Tokens (v1)

The token endpoints serve the v1 token list: a curated set of tokens across the v1 chains. Being listed does not guarantee a route for every pair. Only a quote tells you whether one exists.

The token object

Every endpoint below returns tokens in this shape:

{
  "chainId": 1,
  "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "name": "USD Coin",
  "symbol": "USDC",
  "decimals": 6,
  "logoURI": "https://api.hyperstream.dev/v1/tokens/icon/fe4f9d5f34ef4ebeb5d80e1f5ff63dcaf5a0d5495f4adf206e4c3011d1f5c57d.svg",
  "extensions": {
    "price": { "usd": "1.000144065102203723352712851816158", "provider": "okx" }
  }
}

Field	Type	Description
chainId	integer	The chain.
address	string	The token address, lowercase on EVM chains. A chain’s native token is 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee. Pass it as fromToken or toToken unchanged.
name, symbol	string	Display name and symbol.
decimals	integer	Decimals of this token on this chain.
logoURI	string	An SVG icon served by the API.
extensions.price	object	usd, a decimal string, and provider, its source (for example okx, coingecko or kraken). Can be missing.
extensions.balance	string	GET /v1/tokens/balances/{address} only. The wallet’s balance, in base units.

Check that a field exists before you use it. Prices carry many decimals, so round them for display.

List tokens

GET /v1/tokens

Parameter	Description
q	Optional. A search term. With a non-empty q, this behaves like GET /v1/tokens/search.
chainIds	Optional. Comma-separated chain ids.

The response shape depends on q:

• Without q, or with an empty one: a flat array of top tokens. On 19 October 2026 it held 20 tokens.
• With q: an object, { "data": [ … ] }.

curl "https://api.hyperstream.dev/v1/tokens"
curl "https://api.hyperstream.dev/v1/tokens?chainIds=1,42161"
curl "https://api.hyperstream.dev/v1/tokens?q=usdc"

Search tokens

GET /v1/tokens/search

Parameter	Description
q	Required. Name, symbol or address. Without it, the response is 400 ValidationException.
chainIds	Optional. Comma-separated chain ids.

Returns { "data": [ … ] }. As of 19 October 2026, q=usdc with chainIds=1,42161,8453 returned USDC on each of the three chains.

curl "https://api.hyperstream.dev/v1/tokens/search?q=usdc&chainIds=1,42161,8453"

Wallet balances

GET /v1/tokens/balances/{address}

Parameter	Description
address	Path. An EVM, Solana, TRON, Bitcoin or CKB address. Any other value returns 400 ValidationException.
chainIds	Optional. Comma-separated chain ids.

Returns a flat array of the listed tokens the wallet holds, each with extensions.balance in base units:

[
  {
    "chainId": 1,
    "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "name": "Ether",
    "symbol": "ETH",
    "decimals": 18,
    "logoURI": "https://api.hyperstream.dev/v1/tokens/icon/130f400afbc54c9096f4faa98fb61019108f515b1966311c20f4aaf1fde1e0c5.svg",
    "extensions": {
      "price": { "usd": "2399.594302201605853431766388244627", "provider": "okx" },
      "balance": "200000000000000"
    }
  }
]

Autocomplete

GET /v1/tokens/autocomplete/{keyword}

Parses what a user types, such as 100 usdc on base or $50 eth, into token suggestions.

Parameter	Description
keyword	Path. 1 to 64 characters, URL-encoded. Longer input returns 400.
chainIds	Optional. Comma-separated chain ids.
limit	Optional. 1 to 20 suggestions. Default 10. A larger value returns 400.

curl "https://api.hyperstream.dev/v1/tokens/autocomplete/100%20usdc%20on%20ethereum"

As of 19 October 2026 the response was, with the chain object shortened:

{
  "data": [
    {
      "description": "Receive 100 USDC on Ethereum",
      "chain": { "type": "eip155", "id": 1, "name": "Ethereum", "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 } },
      "token": {
        "chainId": 1,
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "logoURI": "https://api.hyperstream.dev/v1/tokens/icon/fe4f9d5f34ef4ebeb5d80e1f5ff63dcaf5a0d5495f4adf206e4c3011d1f5c57d.svg",
        "extensions": { "price": { "usd": "1.000144065102203723352712851816158", "provider": "okx" } }
      },
      "amount": "100000000",
      "usdAmount": "100.0144065102203723"
    }
  ],
  "parsed": { "amount": "100", "tokenQuery": "usdc", "chainQuery": "ethereum", "hasOn": true },
  "nextSlots": ["keyword"]
}

Field	Type	Description
data[].description	string	A label for the suggestion. Receive 100 USDC on Ethereum when the input has an amount; USDC on Ethereum when it does not.
data[].chain	object	The chain, in the GET /v1/chains shape, with extra viem fields on EVM chains.
data[].token	object	The token object, extensions included.
data[].amount	string	Only when the input has an amount: the amount in the token’s base units.
data[].usdAmount	string	Only when the input has an amount and a price is known: its USD value, unrounded.
parsed.amount	string	The number, when the input starts with one (100 usdc).
parsed.usdAmount	string	The dollar amount, when the input starts with $ ($50 eth).
parsed.tokenQuery	string	The token part.
parsed.chainQuery	string	The chain part, after on.
parsed.hasOn	boolean	Whether the input contains on.
nextSlots	string[]	What the user can type next: usdAmount, amount, tokenSymbol, chain or keyword.

nextSlots narrows as the input gets more specific. As of 19 October 2026:

Input	nextSlots
usdc	["usdAmount", "amount", "tokenSymbol", "chain", "keyword"]
usdc on base	["usdAmount", "amount", "tokenSymbol", "chain", "keyword"]
100 usdc	["chain", "keyword"]
$50 eth	["chain", "keyword"]
100 usdc on	["chain", "keyword"]
100 usdc on ethereum	["keyword"]

Errors

Status	name	When
400	ValidationException	A missing q on search, an invalid address, a keyword over 64 characters, or a limit over 20.