> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arqitech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asset Notation

> Understanding how assets are identified in the Arqitech Router API

## Overview

We use 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:

<CodeGroup>
  ```javascript EVM theme={null}
  // 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"
  ```

  ```javascript Bitcoin theme={null}
  // Bitcoin addresses (multiple formats supported)
  // Legacy (P2PKH)
  const legacyAddress = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

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

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

  ```javascript Solana theme={null}
  // Solana uses Base58 encoded addresses
  const solanaAddress = "7VJsBtJzgTftYzEeooSDYyjKXvYRWJHdwvbwfBvTg9K"

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

  ```javascript Cosmos theme={null}
  // Cosmos ecosystem uses Bech32 addresses
  const cosmosAddress = "cosmos1vx8knpllrj7n963p9ttd80w47kpacrhuts497x"
  const thorchainAddress = "thor1vx8knpllrj7n963p9ttd80w47kpacrhuts497x"
  const mayaAddress = "maya1vx8knpllrj7n963p9ttd80w47kpacrhuts497x"
  ```
</CodeGroup>

## Asset Discovery

### Finding Available Assets

Use the `/tokens` endpoint to discover available assets:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```javascript theme={null}
// ✅ Correct
"ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48"

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

### 2. Address Validation

Always validate addresses before making requests:

```javascript theme={null}
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:

```javascript theme={null}
// ❌ Ambiguous - USDC exists on multiple chains
"ETH.USDC"

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

### 4. Chain-Asset Compatibility

Ensure the asset belongs to the specified chain:

```javascript theme={null}
// ✅ 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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"
}
```