GetTokenList - Trails

Overview

The GetTokenList endpoint retrieves a list of tokens available on specified chains. This is useful for building token selection UIs, searching for tokens, and discovering available assets for swaps and transfers.

Use Cases

Build token selector dropdowns
Implement token search functionality
Display featured/popular tokens
Filter tokens by chain
Look up specific token addresses
Exclude certain tokens from selection

Request Parameters

Required Fields

chainIds (number[]): Array of chain IDs to get tokens for

Optional Fields

searchQuery (string): Search tokens by name, symbol, or address
limit (number): Maximum number of tokens to return
tokenAddress (string): Filter to a specific token address
includeAllListed (boolean): Include all listed tokens, not just featured
includeExternal (boolean): Include external/non-native tokens
excludeTokens (string[]): Array of token addresses to exclude

Response

The response includes:

tokens (TokenInfo[]): Array of token information

TokenInfo Object Structure

Each token object contains:

chainId (number): Chain where the token exists
address (string): Token contract address
name (string): Token name
symbol (string): Token symbol
decimals (number): Token decimals
supportsBridging (boolean, optional): Whether the token supports bridging
logoUri (string, optional): URL to token logo
featured (boolean): Whether this is a featured/popular token
featureIndex (number): Sort order for featured tokens

Examples

Get Featured Tokens for Multiple Chains

const response = await fetch('https://trails-api.sequence.app/rpc/Trails/GetTokenList', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    chainIds: [1, 8453, 42161], // Ethereum, Base, Arbitrum
    limit: 20
  })
});

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

console.log('Featured tokens:');
tokens.forEach(token => {
  console.log(`${token.symbol} on chain ${token.chainId}: ${token.address}`);
});

Search for a Token

const response = await fetch('https://trails-api.sequence.app/rpc/Trails/GetTokenList', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    chainIds: [1, 8453, 42161, 137, 10],
    searchQuery: 'USDC',
    includeAllListed: true
  })
});

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

console.log('USDC tokens found:');
tokens.forEach(token => {
  console.log(`Chain ${token.chainId}: ${token.address}`);
});

Look Up Specific Token

const response = await fetch('https://trails-api.sequence.app/rpc/Trails/GetTokenList', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    chainIds: [8453], // Base
    tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' // USDC
  })
});

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

if (tokens.length > 0) {
  const token = tokens[0];
  console.log(`Found: ${token.name} (${token.symbol})`);
  console.log(`Decimals: ${token.decimals}`);
  console.log(`Supports bridging: ${token.supportsBridging}`);
}

Build Token Selector with Search

import { useEffect, useState, useCallback } from 'react';
import { debounce } from 'lodash';

interface TokenInfo {
  chainId: number;
  address: string;
  name: string;
  symbol: string;
  decimals: number;
  logoUri?: string;
  featured: boolean;
}

interface TokenSelectorProps {
  chainIds: number[];
  onSelect: (token: TokenInfo) => void;
  excludeAddresses?: string[];
}

export const TokenSelector = ({
  chainIds,
  onSelect,
  excludeAddresses = []
}: TokenSelectorProps) => {
  const [tokens, setTokens] = useState<TokenInfo[]>([]);
  const [searchQuery, setSearchQuery] = useState('');
  const [loading, setLoading] = useState(true);

  const fetchTokens = useCallback(async (query: string) => {
    setLoading(true);
    
    const response = await fetch('https://trails-api.sequence.app/rpc/Trails/GetTokenList', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Access-Key': 'YOUR_API_KEY'
      },
      body: JSON.stringify({
        chainIds,
        searchQuery: query || undefined,
        includeAllListed: !!query,
        excludeTokens: excludeAddresses,
        limit: 50
      })
    });

    const { tokens } = await response.json();
    setTokens(tokens);
    setLoading(false);
  }, [chainIds, excludeAddresses]);

  // Debounced search
  const debouncedSearch = useCallback(
    debounce((query: string) => fetchTokens(query), 300),
    [fetchTokens]
  );

  useEffect(() => {
    fetchTokens('');
  }, [fetchTokens]);

  useEffect(() => {
    if (searchQuery) {
      debouncedSearch(searchQuery);
    }
  }, [searchQuery, debouncedSearch]);

  return (
    <div>
      <input
        type="text"
        placeholder="Search tokens..."
        value={searchQuery}
        onChange={(e) => setSearchQuery(e.target.value)}
      />
      
      {loading ? (
        <div>Loading...</div>
      ) : (
        <ul>
          {tokens.map(token => (
            <li
              key={`${token.chainId}-${token.address}`}
              onClick={() => onSelect(token)}
            >
              {token.logoUri && (
                <img src={token.logoUri} alt={token.symbol} width={24} />
              )}
              <span>{token.symbol}</span>
              <span>{token.name}</span>
              <span>Chain {token.chainId}</span>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
};

Get All Tokens Including External

const response = await fetch('https://trails-api.sequence.app/rpc/Trails/GetTokenList', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    chainIds: [8453], // Base
    includeAllListed: true,
    includeExternal: true,
    limit: 100
  })
});

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

console.log(`Found ${tokens.length} tokens on Base`);

Exclude Specific Tokens

// Exclude native tokens from the list
const response = await fetch('https://trails-api.sequence.app/rpc/Trails/GetTokenList', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    chainIds: [1],
    excludeTokens: [
      '0x0000000000000000000000000000000000000000', // Native ETH
      '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'  // WETH
    ],
    limit: 20
  })
});

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

Filtering Tips

Use Case	Parameters
Featured tokens only	Default (no extra params)
All tokens	`includeAllListed: true`
Search by name/symbol	`searchQuery: "USDC"`
Specific token lookup	`tokenAddress: "0x..."`
Exclude tokens	`excludeTokens: ["0x...", "0x..."]`

Featured tokens are curated for popularity and liquidity. Use includeAllListed for comprehensive token lists.

Next Steps

GetChains

Get supported chains for token selection

GetTokenPrices

Get USD prices for selected tokens

Authorizations

X-Access-Key

string

header

required

API Key for authenticating requests, get an access key at https://trails.build and request early access

Body

application/json

chainIds

number[]

required

[]uint64

searchQuery

string

limit

number

tokenAddress

string

includeAllListed

boolean

includeExternal

boolean

excludeTokens

string[]

[]string

Response

Successful response

tokens

object[]

required

[]TokenInfo

Show child attributes

tokens.chainId

number

required

tokens.address

string

required

tokens.name

string

required

tokens.symbol

string

required

tokens.decimals

number

required

tokens.featured

boolean

required

tokens.featureIndex

number

required

tokens.supportsBridging

boolean

tokens.logoUri

string

Overview

Endpoints

​Overview

​Use Cases

​Request Parameters

​Required Fields

​Optional Fields

​Response

​TokenInfo Object Structure

​Examples

​Get Featured Tokens for Multiple Chains

​Search for a Token

​Look Up Specific Token

​Build Token Selector with Search

​Get All Tokens Including External

​Exclude Specific Tokens

​Filtering Tips

​Next Steps

GetChains

GetTokenPrices

Authorizations

Body

Response

Overview

Use Cases

Request Parameters

Required Fields

Optional Fields

Response

TokenInfo Object Structure

Examples

Get Featured Tokens for Multiple Chains

Search for a Token

Look Up Specific Token

Build Token Selector with Search

Get All Tokens Including External

Exclude Specific Tokens

Filtering Tips

Next Steps