CAIP-19 currency identifiers

BTC Direct API v1 and v2 support CAIP-19: a chain-agnostic standard for uniquely identifying blockchain assets. This allows you to reference currencies by their canonical on-chain identity rather than BTC Direct’s internal currency codes.

This is especially useful when:

Your application already tracks assets by on-chain identifier
You need to distinguish multi-network tokens unambiguously (e.g. USDC on Ethereum vs. USDC on Solana)

CAIP-19 format

A CAIP-19 identifier follows this structure:

{chain_id}/{asset_namespace}:{asset_reference}

Some examples for currencies available on BTC Direct:

Currency	CAIP-19 identifier
Bitcoin	`bip122:000000000019d6689c085ae165831e93/slip44:0`
Ethereum	`eip155:1/slip44:60`
Euro	`swift:0/iso4217:EUR`
USDC (Solana)	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`

CAIP-19 in API responses

All v2 endpoints that return currency information include sourceCurrency and targetCurrency objects containing the CAIP-19 identifier alongside the code, ticker, and name.

Currency object

{
  "code": "USDC_SOL",
  "ticker": "USDC",
  "name": "USD Coin (Solana)",
  "caip19": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}

Endpoints that include CAIP-19 identifiers in their responses:

Endpoint	Field(s)
`GET /api/v2/prices`	`{pair}.sourceCurrency`, `{pair}.targetCurrency`
`GET /api/v2/buy/orders/{id}`	`sourceCurrency`, `targetCurrency`
`GET /api/v2/sell/orders/{id}`	`sourceCurrency`, `targetCurrency`
`GET /api/v2/user/dca-codes`	`targetCurrency`
`POST /api/v2/buy/checkout`	`sourceCurrency`, `targetCurrency` (response)

Example: prices response

{
  "BTC-EUR": {
    "sourceCurrency": {
      "code": "BTC",
      "ticker": "BTC",
      "name": "Bitcoin",
      "caip19": "bip122:000000000019d6689c085ae165831e93/slip44:0"
    },
    "targetCurrency": {
      "code": "EUR",
      "ticker": "EUR",
      "name": "Euro",
      "caip19": "swift:0/iso4217:EUR"
    },
    "buy": 54355.90,
    "sell": 52722.66
  }
}

Using CAIP-19 in requests

On quote and order creation endpoints, you can identify currencies using CAIP-19 by providing sourceCurrency and targetCurrency. When both fields are present, they take precedence over the standard currency parameters ( currencyPair in v1, baseCurrency / quoteCurrency in v2).

The direction of the order determines which currency maps to which field:

Order type	`sourceCurrency`	`targetCurrency`
Buy: fiat to crypto (F2C)	Fiat (e.g. EUR)	Crypto (e.g. BTC)
Sell: crypto to fiat (C2F)	Crypto (e.g. BTC)	Fiat (e.g. EUR)

In short: source is what the customer sends, target is what they receive.

V1: buy quote (F2C)

POST /api/v1/buy/quote

{
  "sourceCurrency": "swift:0/iso4217:EUR",
  "targetCurrency": "bip122:000000000019d6689c085ae165831e93/slip44:0",
  "paymentMethod": "iDeal",
  "fiatAmount": 100
}

When sourceCurrency and targetCurrency are provided, currencyPair is derived automatically and any currencyPair value in the request is ignored.

V1: sell quote (C2F)

POST /api/v1/sell/quote

{
  "sourceCurrency": "bip122:000000000019d6689c085ae165831e93/slip44:0",
  "targetCurrency": "swift:0/iso4217:EUR",
  "cryptoAmount": 0.01
}

When sourceCurrency and targetCurrency are provided, currencyPair is derived automatically and any currencyPair value in the request is ignored.

V2: checkout (F2C)

POST /api/v2/buy/checkout

{
  "sourceCurrency": "swift:0/iso4217:EUR",
  "targetCurrency": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "paymentMethod": "iDeal",
  "quoteCurrencyAmount": 100
}

When sourceCurrency and targetCurrency are provided, they take precedence over baseCurrency and quoteCurrency.

V2: offer (F2C)

POST /api/v2/buy/offer

{
  "sourceCurrency": "swift:0/iso4217:EUR",
  "targetCurrency": "bip122:000000000019d6689c085ae165831e93/slip44:0",
  "paymentMethod": "iDeal",
  "quoteCurrencyAmount": 100,
  "returnUrl": "https://example.com/return"
}