> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances

> Get the latest native and ERC-20 balances for one wallet across chains, with USD values and a total for the wallet.

```text theme={"dark"}
GET https://api.goldsky.com/api/v1/feeds/wallets/balances
```

Returns the latest balance of each token one wallet holds across the requested chains, native tokens included. Each row carries the token's metadata and USD value, and the response includes the wallet's total value. Use it to build a portfolio screen with the total at the top and one row per token.

By default, tokens Goldsky has no price source for are left out. Set `include_unknown_price=true` to see them.

## Parameters

This endpoint accepts the [shared parameters](/feeds/api/overview#shared-parameters), plus the following.

<ParamField query="min_value_usd" type="number">
  Hide balances worth less than this many US dollars, to filter out dust. Must be `0` or more. Balances without a price are hidden too, since they have no value to compare. `total_value_usd` only counts the balances that pass.
</ParamField>

<ParamField query="include_historical" type="boolean" default="false">
  Also return zero balances: tokens the wallet held and fully sold, and native tokens it holds none of.
</ParamField>

## Response

<ResponseField name="address" type="string">
  The wallet address, in lowercase.
</ResponseField>

<ResponseField name="total_value_usd" type="number">
  Sum of `value_usd` over every balance that matches your filters, across all pages. Balances without a USD value add nothing, so read it as a lower bound.
</ResponseField>

<ResponseField name="data" type="object[]">
  One entry per token balance, highest `value_usd` first. Balances without a price come last.

  <Expandable title="properties">
    <ResponseField name="chain" type="string">
      Chain value, such as `ethereum`. See [supported chains](/feeds/api/overview#supported-chains).
    </ResponseField>

    <ResponseField name="chain_family" type="string">
      `evm`.
    </ResponseField>

    <ResponseField name="token_address" type="string">
      Token contract address. The zero address for the chain's native token.
    </ResponseField>

    <ResponseField name="token_symbol" type="string | null">
      Token symbol.
    </ResponseField>

    <ResponseField name="token_name" type="string | null">
      Token name.
    </ResponseField>

    <ResponseField name="token_decimals" type="integer | null">
      Token decimals.
    </ResponseField>

    <ResponseField name="token_logo_url" type="string | null">
      URL of the token logo.
    </ResponseField>

    <ResponseField name="balance_raw" type="string">
      Balance in the token's smallest unit.
    </ResponseField>

    <ResponseField name="price_usd" type="number | null">
      Latest token price in USD. Major stablecoins are priced at `1.0`.
    </ResponseField>

    <ResponseField name="last_priced_at" type="string | null">
      When Goldsky recorded `price_usd`. The API returns the latest price however old it is, so check this field if stale prices matter to you.

      A `null` here next to a `price_usd` means a major stablecoin priced at `1.0`. Leave those rows out of any staleness filter.
    </ResponseField>

    <ResponseField name="value_usd" type="number | null">
      `balance_raw / 10^token_decimals * price_usd`. `null` when the balance has no price.
    </ResponseField>

    <ResponseField name="block_number" type="integer">
      For a native token, the latest block when the API read the balance. For an ERC-20 token, the block of the wallet's most recent balance change.
    </ResponseField>

    <ResponseField name="block_timestamp" type="string">
      Timestamp of `block_number`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  See [pagination](/feeds/api/overview#pagination).
</ResponseField>

## How the data behaves

* **Latest only.** You can't ask for a wallet's balances at a past block. To reconstruct past holdings, use [Transfers](/feeds/api/transfers).
* **Native balances are read live.** The API reads each chain's native balance over RPC when you make the request. If a chain doesn't answer, the request fails with `503 NATIVE_BALANCE_UNAVAILABLE`, lists the chains in `error.chains`, and sets `Retry-After`. To get the other chains in the meantime, leave the failing ones out of `chains`.
* **Values move without onchain activity.** Prices update on their own schedule, so two requests seconds apart can return different values for the same balances. Pages are ordered by `value_usd`, so a balance whose value changes while you page through can be skipped or repeated.
* **Going back re-reads the wallet.** A `prev_page_token` request uses current values, so a balance can land on a different page than it did the first time.

## Example

```bash theme={"dark"}
curl "https://api.goldsky.com/api/v1/feeds/wallets/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&page_size=2&key=$GOLDSKY_FEEDS_API_KEY"
```

```json theme={"dark"}
{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "total_value_usd": 25174.729277920822,
  "data": [
    {
      "chain": "ethereum",
      "chain_family": "evm",
      "token_address": "0x0000000000000000000000000000000000000000",
      "token_symbol": "ETH",
      "token_name": "Ether",
      "token_decimals": 18,
      "token_logo_url": "https://coin-images.coingecko.com/coins/images/279/large/ethereum.png?1696501628",
      "balance_raw": "5715987139328012679",
      "price_usd": 2659.529118748444,
      "last_priced_at": "2026-09-30T06:46:00.000Z",
      "value_usd": 15201.834239434469,
      "block_number": 26088597,
      "block_timestamp": "2026-09-30T06:47:23.000Z"
    },
    {
      "chain": "base",
      "chain_family": "evm",
      "token_address": "0x0000000000000000000000000000000000000000",
      "token_symbol": "ETH",
      "token_name": "Ether",
      "token_decimals": 18,
      "token_logo_url": "https://coin-images.coingecko.com/coins/images/279/large/ethereum.png?1696501628",
      "balance_raw": "3128821803472537280",
      "price_usd": 2659.529118748444,
      "last_priced_at": "2026-09-30T06:46:00.000Z",
      "value_usd": 8321.192693710234,
      "block_number": 51980751,
      "block_timestamp": "2026-09-30T06:47:29.000Z"
    }
  ],
  "pagination": {
    "next_page_token": "eyJzIjoidmFsdWVfdXNkIiwiayI6IiIsInQiOiIiLCJm...",
    "prev_page_token": null,
    "page_size": 2
  }
}
```


## Related topics

- [eth_getBalance](/edge-rpc/evm/methods/eth_getBalance.md)
- [Track native token balances for a set of addresses](/turbo-pipelines/guides/native-balances.md)
- [Stellar Sources](/turbo-pipelines/sources/stellar.md)
- [Turbo SQL Functions Reference](/turbo-pipelines/reference/sql-functions.md)
- [Detect incoming assets to a set of addresses](/solutions/deposit-detection.md)