Skip to content
BitSafe

Instrument ID Management

What Are Instrument IDs?

Section titled “What Are Instrument IDs?”

Every token on Canton is identified by an Instrument ID, a combination of an admin party ID and a token id string, plus a registry URL. These values let any CIP-56-compliant tool discover and interact with CBTC.

Why IDs Change

Section titled “Why IDs Change”

Instrument IDs can change due to network dynamics, including DAR upgrades, network migrations, or infrastructure changes. Never hardcode Instrument IDs. Fetch them dynamically from the metadata URL.

⚠️ There is currently no push notification when Instrument IDs change. Poll the metadata URL periodically.

Current IDs by Network

Section titled “Current IDs by Network”

Devnet

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

Testnet

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

Mainnet

Section titled “Mainnet”
{
 "instrument_id": {
 "admin": "cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262",
 "id": "CBTC"
 },
 "registry_url": "https://api.utilities.digitalasset.com"
}
Section titled “Recommended Polling Pattern”
use std::time::Duration;


// Poll every 5 minutes in production
const POLL_INTERVAL: Duration = Duration::from_secs(300);


async fn refresh_instrument_id(registry_url: &str, admin: &str) -> Result<InstrumentId> {
 let url = format!(
 "{}/api/token-standard/v0/registrars/{}/registry/metadata/v1/instruments",
 registry_url, admin
 );
 let response = reqwest::get(&url).await?.json::<InstrumentMetadata>().await?;
 Ok(response.instrument_id)
}

Best practices:

  • Cache the Instrument ID locally and refresh on a schedule (every 5-15 minutes)
  • Log a warning if the ID changes between polls, as this may indicate a DAR upgrade
  • On startup, always fetch fresh rather than relying on cached values
  • Handle fetch failures gracefully and use the last known good value

Token Standard API Reference

Section titled “Token Standard API Reference”

Full documentation for the Canton Token Standard API: Canton Token Standard Docs

Requirements: CBTC is CIP-56 compliant. No special requirements for holding CBTC.