> 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/prediction-markets.md).

# Prediction Markets

HayMarkets prediction markets, their price feeds and market hours, and the prediction leaderboards.

These paths are under `https://api.hay.app/markets`, not `/api`. The full schemas are in the [OpenAPI specification](https://api.hay.app/info/openapi3.yaml).

HayMarkets are up/down prediction markets on a price feed: a stock, commodity, crypto asset or Algorand ASA. Prices from a feed are integers scaled by `10^decimals` of that feed. Prices, and every other integer in a market (`marketId`, `duration`, the pools and shares, `predictionCount`, `totalVolume`), are JSON strings so they keep their precision in JavaScript.

## Markets

`GET /markets/list?status=active|all`

Prediction markets with their on-chain state, `active` ones by default: `{ markets: [...], cachedAt }`. Each market has:

* `marketId`, `creator`, `status` (`active`, `resolved`, `cancelled` or `unknown`), `outcome` (`unresolved`, `yes_up`, `no_down`, `draw` or `unknown`).
* `startTime`, `endTime`, `duration` (seconds), and `timeRemaining` (seconds, negative once expired; it can lag by the cache's age).
* `startPrice`, `endPrice` and `oraclePrice`, scaled by `10^decimals`.
* `yesPool`, `noPool`, `yesShares`, `noShares`, `totalVolume` and `predictionCount`.
* The feed: `assetClass`, `idType`, `identifier`, `currency`, `feedName`, `feedImage`, `feedCategory`, `decimals`.

`cachedAt` is when the list was last refreshed from chain.

## Feeds

`GET /markets/feeds?category=all|stocks|commodities|crypto|asa|exotic`

Every registered feed with its latest price, grouped by category: `{ feeds: { "<category>": [Feed] } }`. A feed has:

* `assetClass`, `idType` (`symbol` or `asaid`), `identifier`, `currency`, `name`, `description`, `image`.
* `decimals`, and `minDuration`: the shortest market it allows, in seconds.
* `price`, `priceUpdatedAt`, and `marketOpen`.

`GET /markets/price?assetClass=<c>&idType=<t>&identifier=<id>[&currency=USD]` returns one feed with its current price: `{ feed }`. An unregistered feed, or one whose price can't be read right now, gets `404`.

## Market hours

`GET /markets/hours`

Whether each asset class's market is open: `{ markets: [{ assetClass, label, isOpen, isEarlyClose, schedule, nextOpen, nextClose }] }`. `nextOpen` and `nextClose` are empty for a market that never closes, and `nextOpen` is empty while a market is open.

## Leaderboards

| Endpoint                           | Returns                                                                                                                                                                                                                                                          |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /markets/topPredictionVolume` | Accounts by prediction volume: `[{ account, nfd, nfdAvatar, amount1day, amount7day, amount30day, amountTotal }]`. `sortBy` is one of the four amounts (default `amount30day`).                                                                                   |
| `GET /markets/pnl`                 | Profit and loss: `[{ account, nfd, nfdAvatar, predictions, wins, losses, wageredUsdc, pnlUsdc, roiPct }]`. `days` is `1`, `7`, `30` (default) or `0` for all time. `sortBy` takes any of the numeric fields (default `pnlUsdc`). Pass `account` for one account. |

Both take `limit` (1 to 100, default 40), `offset` and `sortOrder` (`desc` default, or `asc`).

## Rate limits

| Endpoint                                                        | Requests per minute |
| --------------------------------------------------------------- | ------------------- |
| `markets/price`                                                 | 300                 |
| `markets/list`, `markets/hours`, `markets/feeds`, `markets/pnl` | 30                  |
| `markets/topPredictionVolume`                                   | 10                  |
