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
}

Get snapshots

GET /v1/snapshots/{identifier}

Returns time-series snapshots for a specific Polymarket market.

curl "https://kwery-api.com/v1/snapshots/will-btc-hit-80k-by-march-31?api-key=YOUR_KEY&interval=1h&limit=3"

{
  "identifier": "will-btc-hit-80k-by-march-31",
  "source": "polymarket",
  "interval": "1h",
  "snapshots": [
    {
      "timestamp": "2026-03-09T12:00:00Z",
      "price_up": 0.72,
      "price_down": 0.28,
      "mid_price": 0.72,
      "spread": 0.02,
      "orderbook_up": {
        "bids": [[0.71, 1500], [0.70, 3200], [0.69, 4800]],
        "asks": [[0.73, 1200], [0.74, 2800], [0.75, 5100]]
      },
      "orderbook_down": {
        "bids": [[0.27, 1200], [0.26, 2800], [0.25, 5100]],
        "asks": [[0.29, 1500], [0.30, 3200], [0.31, 4800]]
      },
      "btc_price": 78542.30
    },
    {
      "timestamp": "2026-03-09T11:00:00Z",
      "price_up": 0.71,
      "price_down": 0.29,
      "mid_price": 0.71,
      "spread": 0.02,
      "orderbook_up": {
        "bids": [[0.70, 1400], [0.69, 3100], [0.68, 4700]],
        "asks": [[0.72, 1100], [0.73, 2700], [0.74, 5000]]
      },
      "orderbook_down": {
        "bids": [[0.28, 1100], [0.27, 2700], [0.26, 5000]],
        "asks": [[0.30, 1400], [0.31, 3100], [0.32, 4700]]
      },
      "btc_price": 78210.15
    }
  ],
  "total": 720,
  "limit": 3,
  "offset": 0
}

Point-in-time snapshot

GET /v1/snapshots/{identifier}/at

Returns the single closest snapshot to a given timestamp.

curl "https://kwery-api.com/v1/snapshots/will-btc-hit-80k-by-march-31/at?api-key=YOUR_KEY&timestamp=2026-03-09T12:00:00Z&interval=5m"

{
  "identifier": "will-btc-hit-80k-by-march-31",
  "source": "polymarket",
  "interval": "5m",
  "snapshot": {
    "timestamp": "2026-03-09T12:00:00Z",
    "price_up": 0.72,
    "price_down": 0.28,
    "mid_price": 0.72,
    "spread": 0.02,
    "orderbook_up": {
      "bids": [[0.71, 1500], [0.70, 3200]],
      "asks": [[0.73, 1200], [0.74, 2800]]
    },
    "orderbook_down": {
      "bids": [[0.27, 1200], [0.26, 2800]],
      "asks": [[0.29, 1500], [0.30, 3200]]
    },
    "btc_price": 78542.30
  }
}

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 unique identifier (slug). Use /v1/markets to discover active markets.
• 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.