Balances API - Feeds - Goldsky Docs

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, plus the following.

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.

boolean

default:"false"

Also return zero balances: tokens the wallet held and fully sold, and native tokens it holds none of.

Response

string

The wallet address, in lowercase.

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.

object[]

One entry per token balance, highest value_usd first. Balances without a price come last.

Show properties

string

Chain value, such as ethereum. See supported chains.

string

evm.

string

Token contract address. The zero address for the chain’s native token.

string | null

Token symbol.

string | null

Token name.

integer | null

Token decimals.

string | null

URL of the token logo.

string

Balance in the token’s smallest unit.

number | null

Latest token price in USD. Major stablecoins are priced at 1.0.

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.

number | null

balance_raw / 10^token_decimals * price_usd. null when the balance has no price.

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.

string

Timestamp of block_number.

object

See pagination.

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.
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

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

{
  "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
  }
}

​Parameters

​Response

​How the data behaves

​Example

Parameters

Response

How the data behaves

Example