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

# Polymarket

> Polymarket API reference and conventions

# Polymarket APIs

Base URL for all API requests:

```
https://api.polyhistorical.com/v1
```

## Authentication

All endpoints require an API key passed in the `X-API-Key` header. See [Authentication](/authentication) for details.

## Request format

* All requests use standard query parameters
* Responses are JSON
* Prediction market timestamps are ISO 8601 format (UTC)
* Binance trade and snapshot timestamps are UTC epoch milliseconds
* Pagination uses `limit` and `offset` parameters

## Response format

All responses follow this structure:

**Success (market list):**

```json theme={null}
{
  "markets": [...],
  "total": 1462,
  "limit": 50,
  "offset": 0
}
```

**Success (single market):**

```json theme={null}
{
  "slug": "btc-updown-5m-1774581000",
  "market_id": "1724470",
  "market_type": "5m",
  ...
}
```

**Success (snapshots):**

```json theme={null}
{
  "market": { ... },
  "snapshots": [...],
  "total": 45,
  "limit": 100,
  "offset": 0
}
```

**Error:**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error description"
  },
  "timestamp": "2026-03-27T12:00:00Z"
}
```

## Common error codes

| Code                  | HTTP Status | Description                    |
| --------------------- | ----------- | ------------------------------ |
| `VALIDATION_ERROR`    | 400         | Invalid request parameters     |
| `UNAUTHORIZED`        | 401         | Missing or invalid API key     |
| `TIER_ACCESS_DENIED`  | 403         | Feature requires a higher plan |
| `RESOURCE_NOT_FOUND`  | 404         | Market or resource not found   |
| `RATE_LIMIT_EXCEEDED` | 429         | Too many requests              |
| `INTERNAL_ERROR`      | 500         | Server error                   |

## Endpoints

<CardGroup cols={2}>
  <Card title="List Markets" icon="list" href="/api-reference/list-markets">
    Browse active and resolved prediction markets with filtering and pagination.
  </Card>

  <Card title="Get Market" icon="search" href="/api-reference/get-market">
    Fetch one prediction market by slug.
  </Card>

  <Card title="Get Snapshots" icon="camera" href="/api-reference/get-snapshots">
    Read time-series price and order book snapshots by market slug.
  </Card>

  <Card title="Replay Strategy" icon="play" href="/api-reference/replay-strategy">
    Backtest entry and exit rules against resolved historical markets.
  </Card>
</CardGroup>

| Method | Endpoint                                        | Description                                                                                        |
| ------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `GET`  | `/v1/markets`                                   | [List markets](/api-reference/list-markets) with filtering and pagination                          |
| `GET`  | `/v1/markets/{slug}`                            | [Get a single market](/api-reference/get-market) by slug                                           |
| `GET`  | `/v1/markets/{slug}/snapshots`                  | [Get snapshots](/api-reference/get-snapshots) for a market                                         |
| `GET`  | `/v1/markets/by-market-id/{marketId}/snapshots` | [Get snapshots by market ID](/api-reference/get-snapshots-by-market-id) using Polymarket market ID |
| `POST` | `/v1/replay`                                    | [Replay a strategy](/api-reference/replay-strategy) against a resolved market                      |