Skip to main content

Wallet balance and transfer history API across chains: a worked example

Goldsky Feeds returns wallet balances and transfer history across 9 EVM chains and Solana. A worked example: one wallet, two requests, the responses, limits, and price.

Wallet balance and transfer history API across chains: a worked example cover image
Written by
image of Emmanuel Pozo
Emmanuel Pozo

Product Manager

Goldsky Feeds returns wallet balances and transfer history across chains through two REST endpoints. Balances returns the tokens that a wallet holds now, with a USD value for each. Transfers returns the wallet's transfers, newest first, with the USD value at the time of each transfer. One request covers 9 EVM chains for an EVM address, or Solana for a Solana address. This guide runs both requests on one wallet, then lists the chains, the limits, and the price.

Flow: a wallet address goes to the Balances and Transfers endpoints of Goldsky Feeds, and both responses go to an application.

What one request returns

The Balances endpoint (opens in a new tab) returns one row per token, highest USD value first. The response also has total_value_usd, the sum of every balance that matches the request.

Balances fieldWhat it holds
addressThe wallet in the request
total_value_usdSum of value_usd over every matching balance, across all pages
chain, chain_familyThe chain, and evm or solana
token_address, token_symbol, token_name, token_decimals, token_logo_urlToken identity and metadata
balance_rawBalance in the smallest unit of the token, as a string
price_usd, last_priced_at, value_usdLatest price, its time, and the USD value
block_number, block_timestampBlock of the read for a native token, or of the last balance change for an ERC-20 token

The Transfers endpoint (opens in a new tab) returns one row per transfer. Each row has the direction, the counterparty, the token, and the USD value at transfer time.

Transfers fieldWhat it holds
directionin or out
from_address, to_addressSender and recipient
token_address, token_symbol, amount_rawToken and raw amount
price_usd, amount_usdPrice and USD value at transfer time
transfer_typenative or erc20. On Solana, native or spl
block_number, block_timestamp, transaction_hashWhere and when the transfer occurred

An app with a balance screen and an activity feed reads both from one API. The rows already have token metadata and prices.

The worked example

The Feeds quickstart (opens in a new tab) uses 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 as its sample wallet. The requests and responses below are copied from the docs.

Balances request

bash
curl "https://edge.goldsky.com/data/feeds/wallets/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&key=$GOLDSKY_FEEDS_API_KEY"

The docs shorten the response to its first row:

json
{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "total_value_usd": 25260.2792825334,
  "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": 2668.616188843224,
      "last_priced_at": "2026-09-30T08:19:00.000Z",
      "value_usd": 15253.775815230401,
      "block_number": 26089058,
      "block_timestamp": "2026-09-30T08:19:59.000Z"
    }
  ],
  "pagination": {
    "next_page_token": "eyJzIjoidmFsdWVfdXNkIiwiayI6IiIsInQiOiJi...",
    "prev_page_token": null,
    "page_size": 100
  }
}

One request reads the wallet's balances on every EVM chain that Feeds supports. The total in this sample is $25,260.28. A balance with no price adds nothing to the total, so the docs call it a lower bound.

Transfers request

This request gets the most recent transfer into the wallet on Base:

bash
curl "https://edge.goldsky.com/data/feeds/wallets/transfers?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chains=base&direction=in&page_size=1&key=$GOLDSKY_FEEDS_API_KEY"
json
{
  "data": [
    {
      "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "chain": "base",
      "chain_family": "evm",
      "block_number": 51496203,
      "block_timestamp": "2026-09-19T01:35:53.000Z",
      "transaction_hash": "0x1d56f2edf92fc043da30a3af245a6d97733e57bd6a91b8116cdc0ef169964ec8",
      "from_address": "0xc5b87910fc3733f8a9cc8f8993cf2c6c7f8a4ab3",
      "to_address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "from_label": null,
      "to_label": null,
      "direction": "in",
      "token_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "token_symbol": "USDC",
      "token_name": "USDC",
      "token_decimals": 6,
      "token_logo_url": "https://coin-images.coingecko.com/coins/images/6319/large/USDC.png?1769615602",
      "amount_raw": "1000000",
      "price_usd": 1.0,
      "amount_usd": 1.0,
      "transfer_type": "erc20"
    }
  ],
  "pagination": {
    "next_page_token": "eyJzIjoiYmxvY2tfdGltZXN0YW1wX2Rlc2MiLCJrIjoi...",
    "prev_page_token": null,
    "page_size": 1
  }
}

The chains=base and direction=in filters limit the result to one chain and one direction. Without them, the endpoint returns the wallet's transfers on every supported chain, 100 per page. To get the next page, pass pagination.next_page_token back as page_token.

A Solana wallet uses the same two requests

