> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/developers/cbtc-testnet-guide.md). # CBTC Testnet Guide > ⚠️ **API Disclaimer:** CBTC APIs are subject to change. Testnet behavior may differ from mainnet in some respects (see Parity section below). *** ## Overview: CBTC Testnet for Developers The CBTC testnet is a sandbox environment where developers can experiment with the full mint, burn, and transfer lifecycle using **test BTC** with no real funds at risk. We recommend all integrations start on testnet before deploying to mainnet. *** ## How to Get Testnet CBTC: Three Options ### Option 1: CBTC Testnet Faucet (Recommended) The fastest way to get testnet tokens: [**CBTC Testnet Faucet →**](https://cbtc-faucet.bitsafe.finance/) Simply enter your testnet wallet address and receive testnet CBTC and CC (for gas) instantly. > 💡 **Quick and easy:** No setup required. Just enter your address and go. ### Option 2: Bron Wallet Testnet Environment If the faucet is unavailable or you want a full testnet wallet environment: 1. **Create a new workspace** in [Bron Wallet](https://bron.app/) 2. Enable **Developer settings → Testnet mode** during workspace creation 3. **Create a testnet account** (toggle Testnet ON in account settings) 4. Select a **Trusted third party** (e.g., Qrypt) for key recovery 5. Use the faucet to fund your new testnet account ### Option 3: Mint via Testnet Flow You can also mint testnet CBTC through the same flow as mainnet, using testnet BTC. This is useful for testing the full minting integration: 1. Set up your participant pointing at the **testnet** Canton network 2. Install CBTC DAR files 3. Follow the standard minting flow (see [Minting and Burning Guide](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning)) 4. Use testnet BTC from a Bitcoin testnet faucet *** ## Testnet Environment Details | Property | Testnet | Mainnet | | ------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **Registry URL** | [`https://api.utilities.digitalasset-staging.com`](https://api.utilities.digitalasset-staging.com/) | [`https://api.utilities.digitalasset.com`](https://api.utilities.digitalasset.com/) | | **Coordinator URL** | [`https://testnet.dlc.link/attestor-1`](https://testnet.dlc.link/attestor-1) | [`https://mainnet.dlc.link/attestor-1`](https://mainnet.dlc.link/attestor-1) | | **Instrument ID (admin)** | `cbtc-network::12201b17...508f` | `cbtc-network::12205af3...b262` | | **BTC network** | Bitcoin Testnet | Bitcoin Mainnet | | **Faucet** | [cbtc-faucet.bitsafe.finance](https://cbtc-faucet.bitsafe.finance/) | N/A (real BTC required) | ### Testnet Instrument ID (Full) ```json { "instrument_id": { "admin": "cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-staging.com" } ``` *** ## Testnet vs. Mainnet: What Is the Same and What Differs > 📋 Understanding what is the same and what differs between testnet and mainnet is critical for a smooth production launch. ### ✅ What Is Identical * **DAR files:** Same CBTC Daml packages * **API surface:** Same Canton Ledger API endpoints and Daml template interfaces * **Mint and burn flows:** Same step-by-step process * **Governance model:** Same Attestor threshold approval mechanism * **Token standard:** CIP-56 compliant on both networks ### ⚠️ What Differs * **Attestor set:** Testnet runs a **smaller** Attestor set than mainnet * **Confirmation times:** May be faster on testnet due to less Bitcoin network congestion * **Instrument IDs:** Different across networks - always fetch from the metadata URL, never hardcode * **BTC:** Testnet uses test BTC with no real value * **Faucet availability:** Testnet has a faucet; mainnet requires real BTC ### 🚫 What Is Mocked or Unavailable on Testnet * **Real BTC settlement:** No real Bitcoin is involved * **Production Attestor SLAs:** Testnet Attestors do not carry the same uptime guarantees * **Mainnet fee structure:** Fees on testnet may not reflect production costs *** ## Important Operational Notes > ⚠️ **Testnet may be reset without notice.** Do not rely on testnet state for production planning. Testnet CBTC balances and transaction history may not persist across resets. * Testnet is for **development and testing only** * Do not use testnet data for compliance, reporting, or production decisions * Testnet performance is not indicative of mainnet performance *** ## Migrate from CBTC Testnet to Mainnet: Step-by-Step Checklist When your testnet integration is working, the migration to mainnet involves: 1. **Update your participant config** to point at the mainnet Canton network 2. **Update Instrument IDs** to mainnet values (see [API Reference](https://docs.bitsafe.finance/developers/cbtc-api-reference)) 3. **Update Coordinator URL** to [`https://mainnet.dlc.link/attestor-1`](https://mainnet.dlc.link/attestor-1) 4. **Use real BTC** for minting - the flow is identical 5. **Review authentication** - ensure your production OIDC provider is configured 6. **Test with a small amount first** - mint a minimal amount of CBTC on mainnet before going live *** ## Devnet There is also a **devnet** environment for earlier-stage experimentation. Devnet is less stable than testnet and may be updated more frequently. **Coordinator URL:** [`https://devnet.dlc.link/attestor-2`](https://devnet.dlc.link/attestor-2) ```json { "instrument_id": { "admin": "cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-dev.com" } ``` *** ## Troubleshooting | Issue | Resolution | | ------------------------------------- | ----------------------------------------------------------------------------- | | Faucet not working | Use Bron Wallet testnet setup (Option 2) or contact | | Testnet CBTC balance disappeared | Testnet may have been reset - request new tokens from the faucet | | Minting on testnet takes too long | Check Bitcoin testnet block times - they can be irregular | | Cannot connect to testnet participant | Verify your participant config points to the correct testnet endpoints | **Support:** *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bitsafe.finance/developers/cbtc-testnet-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.