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 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):

{
  "markets": [...],
  "total": 1462,
  "limit": 50,
  "offset": 0
}

Success (single market):

{
  "slug": "btc-updown-5m-1774581000",
  "market_id": "1724470",
  "market_type": "5m",
  ...
}

Success (snapshots):

{
  "market": { ... },
  "snapshots": [...],
  "total": 45,
  "limit": 100,
  "offset": 0
}

Error:

{
  "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

List Markets

Browse active and resolved prediction markets with filtering and pagination.

Get Market

Fetch one prediction market by slug.

Get Snapshots

Read time-series price and order book snapshots by market slug.

Replay Strategy

Backtest entry and exit rules against resolved historical markets.

Backtest AI Agent BETA

Generate replay-ready strategies from natural language and test them across resolved markets.

Method	Endpoint	Description
GET	/v1/markets	List markets with filtering and pagination
GET	/v1/markets/{slug}	Get a single market by slug
GET	/v1/markets/{slug}/snapshots	Get snapshots for a market
GET	/v1/markets/by-market-id/{marketId}/snapshots	Get snapshots by market ID using Polymarket market ID
POST	/v1/replay	Replay a strategy against a resolved market
POST	/v1/backtest-ai/generate	Generate a Backtest AI Agent strategy
POST	/v1/backtest-ai/strategy	Generate and backtest a Backtest AI Agent strategy
POST	/v1/backtest-ai/run	Run a generated Backtest AI Agent strategy
GET	/v1/backtest-ai/quota	Get Backtest AI Agent monthly quota