CBTC API Reference

⚠️ API Stability Notice: All endpoints and interfaces are subject to change without notice. There is no formal versioning policy today. Breaking changes are communicated via the site changelog.

---

CBTC SDK Reference: cbtc-lib (Rust)

For most integrations, we recommend using cbtc-lib (Rust) rather than raw API calls:

• Repository: github.com/DLC-link/cbtc-lib
• Current version: v0.9.0
• Crate name: cbtc (add via cbtc = { git = "ssh://git@github.com/DLC-link/cbtc-lib.git", tag = "v0.9.0" })
• Lower-level library: github.com/DLC-link/canton-lib (v0.11.0)
• Code examples: github.com/DLC-link/cbtc-lib/tree/main/examples
• Setup guide: SDK Setup and Installation

---

Overview: Canton Ledger API for CBTC Operations

All CBTC operations (minting, burning, transferring wrapped Bitcoin) are performed through the Canton Ledger API (also called the JSON Ledger API). There is no separate “CBTC API.” You interact with CBTC by exercising choices on Daml smart contracts running on your Canton participant node.

Base URL: https://<your-participant-host>/v2/

Authentication: Bearer token (JWT) from your OIDC provider. See the Authentication Guide.

Content-Type: application/json for all requests.

---

Prerequisites

Before calling any CBTC API:

1. Canton participant node running and connected to the network
2. CBTC DAR files installed on your participant - download from GitHub
3. Valid JWT from your OIDC provider (Keycloak officially supported)
4. Party ID allocated on your participant

---

Canton Ledger API Endpoints

For full endpoint documentation covering the Canton Ledger API (including all endpoints used by CBTC operations), refer to the official Canton documentation:

Canton JSON Ledger API Documentation →

---

CBTC Instrument ID Management: Devnet, Testnet, and Mainnet

CBTC uses the Canton Token Standard. To interact with CBTC programmatically, you need the correct Instrument ID for your target network.

⚠️ Instrument IDs differ across networks (devnet, testnet, mainnet). Always fetch the latest from the metadata URL rather than hardcoding.

Devnet

{
 "instrument_id": {
 "admin": "cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff",
 "id": "CBTC"
 },
 "registry_url": "https://api.utilities.digitalasset-dev.com"
}

Metadata: View

Testnet

{
 "instrument_id": {
 "admin": "cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f",
 "id": "CBTC"
 },
 "registry_url": "https://api.utilities.digitalasset-staging.com"
}

Metadata: View

Mainnet

{
 "instrument_id": {
 "admin": "cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262",
 "id": "CBTC"
 },
 "registry_url": "https://api.utilities.digitalasset.com"
}

Metadata: View

Token Standard API Reference: Canton Token Standard Docs

💡 Polling pattern: Instrument IDs can change due to network dynamics (e.g., DAR upgrades). Query the metadata URL periodically rather than hardcoding values. There is currently no push notification for ID changes - this is a known gap.

---

Rate Limits

There are no BitSafe-imposed rate limits on the Canton Ledger API. However:

• Canton network throughput: Transfers take a few seconds each. Approximately 500 transfers per 10-minute period is near the current practical limit.
• Your participant node: Performance depends on your infrastructure. Monitor node resource usage under load.

---

API Error Handling for CBTC Operations

Error	Cause	Resolution
401 Unauthorized	Invalid or expired JWT	Re-authenticate with your OIDC provider
404 Not Found	Contract ID no longer active	Re-query for current contract IDs
409 Conflict	Duplicate command ID	Use a unique commandId per request
UTXO limit exceeded	Too many UTXOs for a party (max 10)	Consolidate UTXOs using cbtc-lib

---