A Solana address goes into the same address parameter. The address is base58, and the API returns it as sent. token_address holds the token mint, and transfer_type is spl for a token transfer. On Solana, only SOL, wrapped SOL, USDC, and USDT have a symbol, a name, decimals, and a price. Other mints come back only with include_unknown_price=true.

Use the two endpoints in an app

The two responses map to two screens: a portfolio screen from Balances and an activity feed from Transfers. The docs state the behavior that an app must handle.

For the portfolio screen:

  • Set min_value_usd to hide dust. total_value_usd then counts only the balances that pass the filter.
  • Divide balance_raw by 10^token_decimals for the token amount. The API sends raw amounts as strings so that no precision is lost.
  • Token metadata and prices can be null and can fill in on a later request. By default, Balances leaves out a token that has no price source.

For the activity feed:

  • Rows are in order by block_timestamp, newest first. Timestamps are RFC 3339 in UTC.
  • Use from and to for a time range, or from_block and to_block with exactly one chain.
  • A transfer between two wallets in the same request comes back as two rows: out for the sender and in for the recipient. An app that sums amounts must count that transfer one time.
  • Follow pagination.next_page_token until it is null. If a filter changes, start again from the first page.

For both screens, a request above the rate limit gets 429 Too Many Requests with a Retry-After header. The header gives the number of seconds to wait.

A team that already has token metadata can set include_token_metadata=false to skip that lookup. The metadata fields then come back null.

Chain coverage

The Feeds API overview (opens in a new tab) lists these chains for Balances and Transfers, as read on 2026-11-18.

Chainchains value
Ethereumethereum
Basebase
Arbitrum Onearbitrum_one
Optimismoptimism
Polygonpolygon
BNB Smart Chainbsc
Robinhood Chainrobinhood
Arcarc
Elysiumelysium
Solanasolana

The wallet address decides which chains a request reads. An EVM address reads the 9 EVM chains, and a Solana address reads Solana. An app with EVM and Solana users sends one request per address type.

Limits and price

TopicWhat the docs state
Paginationpage_size up to 1,000, default 100. A page token works only with the filters it was issued for.
Rate limitPer project, not per API key. 5 requests per second on Starter and 50 on Scale, at no monthly fee. Higher tiers go to 500 and more.
HistoryBalances returns the latest balance only. Transfers history depth can differ from chain to chain.
Wallets per requestOne wallet, or up to 10 EVM wallets separated by commas. A Solana address goes alone.
Filterschains, token_address, token_symbol, min_value_usd on Balances, and transfer_type, direction, time range, and block range on Transfers.
Price$0.35 per 1,000 requests with an API key. Each wallet in a request counts as one request.

The rate limit and the price come from the Feeds section of the pricing page (opens in a new tab). An export of full history for many wallets reaches the rate limit before any other limit, so plan the page size and the tier first.

Move the same data into a database

Two paths put this data into a database that the team owns.

Feeds data sync (opens in a new tab) pushes the rows of any feed to ClickHouse, Postgres, MySQL, or a webhook as they land. The app then reads its own table and does not poll the API. Data sync is in early access, and a team requests it from Goldsky support.

Turbo Pipelines stream onchain data into a destination that the team configures in YAML. Turbo writes to Postgres, ClickHouse, Kafka, S3, and the other destinations in the list of supported sinks (opens in a new tab). One guide, track native token balances for a set of addresses (opens in a new tab), keeps a Postgres table of current balances for a list of wallets.

A table in the team's own database removes the rate limit from the read path of the app.

Three ways to get wallet data

ApproachWork the team doesGoldsky product
Poll an RPC node with eth_getBalance and eth_getLogsRun requests per chain, decode transfer events, add token metadata and prices, and store the resultEdge RPC (opens in a new tab)
Run an indexing pipelineWrite a pipeline that decodes transfers and writes a balances tableTurbo Pipelines (opens in a new tab)
Call a wallet data APISend one GET request per walletFeeds

The first approach needs many calls for a full history. On Edge RPC, one eth_getLogs request covers up to 20,000 blocks on most EVM chains. On Base, Celo, and Cronos, the cap is 1,000 blocks, as the eth_getLogs reference (opens in a new tab) states. The decoding and the prices are still the team's work after those calls.

FAQ

Does Balances return a wallet's balance at a past block?
No. Balances returns the latest balance only. For past holdings, sum the wallet's rows from Transfers up to that time.

Can one request cover several wallets?
Yes, for EVM wallets. Balances and Transfers accept up to 10 EVM addresses separated by commas, and each wallet counts as one request. A Solana address goes in its own request.

What does a request cost?
$0.35 per 1,000 requests with an API key. Without an account, a request can be paid in USDC over x402 at $0.00035.

How does a team start with Feeds on Goldsky?
Create a Feeds API key in the Goldsky dashboard. Then run the two requests in this post on the sample wallet.

© Endless Sky Inc. All rights reserved.

PrivacyTermsSecurity

System status