Token Balances

This endpoint returns token balances for an address for any token that the address has interacted with

The Token Balances API provides accurate and fast real time balances of the native and ERC20 tokens of accounts on supported blockchains (EVM currently). Data is typically available within 100 ms since a block was propagated to nodes.

• These endpoints are authenticated with a normal Dune API key.
• As we are in beta there might be changes. Please reach out to [e-mail] if you use this API.
• Specify ?all_chains to get native balances for a long tail of evm chains, where we don’t support erc20 assets. See chains endpoint.
• Specify ?filters=erc20 or ?filters=native to get only erc20 tokens or native assets, respectively
• Specify ?exclude_spam_tokens to filter out tokens Dune believes to be spam. We use this query to determine if something is spam.
• Specify ?chain_ids=11,250,1 to fetch balances only for select chains. See chainlist https://chainlist.org/ for a list of chainIDs.
• CoinMarketCap is used for price information
• Token metadata, such as symbols and decimals, are fetched from Dune’s tokens.erc20 dataset which is curated by Dune users and defined.fi

Column Descriptions

Column	Description	Type
request_time	Time of request	timestamp
response_time	Time of response	timestamp
wallet_address	Wallet address	string
chain	Name of blockchain of token	string
address	ERC20 contract address or blockchain name for native token	string
amount	Amount of token owned in WEI	double
symbol	Symbol of token, if avilable	string
decimals	Decimals of token, if available	double
price_usd	Current price of token, if available	double
value_usd	Current value of token owned, if available	double

Pagination

This endpoint is using 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 passed back by the initial response and can be used to fetch the next page of results, by passing it as the offet 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.

Headers

X-Dune-Api-Key

string

required

API key to access the service

Path Parameters

address

string

required

Wallet to get balances for

Query Parameters

all_chains

string | null

Specify this to get native balances for a long tail of EVM chains, where we don’t support ERC20 assets

chain_ids

string | null

Comma separated list of chain ids to get balances for

exclude_spam_tokens

string | null

Specify this to exclude spam tokens from the response

filters

string | null

Specify ERC20 or NATIVE to get only ERC20 tokens or native assets, respectively

offset

string | null

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

limit

integer | null

Maximum number of transactions to return

Response

200 - application/json

balances

object[]

required

Show child attributes

errors

object

Show child attributes

next_offset

string | null

request_time

string | null

response_time

string

required

wallet_address

string

required