> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Feeds API overview

> Base URL, authentication, supported chains, shared query parameters, pagination, and errors for the Goldsky Feeds REST API.

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

## Base URL

```text theme={"dark"}
https://api.goldsky.com/api/v1/feeds/wallets
```

## Authentication

Pass your API key in the `key` query parameter:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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**](https://app.goldsky.com/dashboard/feeds?tab=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`](/feeds/api/balances) | The latest balance of each token a wallet holds, with USD values and a total for the wallet. |
| [`GET /transfers`](/feeds/api/transfers) | A wallet's transfers in and out, newest first, with USD values. |

<CardGroup cols={2}>
  <Card title="Try it in the API reference" icon="terminal" href="https://edge.goldsky.com/data/docs/#tag/feeds" arrow={true}>
    Send test requests with your key.
  </Card>

  <Card title="OpenAPI spec (JSON)" icon="file-code" href="https://edge.goldsky.com/data/openapi.json" arrow={true}>
    For codegen and AI agents.
  </Card>
</CardGroup>

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

<ParamField query="address" type="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.
</ParamField>

<ParamField query="chains" type="string">
  Comma-separated chain values, such as `ethereum,base`. Defaults to every [supported chain](#supported-chains).
</ParamField>

<ParamField query="token_address" type="string">
  Comma-separated token contract addresses, up to 100. Use the zero address, `0x0000000000000000000000000000000000000000`, for each chain's native token.
</ParamField>

<ParamField query="token_symbol" type="string">
  Comma-separated token symbols, such as `USDC,WETH`. Up to 100 symbols of at most 32 characters each. Case-insensitive.
</ParamField>

<ParamField query="include_unknown_price" type="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.
</ParamField>

<ParamField query="page_size" type="integer" default="100">
  Results per page, up to `1000`.
</ParamField>

<ParamField query="page_token" type="string">
  The `next_page_token` or `prev_page_token` from a previous response.
</ParamField>

## Pagination

Every response has a `pagination` object:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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](/pricing/summary#rate-limits) 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.


## Related topics

- [Feeds](/feeds.md)
- [Get started with Feeds](/feeds/quickstart.md)
- [Pricing: plans, metering, and product costs](/pricing/summary.md)
- [Stream Feeds to your database](/feeds/streaming.md)
- [Which product do I need?](/which-product.md)