Overview

Polymarket is a prediction market built on the Polygon blockchain using a Central Limit Order Book (CLOB) model. Traders buy and sell binary outcome shares — YES and NO — for events like "BTC above $80k by March 31." The price of a YES share represents the market's implied probability that the event occurs.

Kwery ingests Polymarket's CLOB data and normalizes it into time-series snapshots. Each snapshot captures the midpoint price, spread, and full order book depth for both sides of a market.

What we ingest

• CLOB midpoint prices for UP (YES) and DOWN (NO) shares
• Full order book snapshots with bids and asks arrays
• Spread and depth metrics derived from the book
• Reference prices (e.g. BTC spot) for context

Currently tracked assets: BTC, ETH, SOL, XRP. Each asset can have multiple active markets simultaneously — for example, "BTC above $70k by Friday" and "BTC above $80k by end of month."

Data semantics

Available endpoints

List markets

GET /v1/markets

Returns all tracked Polymarket markets and their metadata.

curl "https://kwery-api.com/v1/markets?api-key=YOUR_KEY&limit=10"

{
  "markets": [
    {
      "identifier": "will-btc-hit-80k-by-march-31",
      "title": "Will BTC hit $80k by March 31?",
      "source": "polymarket",
      "asset": "BTC",
      "status": "active",
      "expiration": "2026-03-31T23:59:59Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Snapshots (current API)

Polymarket history is exposed on the unified snapshot endpoints (see Snapshots and OpenAPI):

GET /v1/snapshots?source=polymarket&symbol=BTC&market_id={slug_or_condition_id}
GET /v1/snapshots/at?source=polymarket&symbol=BTC&market_id=...&time=ISO8601

• market_id — Polymarket condition id (0x…) or slug (e.g. btc-updown-5m-…). Discover values from GET /v1/markets?source=polymarket.
• time — Use the query name time on /at (not timestamp).
• Scoped route: GET /v1/polymarket/snapshots and GET /v1/polymarket/snapshots/at are equivalent shortcuts — see Platform routes.

curl "https://kwery-api.com/v1/snapshots?source=polymarket&symbol=BTC&market_id=will-btc-hit-80k-by-march-31&interval=1h&limit=3" \
  -H "X-API-Key: YOUR_KEY"

Responses use the standard { "data": [...], "meta": {...} } envelope; field names match the live schema in OpenAPI.

Source-specific fields

Available intervals

Limitations & notes

• Multiple markets per asset. A single asset like BTC can have many concurrent markets with different strike prices and expirations. Each market has a slug and condition id. Use GET /v1/markets?source=polymarket to discover markets and pass market_id on snapshot calls.
• Order book depth varies. Illiquid markets may have sparse books. The orderbook_up and orderbook_down arrays reflect whatever depth is available at snapshot time.
• Prices are probabilities, not dollar amounts. A price_up of 0.65 is not $0.65 — it's a 65% implied probability. Do not mix these with spot prices from other sources without conversion.
• 500ms interval requires Business plan. Sub-second snapshots are only available on Business and Enterprise tiers.
• Settlement is binary. All Polymarket contracts resolve to exactly 1.00 or 0.00. There are no partial payoffs.
• btc_price is a reference field. It reflects the approximate BTC spot price at the time of each snapshot, useful for correlating prediction market movement with underlying price action.