> For the complete documentation index, see [llms.txt](https://txnlab.gitbook.io/haystack-dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://txnlab.gitbook.io/haystack-dev/haystack-api/overview.md).

# Overview

The Haystack API (api.hay.app) serves the market data behind hay.app.

Base URL: `https://api.hay.app`

The Haystack API serves the data behind [hay.app](https://hay.app): assets and prices, charts, pools, trades and liquidity, HayLaunch tokens, prediction markets, and live updates over a WebSocket. Only Algorand `mainnet` is supported.

The OpenAPI 3 specification is at [`https://api.hay.app/info/openapi3.yaml`](https://api.hay.app/info/openapi3.yaml). These pages explain how to use the endpoints. The specification is the field-by-field reference. It also lists endpoints that only Haystack's own apps use: those not documented here aren't supported for third parties and may change without notice.

| Page                                                                     | Covers                                                                       |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| [Assets](/haystack-dev/haystack-api/assets.md)                           | Search, prices, details, trending, movers, market signals                    |
| [Trades & Liquidity](/haystack-dev/haystack-api/trades-and-liquidity.md) | An asset's trades and liquidity adds and removes, top holders, creator links |
| [Charts & Pools](/haystack-dev/haystack-api/charts-and-pools.md)         | Price candles, the pools holding an asset                                    |
| [Accounts](/haystack-dev/haystack-api/accounts.md)                       | HayLaunch holdings, creator earnings and fees, trading totals                |
| [Leaderboards & Liftoff](/haystack-dev/haystack-api/leaderboards.md)     | All-time leaderboards, the weekly Liftoff competition                        |
| [Prediction Markets](/haystack-dev/haystack-api/prediction-markets.md)   | HayMarkets, price feeds, market hours, prediction leaderboards               |
| [Fee Schedule](/haystack-dev/haystack-api/fees.md)                       | Haystack's swap fees and HAY discounts                                       |
| [Live Data (WebSocket)](/haystack-dev/haystack-api/websocket.md)         | Streaming prices, trades, market data and curve updates                      |

## Authentication

Every request to `/api/...` and `/markets/...` needs an API key with Haystack API access, sent in the `X-API-Key` header:

```bash
curl -H "X-API-Key: hay_pk_s5ltqlgh6i44npsb2m2qarpolc" "https://api.hay.app/api/assets/trending"
```

That is the public free-tier key, which anyone may use from servers, scripts and apps at the [free tier's limits](#rate-limits), counted per IP address. See [API Keys](/haystack-dev/getting-started/api-keys.md#getting-a-key) for a key of your own and the key kinds. A key issued for the Haystack Router alone is refused here, and the router's free key has no Haystack API access.

Browsers can't set headers on a WebSocket, so `wsLiveData` also takes a publishable key as the `apiKey` query parameter. No other endpoint reads a key from the URL, and a secret key is never accepted there.

## Errors

Errors are JSON, with the error's name in the `goa-error` response header too. The two exceptions are plain text: an unknown path or method (`404 page not found`), and a path or query containing invalid UTF-8 or NUL characters (`400 invalid characters in request`).

```json
{
  "name": "unauthorized",
  "id": "k3f9x2ab",
  "message": "invalid or revoked API key",
  "temporary": false,
  "timeout": false,
  "fault": false
}
```

| Status | Meaning                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------- |
| `304`  | Not modified: the `If-None-Match` ETag still matches. See [Caching](#caching).                  |
| `400`  | The request is invalid. `message` says why.                                                     |
| `401`  | The key is missing, invalid, revoked, not valid for this origin, or has no Haystack API access. |
| `404`  | The route doesn't exist, or what was asked for isn't known (an asset, a price feed).            |
| `429`  | Rate limited. See [Rate limits](#rate-limits).                                                  |
| `5xx`  | A server or upstream failure, including `503 unable to verify API key`. Retry with backoff.     |

Don't retry other errors because `temporary` is `true`: 400s and 404s set it too. Retry 5xx responses, and 429s after the wait they give.

## Rate limits

Each endpoint has its own per-minute limit. A publishable key is limited per end-user IP address, so each of your users has their own budget, and a secret key per key. Endpoints about one account also limit each account. A key can also have a cap across all endpoints, per minute (secret keys) and per day (per key for a secret key, per end-user IP for a publishable one). A request over any of these gets `429` with a `Retry-After` header giving the seconds until it resets, and the limit and the same wait in the body:

```json
{ "limit": 20, "secsRemaining": 41 }
```

Wait that long before retrying that endpoint. The 429 can arrive after a delay of up to 5 seconds, which the wait already counts. A daily cap refills gradually through the day rather than all at once, so once it's used up, calls come back at its daily rate (a 5,000-a-day cap gives one about every 17 seconds). Only calls the per-minute limits let through count against it.

The per-endpoint limits on each page are the base limits. A key on the free tier gets half of each, and these caps across endpoints:

| Key         | Per minute | Per day               |
| ----------- | ---------- | --------------------- |
| Secret      | 60         | 5,000                 |
| Publishable | -          | 1,000 per end-user IP |

A key can be issued with higher limits: see [Getting a key](/haystack-dev/getting-started/api-keys.md#getting-a-key) for what to send us.

## Conventions

* **Amounts:** unlike the router, which works in base units, most amounts and prices here are decimal values. A few are not, so each endpoint page states its units.
* **Asset IDs:** ALGO is `0`. To pass a list, repeat the parameter: `?asset=0&asset=31566704`.
* **Times:** RFC 3339 (`2026-11-15T00:00:00Z`).
* **Paging:** list endpoints that page by cursor return `nextToken` and `prevToken`. Pass one back as `paginationToken` to get the next or previous page. Leaderboards page by `limit` and `offset`.

## Caching

Many `GET` endpoints return an `ETag`. Send it back in `If-None-Match` on a request for the same URL, and an unchanged response comes back as `304 Not Modified` with no body. An ETag is only valid for the URL it came with. Respect `Cache-Control`: polling faster than a response's `max-age` returns the same data and uses up your rate limit.
