Token Info

Get detailed metadata and realtime price information for any native asset or ERC20 token including symbol, name, decimals, supply information, USD pricing, and logo URLs.

The Tokens API provides metadata and realtime pricing information for native and ERC20 tokens on supported EVM blockchains. The API returns:

• Token metadata (symbol, name, decimals)
• Current USD pricing information
• Supply information
• Logo URLs when available

The ?chain_ids query parameter is mandatory. To learn more about this query parameter, see the Supported Chains page.

Native vs. ERC20 tokens

The address path parameter can be set to native for chain-native assets or to an ERC20 contract address. Include the required ?chain_ids query parameter to select the chain. The response shape differs slightly for native assets vs ERC20 tokens.

Native asset

Use native as the address path parameter.

Native Request Example

GET /v1/evm/token-info/native?chain_ids=1

Native Response Example

{
  "contract_address": "native",
  "tokens": [
    {
      "chain_id": 1,
      "chain": "ethereum",
      "price_usd": 3900.777068,
      "symbol": "ETH",
      "name": "Ethereum",
      "decimals": 18,
      "logo": "https://api.sim.dune.com/beta/token/logo/1"
    }
  ]
}

ERC20 token

Use the token’s contract address as the address path parameter. Additional fields like pool_size, total_supply, and fully_diluted_value may be present.

ERC20 Request Example

GET /v1/evm/token-info/0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca?chain_ids=8453

ERC20 Response Example

{
  "contract_address": "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca",
  "tokens": [
    {
      "chain_id": 8453,
      "chain": "base",
      "price_usd": 0.998997309877106,
      "pool_size": 456370.679451466,
      "total_supply": "8980896607582",
      "fully_diluted_value": 8971891.55125885,
      "symbol": "USDbC",
      "name": "USD Base Coin",
      "decimals": 6,
      "logo": "https://api.sim.dune.com/beta/token/logo/8453/0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca"
    }
  ]
}

Token Prices

Sim looks up prices onchain. We use the most liquid onchain pair to determine a usd price. We return the available liquidity in pool_size as part of the response.

Historical prices

You can request historical point-in-time prices by adding the optional historical_prices query parameter. Use whole numbers to specify the number of hours in the past. You can request up to three offsets. For example, historical_prices=8760 returns the price 8760 hours (approximately 1 year) ago. historical_prices=720,168,24 returns prices 720 hours (1 month) ago, 168 hours (1 week) ago, and 24 hours ago.

The historical_prices query parameter is currently supported only on the EVM Token Info and EVM Balances endpoints.

When set, each token object includes a historical_prices array with one entry per offset:

{
  "tokens": [
    {
      "chain": "base",
      "symbol": "ETH",
      "price_usd": 3897.492219,
      "historical_prices": [
        { "offset_hours": 8760, "price_usd": 2816.557286 },
        { "offset_hours": 720,  "price_usd": 3714.205613 },
        { "offset_hours": 168,  "price_usd": 3798.926195 }
      ]
    }
  ]
}

Percent changes are not returned. You can compute your own percentage differences using the current price_usd and the values in historical_prices[].price_usd.

Pagination

This endpoint uses cursor-based pagination. You can use the limit parameter to define the maximum page size. Results might at times be less than the maximum page size. The next_offset value is included in the initial response and can be utilized to fetch the next page of results by passing it as the offset query parameter in the next request.

You can only use the value from next_offset to set the offset parameter of the next page of results. Using your own offset value will not have any effect.

Compute Unit Cost

The Token Info endpoint has a fixed CU cost of 2 per request. The chain_ids query parameter is required but does not change the CU cost. See the Compute Units page for detailed information.

Headers

X-Sim-Api-Key · string · required

Used for authenticating requests. Provide an API key with a purpose of Sim API. See Authentication.

Path Parameters

address · string · default: 0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca · required

The contract address of the token or 'native' for the native token of the chain

Query Parameters

chain_ids · string · default: 8453 · required

Specify exactly one chain. Accepts a single numeric chain ID (e.g. ?chain_ids=1). Chain names are not accepted. See the Supported Chains Tags section.

historical_prices

Request historical point-in-time prices. Accepts integer | integer[]. Provide whole numbers representing hours in the past, with a maximum of 3 time offsets (e.g. 8760 for 1 year ago or 720,168,24 for 1 month, 1 week, and 1 day ago). When present, each token includes a historical_prices array with one entry per offset.

Required range: x >= 1

limit · integer

This endpoint returns up to the number of supported chains. See Supported Chains to learn more.

Required range: x >= 0

offset · string

The offset to paginate through result sets; this is a cursor being passed from the previous response, only use what the backend returns here

Response

200

application/json

Successful Response

contract_address · string · required

The contract address of the token or 'native' for the native token

tokens · object[] · required

Array of token information across different chains

Show child attributes

next_offset · string

Pagination cursor for the next page of results