Tokens & Chains

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.

Edge Chains

Trails extends beyond EVM networks to edge chains — non-EVM ecosystems reached through edge rails. All alternative-VM chains are edge chains: funding from an edge-chain wallet settles into any supported EVM chain, and back, with Trails handling the cross-ecosystem routing. Edge chains are handled at the quote and execution layer — useQuote and useTrailsSendTransaction accept an edge chain anywhere they accept an EVM chain, and the Chain and Token types are chain-agnostic. Edge chains use their ecosystem-native chain IDs and address formats rather than EVM conventions. Not every hook is edge-aware: the chain/token list and balance utilities below are EVM-only. See Hooks → Edge chains for the exact per-hook support matrix and the edge execution model.

For the current list of supported edge chains and their tokens, see Supported Chains.

Chain Utilities

import {
  getSupportedChains,
  useSupportedChains,
  getChainInfo,
  getAllChains,
  type Chain,
} from '0xtrails'

Fetching Supported Chains

As a hook (React):

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):

import { getSupportedChains } from '0xtrails'

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

Getting Chain Information

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

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

import {
  getSupportedTokens,
  useSupportedTokens,
  useTokenList,
  type Token,
} from '0xtrails'

Fetching Supported Tokens

All tokens (hook):

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):

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):

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:

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

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

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

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>
  )
}

SDK Documentation

Tokens & Chains

Overview

Edge Chains

Chain Utilities

Fetching Supported Chains

Getting Chain Information

Chain Type

Token Utilities

Fetching Supported Tokens

Token Type

Practical Examples

Dynamic Chain and Token Selectors

Finding Token Address by Symbol

Checking Token Availability

See Also

​Overview

​Edge Chains

​Chain Utilities

​Fetching Supported Chains

​Getting Chain Information

​Chain Type

​Token Utilities

​Fetching Supported Tokens

​Token Type

​Practical Examples

​Dynamic Chain and Token Selectors

​Finding Token Address by Symbol

​Checking Token Availability

​See Also

Overview

Edge Chains

Chain Utilities

Fetching Supported Chains

Getting Chain Information

Chain Type

Token Utilities

Fetching Supported Tokens

Token Type

Practical Examples

Dynamic Chain and Token Selectors

Finding Token Address by Symbol

Checking Token Availability

See Also