Skip to main content

​
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

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 Image URLs

import { getChainImageUrl, useChainImageUrl } from '0xtrails'

// Get chain image URL directly
const imageUrl = getChainImageUrl(8453)
// Returns: "https://assets.sequence.info/images/networks/large/8453.webp"

// As a React hook
function ChainIcon({ chainId }: { chainId: number }) {
  const imageUrl = useChainImageUrl(chainId)
  return <img src={imageUrl} alt="Chain logo" />
}

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

​
See Also