> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sim.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
export const SupportedChains = ({endpoint, title, excludeChains}) => {
const dataState = useState(null);
const data = dataState[0];
const setData = dataState[1];
useEffect(function () {
var url = "https://api.sim.dune.com/v1/evm/supported-chains";
fetch(url, {
method: "GET"
}).then(function (response) {
return response.json();
}).then(function (responseData) {
setData(responseData);
});
}, [endpoint]);
if (data === null) {
return Loading chain information...
;
}
if (!data.chains) {
return No chain data available
;
}
var supportedChains = [];
var totalChains = data.chains.length;
var excludedChainNames = excludeChains || [];
for (var i = 0; i < data.chains.length; i++) {
var chain = data.chains[i];
if (excludedChainNames.indexOf(chain.name) !== -1) continue;
if (endpoint === undefined) {
supportedChains.push(chain);
} else if (chain[endpoint] && chain[endpoint].supported) {
supportedChains.push(chain);
}
}
var count = supportedChains.length;
var endpointName = endpoint ? endpoint.charAt(0).toUpperCase() + endpoint.slice(1).replace(/_/g, " ") : "All";
var accordionTitle = title ? title + " (" + count + ")" : "Supported Chains (" + count + ")";
return
| name |
chain_id |
tags |
{supportedChains.map(function (chain) {
return
{chain.name} |
{chain.chain_id} |
{chain.tags ? chain.tags.join(", ") : ""} |
;
})}
;
};
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](/evm/supported-chains#tags) 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.
```http Native Request Example theme={null}
GET /v1/evm/token-info/native?chain_ids=1
```
```json Native Response Example [expandable] theme={null}
{
"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.
```http ERC20 Request Example theme={null}
GET /v1/evm/token-info/0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca?chain_ids=8453
```
```json ERC20 Response Example [expandable] theme={null}
{
"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:
```json theme={null}
{
"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](/compute-units) page for detailed information.
## OpenAPI
````yaml /openapi.json GET /v1/evm/token-info/{address}
openapi: 3.0.3
info:
title: Sim API
description: >-
The Sim API by Dune provides real-time blockchain data across EVM and SVM
chains. Access token balances, transaction history, on-chain activity, DeFi
positions, NFT collectibles, token information, and webhook subscriptions
through a unified REST API.
version: 1.0.0
license:
name: ''
contact:
name: Dune Support
url: https://docs.sim.dune.com
email: support@dune.com
servers:
- url: https://api.sim.dune.com
security:
- ApiKeyAuth: []
tags:
- name: evm
description: EVM-compatible blockchain endpoints.
- name: svm
description: Solana/SVM blockchain endpoints.
- name: activity
description: On-chain activity feed.
- name: balances
description: Token balances (EVM and SVM).
- name: transactions
description: Transaction history (EVM and SVM).
- name: collectibles
description: NFT and ERC721/ERC1155 holdings.
- name: defi
description: DeFi protocol positions.
- name: supported-chains
description: Supported blockchain networks.
- name: token-info
description: Token metadata and pricing.
- name: token-holders
description: Token holder distribution.
- name: subscriptions
description: >-
Webhook subscription management for real-time on-chain event
notifications.
paths:
/v1/evm/token-info/{address}:
get:
tags:
- evm
- token-info
summary: >-
Get EVM token information for a specified contract address (or the
native token), on any chain.
description: >-
Returns metadata and pricing information for a specific EVM token.
Includes token name, symbol, decimals, current price in USD, and
optionally historical price data when the `historical_prices` parameter
is set.
operationId: getEvmTokenInfo
parameters:
- name: address
in: path
description: >-
The contract address of the token or 'native' for the native token
of the chain
required: true
schema:
type: string
format: address
pattern: ^0x[a-fA-F0-9]{40}$
default: '0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca'
example: '0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca'
- name: chain_ids
in: query
description: >-
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](/evm/supported-chains#tags) section.
required: true
schema:
type: string
default: '8453'
example: '8453'
- name: historical_prices
in: query
description: >-
Request historical point-in-time prices. Provide a single integer or
a comma-separated list of up to 3 integers representing hours in the
past (e.g. `168` for 1 week 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: false
schema:
type: string
examples:
single_offset:
summary: Single offset (1 week ago)
value: '168'
three_offsets:
summary: Three offsets (1 month, 1 week, 1 day ago)
value: 720,168,24
- name: limit
in: query
description: >-
This endpoint returns up to the number of supported chains. See
[Supported Chains](/evm/supported-chains) to learn more.
required: false
schema:
type: integer
minimum: 0
example: 100
- name: offset
in: query
description: >-
The offset to paginate through result sets; this is a cursor being
passed from the previous response, only use what the backend returns
here
required: false
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TokensResponse'
example:
contract_address: native
tokens:
- chain: ethereum
chain_id: 1
price_usd: 12.34
symbol: ETH
'400':
description: >-
Bad Request - Invalid address, chain ID, token ID, or batch size
exceeded.
content:
text/plain:
schema:
type: string
examples:
invalidAddress:
summary: Invalid address
value: 'Invalid address: expected a hex-encoded address'
invalidChainId:
summary: Invalid chain ID
value: 'Invalid chain id: 999999'
batchSizeExceeded:
summary: Batch size exceeded
value: Batch size exceeds maximum limit of 100 tokens
'401':
description: Unauthorized - Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
invalidApiKey:
value:
error: invalid API Key
'404':
description: Not Found - Token or resource not found.
content:
text/plain:
schema:
type: string
examples:
tokenNotFound:
summary: Token not found
value: Token not found
'429':
description: Rate Limit Exceeded - Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayErrorResponse'
examples:
rateLimitExceeded:
value:
error: >-
Too many requests. Please contact sales@dune.com to
increase your limit.
'500':
description: Internal Server Error.
content:
text/plain:
schema:
type: string
examples:
storeError:
summary: Store read failure
value: 'Failed to read from store: connection timeout'
components:
schemas:
TokensResponse:
type: object
required:
- contract_address
- tokens
properties:
contract_address:
type: string
description: The contract address of the token or 'native' for the native token
tokens:
type: array
items:
$ref: '#/components/schemas/TokenInfo'
description: Array of token information across different chains
warnings:
type: array
items:
$ref: '#/components/schemas/Warning'
description: >-
Array of warnings that occurred during request processing. Warnings
indicate non-fatal issues (e.g., unsupported chain IDs) where the
request can still be partially fulfilled.
next_offset:
type: string
description: Pagination cursor for the next page of results
GatewayErrorResponse:
type: object
description: >-
Error response from the API gateway. Returned for authentication,
permissions, rate-limiting, and quota errors.
properties:
error:
type: string
description: Error message.
required:
- error
TokenInfo:
type: object
properties:
chain:
type: string
description: The name of the blockchain
chain_id:
type: integer
format: int64
description: The ID of the blockchain
symbol:
type: string
description: The token symbol
name:
type: string
description: The token name
decimals:
type: integer
description: The number of decimals for the token
price_usd:
type: number
format: double
description: The price of the token in USD
historical_prices:
type: array
items:
$ref: '#/components/schemas/HistoricalPricePoint'
description: >-
Historical price points for the requested offsets. Only present when
the historical_prices query parameter is provided.
total_supply:
type: string
description: The total supply of the token
market_cap:
type: number
format: double
description: The market capitalization of the token
logo:
type: string
description: URL to the token logo
Warning:
type: object
required:
- code
- message
properties:
code:
type: string
description: Warning code identifier (e.g., 'UNSUPPORTED_CHAIN_IDS')
example: UNSUPPORTED_CHAIN_IDS
message:
type: string
description: Human-readable warning message
example: >-
Some requested chain_ids are not supported. Activity is returned
only for supported chains.
chain_ids:
type: array
items:
type: integer
format: int64
description: >-
List of chain IDs that triggered this warning (for chain-related
warnings)
docs_url:
type: string
description: URL to documentation with more information about the warning
example: https://docs.sim.dune.com/evm/supported-chains
HistoricalPricePoint:
type: object
required:
- offset_hours
- price_usd
properties:
offset_hours:
type: integer
format: int32
minimum: 1
price_usd:
type: number
format: double
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Sim-Api-Key
description: >-
API key for authentication. Obtain your key from the Dune dashboard at
sim.dune.com.
````