Balances

Access realtime token balances. Get comprehensive details about native and ERC20 tokens, including token metadata and USD valuations.

The Token Balances API provides accurate and fast real time balances of the native and ERC20 tokens of accounts on supported EVM blockchains.

Looking for the balance of a single token for a wallet? See Single token balance.

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.

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.

Exclude tokens with less than 100 USD liquidity

Use the optional exclude_spam_tokens query parameter to automatically filter out tokens with less than 100 USD of liquidity. Include the query parameter exclude_spam_tokens=true so that those tokens are excluded from the response entirely. This is distinct from the low_liquidity field in the response, which is true when liquidity is below 10,000. To learn more about how Sim calculates liquidity data, visit the Token Filtering guide.

Compute Unit Cost

The Balances endpoint’s CU cost equals the number of chains you include via the chain_ids query parameter. For example, ?chain_ids=1,8453,137 processes three chains and consumes three CUs.

If you omit chain_ids, the endpoint uses its default chain set (low-latency networks), which equals chains at request time (subject to change). See the tags section of the Supported Chains page and the Compute Units page for details.

Historical prices

You can request historical point-in-time prices by adding the 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=168 returns the price 168 hours (1 week) 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 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": 8760, "price_usd": 2816.476803 },
        { "offset_hours": 720,  "price_usd": 3710.384068 },
        { "offset_hours": 168,  "price_usd": 3798.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. If more than 3 are provided, the API returns an error.

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.

Single token balance

Use the token sub-path of the Balances endpoint to fetch a wallet’s balance for one token on one chain.

This sub-path accepts exactly one chain via the chain_ids query parameter.

ERC-20 token

Use the ERC-20 contract address in {token_address}.

curl -s -X GET 'https://api.sim.dev.dune.com/v1/evm/balances/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/token/0x146523e8db6337291243a63a5555f446fa6c279f?chain_ids=1' \
  -H 'X-Sim-Api-Key: YOUR_API_KEY'

{
  "request_time": "2025-10-11T03:47:29.364380268+00:00",
  "response_time": "2025-10-11T03:47:29.380032150+00:00",
  "wallet_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "balances": [
    {
      "chain": "ethereum",
      "chain_id": 1,
      "address": "0x146523e8db6337291243a63a5555f446fa6c279f",
      "amount": "7156868995423049840501842481",
      "symbol": "AiMeme",
      "name": "Ai Meme",
      "decimals": 18,
      "price_usd": 102826.739324412,
      "value_usd": 735917502571333,
      "pool_size": 9.09741149400001,
      "low_liquidity": true
    }
  ]
}

Compute Unit Cost

This sub-path has a fixed CU cost of 1 per request.

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: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 · required

Wallet address to get balances for

Query Parameters

chain_ids · string

Filter by chain(s). Accepts numeric chain IDs and/or tags. Provide a single value (e.g. ?chain_ids=1 or ?chain_ids=mainnet) or a comma-separated list (e.g. ?chain_ids=1,8543,testnet). Chain names are not accepted. If this query parameter is omitted, results include balances from chains with the default tag. See the Supported Chains Tags section.

filters · enum<string>

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

Available options:

erc20,

native

metadata · string

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

exclude_spam_tokens · boolean · default: false

When true, excludes tokens with less than 100 USD liquidity from the response. This differs from the low_liquidity field in the response.

historical_prices

Historical price selection. Accepts integer | integer[]. Provide whole numbers representing hours in the past, up to 3 time offsets (e.g. 8760 for 1 year ago or 720,168,24 for 1 month, 1 week, and 1 day ago). When set, each balance includes a historical_prices array with one entry per offset.

Required range: x >= 1

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.

limit · integer · default: 1000

Maximum number of balances to return. Default is 1000 when not provided. Values above 1000 are reduced to 1000.

Required range: 1 <= x <= 1000

Response

200

application/json

Successful Response

balances · object[] · required

Show child attributes

wallet_address · string · required

Example:

"0xd8da6bf26964af9d7eed9e03e53415d37aa96045"

errors · object

Show child attributes

next_offset · string

Use this value as the offset in your next request to continue pagination. Not included when there are no more balances.

request_time · string<date-time>

Timestamp of when the request was received.

response_time · string<date-time>

Timestamp of when the response was generated.