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

# Assets & Balances

> Retrieve supported tokens and query wallet balances across multiple chains

## GET /leokit/assets

Get list of supported tokens with current prices and metadata.

### Request

**Authentication:** `Api-Key` header required

```http theme={null}
GET /leokit/assets
Api-Key: your_api_key_here
```

### Response

**Status Code:** `200 OK`

**Cache:** 20 seconds

```json theme={null}
{
  "tokens": [
    {
      "identifier": "BTC.BTC",
      "blockchain": "BTC",
      "symbol": "BTC",
      "address": "",
      "decimals": 8,
      "price_usd": 98500.45,
      "icon": "https://static.leofinance.io/icons/btc.png",
      "chain_icon": "https://static.leofinance.io/chains/btc.png",
      "coingecko_id": "bitcoin"
    },
    {
      "identifier": "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "blockchain": "ETH",
      "symbol": "USDC",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "decimals": 6,
      "price_usd": 1.0001,
      "icon": "https://static.leofinance.io/icons/usdc.png",
      "chain_icon": "https://static.leofinance.io/chains/eth.png",
      "coingecko_id": "usd-coin"
    },
    {
      "identifier": "THOR.RUNE",
      "blockchain": "THOR",
      "symbol": "RUNE",
      "address": "",
      "decimals": 8,
      "price_usd": 4.25,
      "icon": "https://static.leofinance.io/icons/rune.png",
      "chain_icon": "https://static.leofinance.io/chains/thor.png",
      "coingecko_id": "thorchain"
    }
  ]
}
```

### Asset Format

Each asset object contains the following fields:

| Field          | Type   | Description                                                 |
| -------------- | ------ | ----------------------------------------------------------- |
| `identifier`   | string | Unique asset identifier in format `CHAIN.SYMBOL[-ADDRESS]`  |
| `blockchain`   | string | Blockchain short name (e.g., "BTC", "ETH", "THOR")          |
| `symbol`       | string | Token symbol (e.g., "BTC", "USDC", "RUNE")                  |
| `address`      | string | Contract address for tokens, empty string for native assets |
| `decimals`     | number | Number of decimal places for the token                      |
| `price_usd`    | number | Current USD price                                           |
| `icon`         | string | URL to token icon image                                     |
| `chain_icon`   | string | URL to blockchain icon image                                |
| `coingecko_id` | string | CoinGecko API identifier for price tracking                 |

### Asset Identifier Format

The `identifier` field uses a standardized format:

* **Native Assets:** `CHAIN.SYMBOL` (e.g., "BTC.BTC", "ETH.ETH", "THOR.RUNE")
* **Token Assets:** `CHAIN.SYMBOL-ADDRESS` (e.g., "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")

### Filtering Rules

The API automatically filters assets based on:

1. **Price Filter:** Tokens with `price_usd < $0.001` are excluded
2. **Banned Chains:** Chains in `BANNED_CHAINS` constant are filtered out
3. **Client Configuration:** Tokens on chains in client's `disabled_chains` are excluded
4. **Client-Specific Tokens:** Tokens from `custom_evm_tokens` table included if `client_api_key` matches

### Data Sources

* **Primary:** Supabase `tokens` table (updated every 5 minutes)
* **Secondary:** `custom_evm_tokens` table for client-specific additions

## GET /leokit/v2/assets

Same data as `/leokit/assets` but in a **compact gzipped binary format** — \~170 KB on the wire vs \~3 MB JSON. Useful for mobile apps, embedded widgets, or any payload-sensitive client.

The format is documented in detail at [Assets v2 (Compact Binary)](/api-reference/endpoint/v2-assets), including the wire layout and a TypeScript decoder.

```bash theme={null}
curl -H "Api-Key: YOUR_API_KEY" \
  -H "Accept-Encoding: gzip" \
  https://api.leokit.dev/leokit/v2/assets \
  --output assets.bin.gz
```

Both endpoints serve the same per-client filtered universe. Pick `/leokit/v2/assets` when payload size matters; pick `/leokit/assets` when you want full per-token JSON metadata (icons, coingecko\_id, etc.).

## POST /leokit/balances

Get wallet balances across multiple chains in a single request.

### Request Body

```json theme={null}
[
  {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "chain": "ETH"
  },
  {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "chain": "BTC"
  },
  {
    "address": "thor1abc...",
    "chain": "THOR"
  }
]
```

**Request Format:** Array of wallet objects

| Field     | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `address` | string | Yes      | Wallet address for the chain        |
| `chain`   | string | Yes      | Blockchain short name (e.g., "ETH") |

### Response

**Status Code:** `200 OK`

