Feeds API Overview

The Feeds API is a REST API. Each feed is a GET endpoint that returns JSON. The feeds come in four groups:

Wallets. Balances and Transfers take one wallet address.
Tokens. Tokens takes a list of tokens.
Prediction markets. Activity, Positions, and Balances return Polymarket data on Polygon.
Chain datasets. Blocks and Chain head return block headers for one chain.

The Prediction markets and Chain datasets feeds were previously called Edge Data, or Data APIs. Their URLs haven’t changed, so existing integrations keep working.

Base URL

https://edge.goldsky.com/data

The wallet feeds live under /feeds/wallets, such as /feeds/wallets/balances, and the token lookup is at /feeds/tokens. The Prediction markets feeds live under /polymarket, and the Chain datasets feeds under /blocks/{chain}.

Get an API key

One Feeds API key works for every feed in your project, from Balances to Blocks. It’s a Feeds API key, not the Goldsky API token the CLI and the Goldsky API use. Any project on a Goldsky plan, Starter included, can get a Feeds key.

Dashboard
Goldsky API
CLI

Open Feeds in the Goldsky dashboard and go to the API keys tab to create or copy a key.

Call POST /api/v1/feeds/api-key with a Goldsky API token from the API Keys page of the dashboard. The token needs the Editor role.

curl -X POST "https://api.goldsky.com/api/v1/feeds/api-key" \
  -H "Authorization: Bearer $GOLDSKY_API_KEY"

The call is idempotent. If the project has no Feeds key yet, it creates one and returns it once, as data.api_key. If a key already exists, data.api_key is null. Grab the existing key from Feeds → API keys in the dashboard, or rotate it with POST /api/v1/feeds/key/rotate. Rotating revokes the old key immediately and returns the new one once.

{
  "data": {
    "name": "feeds",
    "api_key": "your-feeds-api-key"
  }
}

See the Feeds catalog in the Goldsky API reference for every key endpoint.

Run this from a CLI session logged in to your project. The command needs CLI version 13.17.0 or later.

goldsky feeds key reveal

It creates the project’s Feeds key if there isn’t one yet, and saves the key to ~/.goldsky/feeds-api-key. It doesn’t print the key or rotate it, so it’s safe to run again.

If your project already has keys from the old Data APIs page, they keep working for every feed. That page is gone, and its keys are listed under Feeds → API keys. Save the key in your server’s environment:

export GOLDSKY_FEEDS_API_KEY=your-api-key

Authentication

Pass your API key in the key query parameter:

curl "https://edge.goldsky.com/data/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://edge.goldsky.com/data/feeds/wallets/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

The API also accepts the key as a bearer token in the Authorization header:

curl -H "Authorization: Bearer $GOLDSKY_FEEDS_API_KEY" \
  "https://edge.goldsky.com/data/feeds/wallets/balances?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Pay per request with x402

You can call any feed without a Goldsky account or API key by paying in USDC over x402. Send the request with no key: the API answers 402 with a payment challenge listing two ways to pay. Edge lists its CDP entries first, so a standard exact USDC payment settled through the Coinbase CDP facilitator (Base, Polygon, Arbitrum, World Chain, Monad) is what a standard x402 client pays by default, with no deposit and no extra configuration. Circle Gateway needs a one-time deposit; an x402 client such as Circle’s @circle-fin/x402-batching selects it explicitly and pays it.

Feeds	Price per request
Balances, Transfers, and Tokens	350 atomic USDC ($0.00035), the same $350 per million you pay with a key
Prediction markets and Chain datasets	10 atomic USDC ($0.00001), however many rows the request returns

The challenge asks for a top-up. For Balances, Transfers, and Tokens, the minimum is 50000 atomic USDC ($0.05), which covers about 142 requests. For Prediction markets and Chain datasets, the minimum is 5000 atomic USDC ($0.005), which covers about 500 requests. Later requests are deducted from that balance until it runs out. This applies to either payment option.
The balance is tied to your wallet and shared across every feed and Edge RPC, so one top-up pays for all of them.

The x402 guide covers funding a Circle Gateway deposit, paying with a standard client through CDP, the payment handshake, and the headers that report your remaining balance.

Endpoints

