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

# Tokens & Chains

> Working with supported tokens and chains in the Trails SDK

## Overview

The Trails SDK provides utilities to query supported chains and tokens across the network. These functions help you build dynamic UIs that adapt to available options.

## Chain Utilities

```ts theme={null}
import {
  getSupportedChains,
  useSupportedChains,
  getChainInfo,
  getAllChains,
  type Chain,
} from '0xtrails'
```

### Fetching Supported Chains

**As a hook (React):**

```tsx theme={null}
import { useSupportedChains } from '0xtrails'

function ChainSelector() {
  const { supportedChains, isLoadingChains } = useSupportedChains()
  
  if (isLoadingChains) return <div>Loading chains...</div>
  
  return (
    <select>
      {supportedChains.map(chain => (
        <option key={chain.id} value={chain.id}>
          {chain.name} (ID: {chain.id})
        </option>
      ))}
    </select>
  )
}
```

**As a function (async):**

```ts theme={null}
import { getSupportedChains } from '0xtrails'

const chains = await getSupportedChains()
console.log('Available chains:', chains)
```

### Getting Chain Information

```ts theme={null}
import { getChainInfo } from '0xtrails'

// Get specific chain info
const baseChain = getChainInfo(8453)
console.log(baseChain?.name) // "Base"
console.log(baseChain?.nativeCurrency.symbol) // "ETH"
```

### Chain Type

```ts theme={null}
import { type Chain } from 'viem'

type Chain = {
  id: number
  name: string
  rpcUrls: string[]
  nativeCurrency: {
    name: string
    symbol: string
    decimals: number
  }
  blockExplorerUrls?: string[]
  imageUrl?: string
  ...
}
```

## Token Utilities

```ts theme={null}
import {
  getSupportedTokens,
  useSupportedTokens,
  useTokenList,
  type Token,
} from '0xtrails'
```

### Fetching Supported Tokens

**All tokens (hook):**

```tsx theme={null}
import { useTokenList } from '0xtrails'

function TokenList() {
  const { tokens, isLoadingTokens } = useTokenList()
  
  if (isLoadingTokens) return <div>Loading tokens...</div>
  
  return (
    <ul>
      {tokens?.map(token => (
        <li key={`${token.chainId}-${token.contractAddress}`}>
          {token.symbol} on {token.chainName}
        </li>
      ))}
    </ul>
  )
}
```

**Filtered by chain (hook):**

```tsx theme={null}
import { useSupportedTokens } from '0xtrails'

function BaseTokens() {
  const { supportedTokens, isLoadingTokens } = useSupportedTokens({
    chainId: 8453 // Base chain
  })
  
  return (
    <select>
      {supportedTokens.map(token => (
        <option key={`${token.chainId}-${token.contractAddress}`} value={token.contractAddress}>
          {token.symbol} - {token.name}
        </option>
      ))}
    </select>
  )
}
```

**As a function (async):**

```ts theme={null}
import { getSupportedTokens } from '0xtrails'

const tokens = await getSupportedTokens()
const usdcTokens = tokens.filter(t => t.symbol === 'USDC')
console.log('USDC available on:', usdcTokens.map(t => t.chainName))
```

### Token Type

The unified `Token` type is used throughout the SDK:

```ts theme={null}
type Token = {
  // Required properties
  symbol: string
  name: string
  decimals: number
  contractAddress: string // Use zeroAddress for native tokens

  // Optional properties
  tokenId?: string
  chainId?: number
  chainName?: string
  imageUrl?: string
  isCustomToken?: boolean
  isNativeToken?: boolean

  // Balance fields (populated when fetched with balances)
  balance?: string
  balanceFormatted?: string
  balanceDisplay?: string
  balanceUsd?: number
  balanceUsdFormatted?: string
  balanceUsdDisplay?: string

  // Price fields
  priceUsd?: number
  priceUsdFormatted?: string
  priceUsdDisplay?: string
}
```

## Practical Examples

### Dynamic Chain and Token Selectors

```tsx theme={null}
import { useSupportedChains, useSupportedTokens } from '0xtrails'
import { useState } from 'react'

function CrossChainSelector() {
  const [selectedChain, setSelectedChain] = useState<number>()
  
  const { supportedChains } = useSupportedChains()
  const { supportedTokens } = useSupportedTokens({
    chainId: selectedChain
  })
  
  return (
    <div>
      <select onChange={(e) => setSelectedChain(Number(e.target.value))}>
        <option value="">Select chain</option>
        {supportedChains.map(chain => (
          <option key={chain.id} value={chain.id}>
            {chain.name}
          </option>
        ))}
      </select>
      
      {selectedChain && (
        <select>
          <option value="">Select token</option>
          {supportedTokens.map(token => (
            <option key={`${token.chainId}-${token.contractAddress}`} value={token.contractAddress}>
              {token.symbol} - {token.name}
            </option>
          ))}
        </select>
      )}
    </div>
  )
}
```

### Finding Token Address by Symbol

```ts theme={null}
import { getSupportedTokens } from '0xtrails'

async function getTokenAddress(symbol: string, chainId: number) {
  const tokens = await getSupportedTokens()
  const token = tokens.find(
    t => t.symbol === symbol && t.chainId === chainId
  )
  return token?.contractAddress
}

// Usage
const usdcOnBase = await getTokenAddress('USDC', 8453)
console.log('USDC on Base:', usdcOnBase)
```

### Checking Token Availability

```tsx theme={null}
import { useSupportedTokens } from '0xtrails'

function TokenAvailability({ symbol, chainId }: { symbol: string, chainId: number }) {
  const { supportedTokens } = useSupportedTokens({ chainId })
  
  const isAvailable = supportedTokens.some(t => t.symbol === symbol)
  
  return (
    <div>
      {symbol} is {isAvailable ? 'available' : 'not available'} on this chain
    </div>
  )
}
```

## See Also

* [Supported Chains](/resources/supported-chains) - Complete list of supported networks
* [Hooks](/sdk/hooks) - Complete SDK hooks reference
* [Configuration](/sdk/configuration) - Widget configuration options