Balances API - Feeds - Goldsky Docs

GET https://edge.goldsky.com/data/feeds/wallets/balances

Returns the latest balance of each token one wallet holds across the requested chains, native tokens included. A Solana wallet gets its native SOL and SPL token balances. 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. Can’t be combined with include_token_metadata=false or include_prices=false: the request returns 422 CONFLICTING_FILTERS.

boolean

default:"false"

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

boolean

default:"false"

Solana wallets only. Set to true to add the lamports held in the wallet’s token accounts for each token, which is their rent, plus the wrapped SOL in wrapped SOL accounts. The amounts come back in the solana object. Tokens with a zero balance whose account is still open come back too, since their rent is still held. The lookup covers at most 10 accounts per token and 20 per request; compare lamports_account_count with open_account_count to see whether the total is partial. A failed lookup leaves the fields out rather than failing the request. Ignored for an EVM wallet.

boolean

default:"false"

Solana wallets only. Set to true to add the rent held in the wallet’s open token accounts to native SOL’s balance_raw and value_usd, and to total_value_usd. The lookup covers the first 20 token accounts by address, and native SOL’s solana object says how much rent was added and how many accounts it covers. A failed lookup adds nothing rather than failing the request. Ignored for an EVM wallet.

Response

string

The wallet address, in lowercase for an EVM wallet and as sent (base58) for a Solana wallet.

number | null

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. null when you set include_token_metadata=false or include_prices=false.

object[]

One entry per token balance, highest value_usd first. Balances without a price come last. With include_token_metadata=false or include_prices=false, no balance has a value_usd, so entries are ordered by chain, then token address.

Show properties

string

Chain value, such as ethereum. See supported chains.

string

evm or solana.

string

Token contract address. The zero address for an EVM chain’s native token. On Solana, the token mint, and So11111111111111111111111111111111111111111 for native SOL.

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 only serves prices recorded in the last 4 hours. A token with no recent price comes back with price_usd and value_usd set to null.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, or when you set include_token_metadata=false or include_prices=false.

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. On Solana, the slot.

string

Timestamp of block_number.

object

Solana rows only, when you set include_chain_fields=true, include_lamports=true, or include_rent=true. Left out otherwise. See Solana object.

object

See pagination.

Solana object

Each flag adds its own fields, and a field the request didn’t ask for is left out.

integer

With include_chain_fields=true. How many of the wallet’s token accounts the balance sums over, since a wallet can own several for one token. Counts every open account with a balance above zero.

object[]

With include_chain_fields=true. The largest of those accounts, largest first, up to 10. Fewer entries than token_account_count means the list was cut. Native SOL sits in the wallet’s own account, so its one entry is the wallet itself.

Show properties

string

The token account address.

string

The account’s balance in the token’s smallest unit.

string

With include_lamports=true too, the lamports at this account, if the lookup covered it.

string

With include_lamports=true, the lamports held in the token accounts the lookup covered: their rent, plus the wrapped SOL in wrapped SOL accounts. For wrapped SOL, the rent is lamports minus balance_raw. On native SOL with include_rent=true, the rent already added to its balance_raw. Left out when the lookup covered no account.

integer

How many token accounts lamports covers. With include_lamports=true, the largest accounts by balance come first, so empty accounts are covered last. On native SOL with include_rent=true, the first 20 of the wallet’s token accounts by address.

integer

Every open token account behind the row, empty ones included: the token’s accounts with include_lamports=true, and all of the wallet’s token accounts on native SOL with include_rent=true. Fewer accounts in lamports_account_count means lamports is partial.

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://edge.goldsky.com/data/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

​Solana object

​How the data behaves

​Example

Parameters

Response

Solana object

How the data behaves

Example