GET
/
v1
/
evm
/
balances
/
{uri}
Get EVM token balances for a given address
curl --request GET \
  --url https://api.sim.dune.com/v1/evm/balances/{uri} \
  --header 'X-Sim-Api-Key: <x-sim-api-key>'
{
  "balances": [
    {
      "address": "native",
      "amount": "605371497350928252303",
      "chain": "ethereum",
      "decimals": 18,
      "price_usd": 3042.816964922323,
      "symbol": "ETH",
      "value_usd": 1842034.6622198338
    }
  ],
  "next_offset": "dKMBWDLqM7vlyn5OMEXsLWp0nI4AAAABA5JLazNO7x4poVGqUwsgxgqvvIg",
  "request_time": "2023-11-07T05:31:56Z",
  "response_time": "2023-11-07T05:31:56Z",
  "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
}
Balance Sv The Token Balances API provides accurate and fast real time balances of the native and ERC20 tokens of accounts on supported EVM blockchains.
The Balances API only returns balances for certain low latency chains by default. To learn more see the Supported Chains page.

​
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, and show a warning low_liquidity: true if this value is less than $10k.

​
Historical prices

You can request 24 hour point-in-time prices by adding the historical_prices query parameter. Use whole numbers only, from 1 to 24. You can request up to three offsets. For example, &historical_prices=24 returns the price 24 hours ago. &historical_prices=1,6,24 returns prices 1 hour ago, 6 hours ago, and 24 hours ago.
The historical_prices parameter is currently supported only on the EVM Balances and EVM Token Info endpoints.
When set, each balance includes a historical_prices array with one entry per offset: 
{
  "balances": [
    {
      "symbol": "ETH",
      "price_usd": 3896.8315,
      "historical_prices": [
        { "offset_hours": 24, "price_usd": 3816.476803 },
        { "offset_hours": 6,  "price_usd": 3910.384068 },
        { "offset_hours": 1,  "price_usd": 3898.632723 }
      ]
    }
  ]
}
Percent changes are not returned. You can compute your own differences using the price_usd on the balance and the values in historical_prices[].price_usd.
The maximum number of historical price offsets is 3. Only whole numbers 1–24 are accepted. If more than 3 are provided, the API returns an error.

​
Token Filtering

We also include the pool_size field in all responses, allowing you to implement custom filtering logic based on your specific requirements. For a detailed explanation of our approach, see our Token Filtering guide.

​
Pagination

This endpoint is using cursor based pagination. You can use the limit query 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 offset query parameter in the next request.
You can only use the value from next_offset to set the offset query parameter of the next page of results.

Headers

​
X-Sim-Api-Key
string
default:sim_p1bmRCWWOBPaaYdHYvy1a33PuvQ8gJVW
required

API key to access the service

Path Parameters

​
uri
string
default:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
required

Wallet to get balances for

Query Parameters

​
chain_ids
string | null

A comma separated list of chain_ids or tags for blockchains to get balances for. Examples: chain_ids=1,8453,10, chain_ids=mainnet,testnet. Only balances for blockchains tagged with all the specified tags are returned. Please see the response of the /chains endpoint for the tags on each blockchain.

​
filters
enum<string> | null

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

Available options:
erc20,
native
​
metadata
string | null

A comma separated list of additional metadata fields to include for each token. Supported values: logo, url

​
historical_prices

24 hour price history selection. Accepts integer | integer[]. Provide whole numbers from 1 to 24, up to 3 time offsets (e.g. 24 or 1,6,24). When set, each balance includes a historical_prices array with one entry per offset.

Required range: 1 <= x <= 24
​
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

Required range: x >= 0

Response

200
application/json

Successful Response

The response is of type object.