select and import tokens

Use this recipe for the token selector in a swap form. GET /api/v2/tokens returns the starter list. Add address to look up a specific token or wallet to read balances for listed assets.

Load the starter list

Save this as tokens.mjs. It works with Node.js 20 or later and uses no SDK or API key.

export async function loadTokens({ address, wallet } = {}) {
  const url = new URL('https://api.route.fun/api/v2/tokens');
  if (address) url.searchParams.set('address', address);
  if (wallet) url.searchParams.set('wallet', wallet);

  const response = await fetch(url, {
    signal: AbortSignal.timeout(15000),
    redirect: 'error',
  });
  const body = await response.json();
  if (!response.ok) {
    throw new Error(body.error?.message ?? `HTTP ${response.status}`);
  }
  return body;
}

const { tokens } = await loadTokens();
console.table(tokens.map(({ address, symbol, name, decimals }) => ({
  address, symbol, name, decimals,
})));

Render the returned tokens in your picker. Use the contract address as the identifier; two tokens can share a symbol. Filter the starter list locally for text search. This endpoint does not accept a free-text search query or list every token on the chain.

Look up an address

Using the same module, call loadTokens when the user pastes a complete contract address:

const result = await loadTokens({
  address: '0x4a72b9702f991b790788f8afa9e7112541f4e8f8',
});
console.log(result.tokens[0]);

Show the full address before adding an imported token. verified means the token belongs to Route’s reviewed starter list. Metadata lookup and list inclusion do not prove that a token is safe or can be sold.

Add wallet balances

Pass the connected wallet’s public address as wallet. Add address if you also want to check one imported token. Each returned token has a balance string in base units. The response includes blockNumber, coverage and failed. Coverage is limited to listed assets plus the requested token. If failed is greater than zero, label the result as incomplete. An absent token is not proof that the wallet owns none of it. Use each token’s decimals to format amounts, for example with viem’s formatUnits. Keep raw balances as strings or bigint; converting them to a JavaScript number can lose precision.

In your interface

Fetch the starter list when the picker opens. Look up pasted addresses only after they are complete, and discard responses for a previous address or wallet. Show loading, lookup failure and no matching balance as separate states. Next: Compare swap quotes. See the token endpoint for all request and response fields.

start here

tokens and quotes

execute a swap

activity

upcoming swap fees

select and import tokens

Load the starter list

Look up an address

Add wallet balances

In your interface

​Load the starter list

​Look up an address

​Add wallet balances

​In your interface

Load the starter list

Look up an address

Add wallet balances

In your interface