Group	Endpoint	Returns
Wallets	`GET /feeds/wallets/balances`	The latest balance of each token a wallet holds, with USD values and a total for the wallet.
Wallets	`GET /feeds/wallets/transfers`	A wallet’s transfers in and out, newest first, with USD values.
Tokens	`GET /feeds/tokens`	Metadata and the current USD price of up to 100 tokens across chains.
Prediction markets	`GET /polymarket/activity`	Polymarket trade fills and other events, newest first.
Prediction markets	`GET /polymarket/positions`	A wallet’s Polymarket positions, with average entry price and realized PnL.
Prediction markets	`GET /polymarket/balances`	The Polymarket outcome tokens a wallet holds.
Chain datasets	`GET /blocks/{chain}`	Block headers by number, hash, or number or timestamp range.
Chain datasets	`GET /blocks/{chain}/head`	The latest block for a chain, and how far behind the current time it is.

Try it in the API reference

Send test requests with your key.

OpenAPI spec (JSON)

For codegen and AI agents.

Supported chains

The wallet feeds, Balances and Transfers, support 9 EVM chains and Solana. Tokens supports the 9 EVM chains.

Chain	`chains` value
Ethereum	`ethereum`
Base	`base`
Arbitrum One	`arbitrum_one`
Optimism	`optimism`
Polygon	`polygon`
BNB Smart Chain	`bsc`
Robinhood Chain	`robinhood`
Arc	`arc`
Elysium	`elysium`
Solana	`solana` (Balances and Transfers only)

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. Tokens takes the same values, and aliases, as the chain in each chain:token_address pair. The wallet address decides which chains a wallet feed reads. A Solana address reads Solana only, and an EVM address reads the EVM chains only. A chains value that leaves out the address’s chains, such as chains=solana with an EVM address, returns an empty data list rather than an error. How far back the history goes can differ from chain to chain. The other groups have their own chains. The Prediction markets feeds return Polymarket data, which is on Polygon, and take no chain parameter. Blocks and Chain head support 21 chains, named by a slug in the path, such as /blocks/matic. See Blocks supported chains.

Shared parameters

The wallet endpoints, Balances and Transfers, accept these query parameters. Each endpoint page lists its own additional parameters. Tokens doesn’t take them. It takes only tokens. The Prediction markets and Chain datasets feeds have their own parameters, listed on each endpoint page.

string

required

The wallet to look up: an EVM address (0x followed by 40 hex characters, in any case) or a Solana address (base58). 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. For a Solana wallet, pass token mints (base58). Native SOL is So11111111111111111111111111111111111111111, and wrapped SOL (So11111111111111111111111111111111111111112) is a separate token.

string

Comma-separated token symbols, such as USDC,WETH. Up to 100 symbols of at most 32 characters each. Case-insensitive. Can’t be combined with include_token_metadata=false.

boolean

default:"false"

By default, both wallet 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.

boolean

default:"true"

Set to false to skip the token metadata lookup, for example when you enrich tokens yourself. token_symbol, token_name, token_decimals, and token_logo_url come back null on every row. A USD value needs the token’s decimals, so amount_usd, value_usd, and total_value_usd are null too. Can’t be combined with token_symbol, or on Balances with min_value_usd: the request returns 422 CONFLICTING_FILTERS.

boolean

default:"true"

Set to false to skip the USD price lookup. price_usd, and on Balances last_priced_at, come back null on every row, and so do amount_usd, value_usd, and total_value_usd. It doesn’t change which tokens include_unknown_price leaves out. On Balances, it can’t be combined with min_value_usd: the request returns 422 CONFLICTING_FILTERS.

boolean

default:"false"

Solana wallets only. Set to true to add a solana object to each row, with fields EVM has no counterpart for, such as token accounts. Balances and Transfers list its fields. Ignored for an EVM wallet.

integer

default:"100"

Results per page, up to 1000.

string

The next_page_token or prev_page_token from a previous response.

Pagination

The wallet feeds and the other groups page differently.

Wallet feeds

Balances and Transfers take page_size and page_token, and their responses have 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. Tokens returns every token you ask for in one response, so it has no pagination.

Prediction markets and Chain datasets

Activity, Positions, Prediction markets Balances, and Blocks take limit and cursor, and their responses have next_cursor and limit at the top level, beside data:

{
  "data": [],
  "next_cursor": "eyJzIjoibnVtYmVyX2Rlc2MiLCJrIjoiMjU1MTMzNjAifQ",
  "limit": 100
}

Pass next_cursor as cursor to get the next page, and keep going until next_cursor is null. There’s no way back to a previous page.