```json theme={null}
{
  "wallets": [
    {
      "chain": "ETH",
      "balances": [
        {
          "token_symbol": "ETH",
          "price": 3500.25,
          "balance": 2.5,
          "balance_usd": 8750.625,
          "icon": "https://static.leofinance.io/icons/eth.png"
        },
        {
          "token_symbol": "USDC",
          "price": 1.0001,
          "balance": 5000,
          "balance_usd": 5000.5,
          "icon": "https://static.leofinance.io/icons/usdc.png"
        }
      ],
      "explorer": "https://etherscan.io/address/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "balance_usd": 13751.125
    },
    {
      "chain": "BTC",
      "balances": [
        {
          "token_symbol": "BTC",
          "price": 98500.45,
          "balance": 1.25,
          "balance_usd": 123125.5625,
          "icon": "https://static.leofinance.io/icons/btc.png"
        }
      ],
      "explorer": "https://blockchain.com/btc/address/bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "balance_usd": 123125.5625
    },
    {
      "chain": "THOR",
      "balances": [
        {
          "token_symbol": "RUNE",
          "price": 4.25,
          "balance": 1000,
          "balance_usd": 4250,
          "icon": "https://static.leofinance.io/icons/rune.png"
        },
        {
          "token_symbol": "sTCY",
          "price": 0.15,
          "balance": 5000,
          "balance_usd": 750,
          "icon": "https://static.leofinance.io/icons/tcy.png"
        }
      ],
      "explorer": "https://runescan.io/address/thor1abc...",
      "balance_usd": 5000
    }
  ]
}
```

### Response Format

Each wallet object contains:

| Field         | Type   | Description                               |
| ------------- | ------ | ----------------------------------------- |
| `chain`       | string | Blockchain short name                     |
| `balances`    | array  | Array of token balance objects            |
| `explorer`    | string | Block explorer URL for the wallet address |
| `balance_usd` | number | Total USD value of all tokens in wallet   |

### Token Balance Object

Each balance object contains:

| Field          | Type   | Description                        |
| -------------- | ------ | ---------------------------------- |
| `token_symbol` | string | Token symbol (e.g., "ETH", "USDC") |
| `price`        | number | Current USD price per token        |
| `balance`      | number | Token balance (in readable units)  |
| `balance_usd`  | number | USD value of token balance         |
| `icon`         | string | URL to token icon image            |

## Supported Chains (30+)

### EVM Chains

* **ETH** (Ethereum)
* **ARB** (Arbitrum)
* **AVAX** (Avalanche C-Chain)
* **BASE** (Base)
* **BSC** (Binance Smart Chain)
* **POLYGON** (Polygon/Matic)
* **OPTIMISM** (Optimism)
* **FANTOM** (Fantom Opera)

### UTXO Chains

* **BTC** (Bitcoin)
* **LTC** (Litecoin)
* **BCH** (Bitcoin Cash)
* **DASH** (Dash)
* **ZEC** (Zcash)
* **DOGE** (Dogecoin)

### Cosmos Chains

* **THOR** (THORChain)
* **MAYA** (MAYAChain)
* **GAIA** (Cosmos Hub)
* **KUJI** (Kujira)

### Other Chains

* **XRP** (Ripple)
* **NEAR** (NEAR Protocol)
* **SOL** (Solana)
* **TRON** (Tron Network)

## Features

### Balance Fetching

* **Parallel Fetching:** All chains queried simultaneously for optimal speed
* **Scam Filter:** Tokens with `balance_usd < $0.10` are automatically excluded
* **Staked Assets:** THORChain staked TCY (sTCY) automatically included for THOR wallets
* **Multi-Chain Aggregation:** Uses Rango API for broad chain support
* **Chain-Specific Fetchers:** Manual implementations for BTC, XRP, NEAR, and other specialized chains

### Data Sources

* **Rango API:** Primary aggregator for most EVM and Cosmos chains
* **Custom Fetchers:** Direct blockchain queries for BTC, XRP, NEAR
* **THORChain API:** For RUNE and staked TCY balances
* **Token Prices:** Real-time prices from CoinGecko via the `tokens` table

## Example Use Cases

### Building a Portfolio Dashboard

```javascript theme={null}
// Request balances for multiple wallets
const wallets = [
  { address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", chain: "ETH" },
  { address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", chain: "BTC" },
  { address: "thor1abc...", chain: "THOR" }
];

const response = await fetch('/leokit/balances', {
  method: 'POST',
  headers: {
    'Api-Key': 'your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(wallets)
});

const data = await response.json();

// Calculate total portfolio value
const totalValue = data.wallets.reduce((sum, wallet) => sum + wallet.balance_usd, 0);
console.log(`Total Portfolio Value: $${totalValue.toFixed(2)}`);
```

### Token Selector with Prices

```javascript theme={null}
// Fetch all supported assets
const response = await fetch('/leokit/assets', {
  headers: {
    'Api-Key': 'your_api_key'
  }
});

const { tokens } = await response.json();

// Filter tokens by chain
const ethereumTokens = tokens.filter(token => token.blockchain === 'ETH');

// Sort by USD price
const sortedTokens = tokens.sort((a, b) => b.price_usd - a.price_usd);
```