Asset Notation

Overview

dKit uses a standardized notation system to identify assets across different blockchains. This ensures consistency and clarity when specifying assets for swaps.

Asset Format

Assets are identified using one of two formats:

Native Assets

CHAIN.SYMBOL

Native blockchain assets (gas tokens) use a simple format with the chain identifier and symbol. Examples:

ETH.ETH - Native Ethereum
BTC.BTC - Native Bitcoin
SOL.SOL - Native Solana
AVAX.AVAX - Native Avalanche
THOR.RUNE - THORChain’s native RUNE

Tokens

CHAIN.SYMBOL-ADDRESS

Non-native tokens include the contract address to ensure uniqueness. Examples:

ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48 - USDC on Ethereum
ARB.USDC-0XAF88D065E77C8CC2239327C5EDB3A432268E5831 - USDC on Arbitrum
ETH.WBTC-0X2260FAC5E5542A773AA44FBCFEDF7C193BC2C599 - Wrapped Bitcoin on Ethereum
SOL.USDC-EPJFWDD5AUFQSSQEM2QN1XZYBAPC8G4WEGGKZWYTDT1V - USDC on Solana

Chain Identifiers

Common chain identifiers used in the API:

Chain	Identifier	Example Asset
Arbitrum	`ARB`	`ARB.ETH`
Avalanche	`AVAX`	`AVAX.AVAX`
Base	`BASE`	`BASE.ETH`
Binance Smart Chain	`BSC`	`BSC.BNB`
Bitcoin	`BTC`	`BTC.BTC`
Bitcoin Cash	`BCH`	`BCH.BCH`
Cosmos	`GAIA`	`GAIA.ATOM`
Dash	`DASH`	`DASH.DASH`
Dogecoin	`DOGE`	`DOGE.DOGE`
Ethereum	`ETH`	`ETH.ETH`
Kujira	`KUJI`	`KUJI.KUJI`
Litecoin	`LTC`	`LTC.LTC`
Maya Protocol	`MAYA`	`MAYA.CACAO`
Polkadot	`DOT`	`DOT.DOT`
Solana	`SOL`	`SOL.SOL`
THORChain	`THOR`	`THOR.RUNE`

Special Cases

Synthetic Assets

THORChain and MayaChain support synthetic assets that represent assets from other chains:

THOR.BTC - Synthetic Bitcoin on THORChain
THOR.ETH - Synthetic Ethereum on THORChain
MAYA.BTC - Synthetic Bitcoin on MayaChain

Layer 2 Networks

Layer 2 networks have their own chain identifiers:

ARB.ETH - Native ETH on Arbitrum
BASE.ETH - Native ETH on Base
OP.ETH - Native ETH on Optimism

Wrapped Assets

Wrapped assets maintain the original asset symbol but include the wrapper contract address:

ETH.WBTC-0X2260FAC5E5542A773AA44FBCFEDF7C193BC2C599 - Wrapped Bitcoin
ETH.WETH-0XC02AAA39B223FE8D0A0E5C4F27EAD9083C756CC2 - Wrapped Ethereum

Address Formats

Different chains use different address formats:

// Ethereum and EVM-compatible chains
// 42-character hex string starting with 0x
const evmAddress = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"

// Token addresses are also 42-character hex strings
const usdcAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

// Bitcoin addresses (multiple formats supported)
// Legacy (P2PKH)
const legacyAddress = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

// SegWit (P2WPKH)
const segwitAddress = "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"

// Taproot (P2TR)
const taprootAddress = "bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr"

// Solana uses Base58 encoded addresses
const solanaAddress = "7VJsBtJzgTftYzEeooSDYyjKXvYRWJHdwvbwfBvTg9K"

// SPL token addresses are also Base58
const splTokenMint = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

// Cosmos ecosystem uses Bech32 addresses
const cosmosAddress = "cosmos1vx8knpllrj7n963p9ttd80w47kpacrhuts497x"
const thorchainAddress = "thor1vx8knpllrj7n963p9ttd80w47kpacrhuts497x"
const mayaAddress = "maya1vx8knpllrj7n963p9ttd80w47kpacrhuts497x"

Asset Discovery

Finding Available Assets

Use the /tokens endpoint to discover available assets:

// Get all available tokens
const response = await fetch('https://api.dkit.xyz/v1/tokens');
const tokenLists = await response.json();

// Get tokens for a specific provider
const thorchainTokens = await fetch('https://api.dkit.xyz/v1/tokens?provider=THORCHAIN');

