​
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:
ChainIdentifierExample Asset
ArbitrumARBARB.ETH
AvalancheAVAXAVAX.AVAX
BaseBASEBASE.ETH
Binance Smart ChainBSCBSC.BNB
BitcoinBTCBTC.BTC
Bitcoin CashBCHBCH.BCH
CosmosGAIAGAIA.ATOM
DashDASHDASH.DASH
DogecoinDOGEDOGE.DOGE
EthereumETHETH.ETH
KujiraKUJIKUJI.KUJI
LitecoinLTCLTC.LTC
Maya ProtocolMAYAMAYA.CACAO
PolkadotDOTDOT.DOT
SolanaSOLSOL.SOL
THORChainTHORTHOR.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"

​
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"
}