# 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](https://github.com/DLC-link/cbtc-lib)
* **Current version:** v0.3.1
* **Crate name:** `cbtc` (add via `cbtc = { git = "https://github.com/DLC-link/cbtc-lib.git", tag = "v0.3.1" }`)
* **Lower-level library:** [github.com/DLC-link/canton-lib](https://github.com/DLC-link/canton-lib) (v0.3.1)
* **Code examples:** [github.com/DLC-link/cbtc-lib/tree/main/examples](https://github.com/DLC-link/cbtc-lib/tree/main/examples)

> 💡 **Note:** cbtc-lib recently underwent a major restructure (December 2025). If you were using an earlier version, you will need to update your imports. See the [cleanup PR](https://github.com/DLC-link/cbtc-lib/pull/11) for migration details.

***

## 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](https://docs.bitsafe.finance/developers/cbtc-authentication).

**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](https://github.com/DLC-link/cbtc-lib/tree/v0.3.1/cbtc-dars)
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 →**](https://docs.digitalasset.com/build/3.4/explanations/json-api/index.html)

***

## 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

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

**Metadata:** [View](https://api.utilities.digitalasset-dev.com/api/token-standard/v0/registrars/cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff/registry/metadata/v1/instruments)

### Testnet

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

**Metadata:** [View](https://api.utilities.digitalasset-staging.com/api/token-standard/v0/registrars/cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f/registry/metadata/v1/instruments)

### Mainnet

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

**Metadata:** [View](https://api.utilities.digitalasset.com/api/token-standard/v0/registrars/cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262/registry/metadata/v1/instruments)

**Token Standard API Reference:** [Canton Token Standard Docs](https://docs.dev.sync.global/app_dev/token_standard/index.html#api-references)

> 💡 **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        |

***