limit defaults to 100. Each endpoint has its own maximum, listed on its page. A larger value is lowered to the maximum rather than rejected, so read limit in the response to see the page size you got.
These feeds don’t read page_size or page_token. A request with page_size=2 gets the default 100 rows, and with an API key each row is billed.
A cursor only works with the sort it was issued for. Keep the same sort and filters while you page.

Chain head returns a single object, so it has no pagination.

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` or `cursor` is malformed, or a `page_token` was issued for different filters.
`400`	`MISSING_SELECTIVE_FILTER`	Activity only. The request has none of the filters Activity needs.
`401`	`UNAUTHORIZED`	The API key is invalid.
`402`	–	No API key was sent. The response is an x402 payment challenge.
`403`	`PERMISSION_DENIED`	The API key is disabled. Enable it under Feeds → API keys in the dashboard.
`422`	`CONFLICTING_FILTERS`	Two filters contradict each other, such as a `to` before `from`, a block filter without exactly one chain (EVM wallets; a Solana wallet may leave `chains` out), `token_symbol` with `include_token_metadata=false`, or a Blocks `number` lookup combined with a range.
`422`	`QUERY_TOO_BROAD`	Wallet feeds only. The request reads more data than one request may, and fails the same way if you retry it unchanged. Narrow it with the parameters in `error.suggested_params`: `from`, `to`, or `token_address` on Transfers, and `token_address` or leaving `include_unknown_price` off on Balances.
`502`	`UPSTREAM_CLICKHOUSE`	The data store 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.
`503`	`QUERY_TIMEOUT`	Wallet feeds only. The query ran out of time. Retry after the number of seconds in the `Retry-After` header. If it times out again, narrow it with the parameters in `error.suggested_params`.
`503`	`UPSTREAM_BUSY`	Wallet feeds only. The data store is at capacity. Retry the same request after the number of seconds in the `Retry-After` header.
`503`	`SOLANA_UNAVAILABLE`, `SOLANA_READ_LIMIT`, `SOLANA_SCAN_FAILED`	Wallet feeds only, for a Solana wallet. Solana data could not be read right now, and `error.reason` says why for the first two. Retry after the number of seconds in the `Retry-After` header.
`504`	–	The request ran past the server’s time limit. 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. The 422 QUERY_TOO_BROAD, 503 QUERY_TIMEOUT, and 503 UPSTREAM_BUSY errors also carry error.retryable, which says whether the same request can succeed later, so your code can act on fields instead of the message. On the Prediction markets and Chain datasets feeds, a query string that can’t be parsed, such as limit=abc, returns 400 with a plain-text body instead of the JSON error object. Branch on the status code, not on the body.

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. Solana addresses, mints, and transaction signatures are base58, where case matters, and come back as they are.
A chain’s native token, such as ETH or BNB, has the zero address as its token_address. Native SOL has So11111111111111111111111111111111111111111.
Token metadata (token_symbol, token_name, token_decimals, token_logo_url) and prices can be null, and can fill in on a later request. They’re always null when you turn them off with include_token_metadata=false or include_prices=false.
On Solana, only SOL, wrapped SOL, USDC, and USDT have a token_symbol, token_name, token_decimals, and a price. No Solana token has a token_logo_url yet. Other mints come back only with include_unknown_price=true, and with token_symbol, token_name, token_logo_url, and the USD fields null.

The Prediction markets and Chain datasets feeds use different conventions:

Timestamps, such as block_timestamp and timestamp, are integers in Unix seconds.
Polymarket Positions and Balances return amounts as strings in raw units of 10^6. Activity returns plain JSON numbers already in shares and USDC.

Feeds

Reference

Base URL

Get an API key

Authentication

Pay per request with x402

Endpoints

Try it in the API reference

OpenAPI spec (JSON)

Supported chains

Shared parameters

Wallet feeds

Prediction markets and Chain datasets

Errors

Data types

​Base URL

​Get an API key

​Authentication

​Pay per request with x402

​Endpoints

Try it in the API reference

OpenAPI spec (JSON)

​Supported chains

​Shared parameters

​Pagination

​Wallet feeds

​Prediction markets and Chain datasets

​Errors

​Data types

Base URL

Get an API key

Authentication

Pay per request with x402

Endpoints

Supported chains

Shared parameters

Pagination

Wallet feeds

Prediction markets and Chain datasets

Errors

Data types