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

***


---

# Agent Instructions: 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:

```
GET https://docs.bitsafe.finance/developers/cbtc-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.