Feeds API Overview

The Feeds API is a REST API. Each feed is a GET endpoint that takes one wallet address and returns JSON.

Base URL

https://api.goldsky.com/api/v1/feeds/wallets

Authentication

Pass your API key in the key query parameter:

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

Or send it in the X-API-Key header, which keeps the key out of URLs and access logs:

curl -H "X-API-Key: $GOLDSKY_FEEDS_API_KEY" \
  "https://api.goldsky.com/api/v1/feeds/wallets/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Create a key under API Keys on the Feeds page of the Goldsky dashboard. It’s a Feeds API key, not the Goldsky API key the CLI uses. Your API key is a secret, so call the API from your server, not from the browser.

Endpoints

Endpoint	Returns
`GET /balances`	The latest balance of each token a wallet holds, with USD values and a total for the wallet.
`GET /transfers`	A wallet’s transfers in and out, newest first, with USD values.

Try it in the API reference

Send test requests with your key.

OpenAPI spec (JSON)

For codegen and AI agents.

Supported chains

Chain	`chains` value
Ethereum	`ethereum`
Base	`base`
Arbitrum One	`arbitrum_one`
Optimism	`optimism`
Polygon	`polygon`
BNB Smart Chain	`bsc`
Robinhood Chain	`robinhood`

mainnet, arbitrum, and matic also work, as aliases for ethereum, arbitrum_one, and polygon. Values are case-insensitive, and a - reads as _, so Arbitrum-One works too. Any other value returns 400 BAD_REQUEST. How far back the history goes can differ from chain to chain.

Shared parameters

Both endpoints accept these query parameters. Each endpoint page lists its own additional parameters.

string

required

The wallet to look up: 0x followed by 40 hex characters, in any case. Each request takes one address, so send one request per wallet.

string

Comma-separated chain values, such as ethereum,base. Defaults to every supported chain.

string

Comma-separated token contract addresses, up to 100. Use the zero address, 0x0000000000000000000000000000000000000000, for each chain’s native token.

string

Comma-separated token symbols, such as USDC,WETH. Up to 100 symbols of at most 32 characters each. Case-insensitive.

boolean

default:"false"

By default, both feeds leave out tokens Goldsky has no price source for. Set to true to include them. They can come back without a price or USD value.

integer

default:"100"

Results per page, up to 1000.

string

The next_page_token or prev_page_token from a previous response.

Pagination

Every response has a pagination object:

{
  "pagination": {
    "next_page_token": "eyJzIjoiYmxvY2tfdGltZXN0YW1wX2Rlc2MiLCJrIjoi...",
    "prev_page_token": null,
    "page_size": 100
  }
}

Pass next_page_token as page_token to get the next page, and keep going until next_page_token is null. prev_page_token takes you back one page and is null on the first page. A page token only works with the filters it was issued for. If you change a filter, start again from the first page, or the request returns 400 INVALID_CURSOR. You can change page_size between pages.

Errors

API errors have a JSON body with a stable code to branch on and a message that explains what went wrong:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "`address` takes exactly one wallet per request, not a list. Issue one request per wallet."
  }
}

Status	`code`	Meaning
`400`	`BAD_REQUEST`	A parameter is missing or malformed, or a chain or transfer type is not supported.
`400`	`INVALID_CURSOR`	`page_token` is malformed or was issued for different filters.
`401`	`UNAUTHORIZED`	The API key is missing or invalid.
`403`	`PERMISSION_DENIED`	The API key is disabled. Enable it under API Keys on the Feeds page.
`422`	`CONFLICTING_FILTERS`	Two filters contradict each other, such as a `to` before `from`, or a block filter without exactly one chain.
`502`	`UPSTREAM_CLICKHOUSE` or `UPSTREAM_EDGE`	A backend did not answer. Retry the request.
`503`	`NATIVE_BALANCE_UNAVAILABLE`	Balances only. Native balances could not be read on the chains listed in `error.chains`. Retry after the number of seconds in the `Retry-After` header.
`504`	`TIMEOUT`	The query timed out. Retry the request.

A request over your rate limit gets 429 Too Many Requests with an empty body and a Retry-After header, in seconds.

Data types

amount_raw and balance_raw are integers in the token’s smallest unit, sent as strings so no precision is lost. Divide by 10^token_decimals for the token amount.
Timestamps are RFC 3339 in UTC with milliseconds, such as 2026-09-30T06:47:23.000Z.
Addresses come back in lowercase.
A chain’s native token, such as ETH or BNB, has the zero address as its token_address.
Token metadata (token_symbol, token_name, token_decimals, token_logo_url) and prices can be null, and can fill in on a later request.

Feeds

Reference

Base URL

Authentication

Endpoints

Try it in the API reference

OpenAPI spec (JSON)

Supported chains

Shared parameters

Errors

Data types

​Base URL

​Authentication

​Endpoints

Try it in the API reference

OpenAPI spec (JSON)

​Supported chains

​Shared parameters

​Pagination

​Errors

​Data types

Base URL

Authentication

Endpoints

Supported chains

Shared parameters

Pagination

Errors

Data types