Checking Asset Connectivity

Use the /connected-assets endpoint to find what assets can be swapped:

// Find all assets that can be swapped from ETH
const response = await fetch('https://api.dkit.xyz/v1/connected-assets?asset_id=ETH.ETH');
const connectedAssets = await response.json();

// Returns object with asset IDs as keys
// {
//   "BTC.BTC": 1,
//   "SOL.SOL": 1,
//   "ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48": 1,
//   ...
// }

Best Practices

1. Case Sensitivity

Chain and symbol identifiers are case-sensitive. Always use uppercase:

// ✅ Correct
"ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48"

// ❌ Incorrect
"eth.usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

2. Address Validation

Always validate addresses before making requests:

const isValidEVMAddress = (address) => {
  return /^0x[a-fA-F0-9]{40}$/i.test(address);
};

const isValidBitcoinAddress = (address) => {
  // Simplified check - use proper library in production
  return /^(bc1|[13])[a-zA-HJ-NP-Z0-9]{25,87}$/.test(address);
};

3. Token Disambiguation

Always use the full identifier with address for tokens to avoid ambiguity:

// ❌ Ambiguous - USDC exists on multiple chains
"ETH.USDC"

// ✅ Specific
"ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48"

4. Chain-Asset Compatibility

Ensure the asset belongs to the specified chain:

// ✅ Correct - BTC on Bitcoin network
"BTC.BTC"

// ❌ Incorrect - BTC doesn't exist natively on Ethereum
"ETH.BTC"

// ✅ Correct - Wrapped BTC on Ethereum
"ETH.WBTC-0X2260FAC5E5542A773AA44FBCFEDF7C193BC2C599"

Common Patterns

Cross-Chain Swaps

// Swap native Bitcoin to native Ethereum
{
  sellAsset: "BTC.BTC",
  buyAsset: "ETH.ETH"
}

// Swap Ethereum USDC to Solana USDC
{
  sellAsset: "ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48",
  buyAsset: "SOL.USDC-EPJFWDD5AUFQSSQEM2QN1XZYBAPC8G4WEGGKZWYTDT1V"
}

Same-Chain Swaps

// Swap ETH to USDC on Ethereum
{
  sellAsset: "ETH.ETH",
  buyAsset: "ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48"
}

// Swap between tokens on Arbitrum
{
  sellAsset: "ARB.USDC-0XAF88D065E77C8CC2239327C5EDB3A432268E5831",
  buyAsset: "ARB.USDT-0XFD086BC7CD5C481DCC9C85EBE478A1C0B69FCBB9"
}

Using Synthetic Assets

// Swap to synthetic BTC on THORChain (faster, lower fees)
{
  sellAsset: "ETH.ETH",
  buyAsset: "THOR.BTC"
}

// Swap from synthetic back to native
{
  sellAsset: "THOR.BTC",
  buyAsset: "BTC.BTC"
}

Monetization

Getting Started

Core Concepts

Overview

Asset Format

Native Assets

Tokens

Chain Identifiers

Special Cases

Synthetic Assets

Layer 2 Networks

Wrapped Assets

Address Formats

Asset Discovery

Finding Available Assets

Checking Asset Connectivity

Best Practices

1. Case Sensitivity

2. Address Validation

3. Token Disambiguation

4. Chain-Asset Compatibility

Common Patterns

Cross-Chain Swaps

Same-Chain Swaps

Using Synthetic Assets

​Overview

​Asset Format

​Native Assets

​Tokens

​Chain Identifiers

​Special Cases

​Synthetic Assets

​Layer 2 Networks

​Wrapped Assets

​Address Formats

​Asset Discovery

​Finding Available Assets

​Checking Asset Connectivity

​Best Practices

​1. Case Sensitivity

​2. Address Validation

​3. Token Disambiguation

​4. Chain-Asset Compatibility

​Common Patterns

​Cross-Chain Swaps

​Same-Chain Swaps

​Using Synthetic Assets

Overview

Asset Format

Native Assets

Tokens

Chain Identifiers

Special Cases

Synthetic Assets

Layer 2 Networks

Wrapped Assets

Address Formats

Asset Discovery

Finding Available Assets

Checking Asset Connectivity

Best Practices

1. Case Sensitivity

2. Address Validation

3. Token Disambiguation

4. Chain-Asset Compatibility

Common Patterns

Cross-Chain Swaps

Same-Chain Swaps

Using Synthetic Assets