List Tokens

GET /tokens | Auth: Required

List available tokens, optionally filtered by chain or symbol. Returns token contract addresses and decimals needed for building swap transactions.

Request

Parameters

Query string parameters:

Field	Type	Required	Description
chain	string	No	Filter by chain key (e.g., "base", "solana", "ethereum"). Use values from GET /chains.
search	string	No	Filter by token symbol substring. Case-insensitive.

Example

GET /tokens?chain=base&search=USD

Response

Status: 200 OK

Fields

Field	Type	Description
success	boolean	Always true.
chain	string	The chain key that was queried. Present when chain parameter is provided.
chain_id	number	The numeric chain ID. Present when chain parameter is provided.
tokens	array	List of matching tokens.
tokens[].symbol	string	Token symbol (e.g., "USDC").
tokens[].address	string	Contract address on the specified chain. Native tokens use the zero address.
tokens[].decimals	number	Number of decimal places for the token.

Example

{
  "hl-key">"success": true,
  "hl-key">"chain": "base",
  "hl-key">"chain_id": 8453,
  "hl-key">"tokens": [
    {
      "hl-key">"symbol": "ETH",
      "hl-key">"address": "0x0000000000000000000000000000000000000000",
      "hl-key">"decimals": 18
    },
    {
      "hl-key">"symbol": "WETH",
      "hl-key">"address": "0x4200000000000000000000000000000000000006",
      "hl-key">"decimals": 18
    },
    {
      "hl-key">"symbol": "USDC",
      "hl-key">"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "hl-key">"decimals": 6
    },
    {
      "hl-key">"symbol": "DAI",
      "hl-key">"address": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
      "hl-key">"decimals": 18
    }
  ]
}

Errors

Status	Error	Description
400	"Unknown chain 'xyz'"	The provided chain key does not match any supported chain. Use GET /chains to see valid values.
401	"Invalid or missing API key"	The API key is missing, malformed, or revoked.

Code Examples

curl

-str">"hl-comment"># List all tokens on Base
-kw">curl -str">"https://api.suwappu.bot/v1/agent/tokens?chain=base" \
  -H -str">"Authorization: Bearer suwappu_sk_your_api_key"

-str">"hl-comment"># Search for USDC across all chains
-kw">curl -str">"https://api.suwappu.bot/v1/agent/tokens?search=USDC" \
  -H -str">"Authorization: Bearer suwappu_sk_your_api_key"

Python

import requests

response = requests.get(
    class="hl-str">"https:class="hl-commentclass="hl-str">">//api.suwappu.bot/v1/agent/tokens",
    headers={class="hl-str">"Authorization": class="hl-str">"Bearer suwappu_sk_your_api_key"},
    params={class="hl-str">"chain": class="hl-str">"base", class="hl-str">"search": class="hl-str">"USD"},
)

tokens = response.json()[class="hl-str">"tokens"]
for token in tokens:
    print(fclass="hl-str">"{token[class="hl-str">'symbol']} - {token[class="hl-str">'address']} ({token[class="hl-str">'decimals']} decimals)")

TypeScript

const params = new URLSearchParams({ chain: class="hl-str">"base", search: class="hl-str">"USD" });

const response = await fetch(
  https:class=class="hl-str">"hl-comment">//api.suwappu.bot/v1/agent/tokens?${params},
  {
    headers: { Authorization: class="hl-str">"Bearer suwappu_sk_your_api_key" },
  }
);

const { tokens } = await response.json();
tokens.forEach((token) => {
  console.log(${token.symbol} - ${token.address} (${token.decimals} decimals));
});