Quickstart

This guide walks through account setup, API key creation, discovery, and a historical books request on the hosted API.

Prerequisites

A PolyOrderbooks account (free Starter tier)
curl or any HTTP client
Familiarity with ISO-8601 UTC timestamps

1. Create an account and API key

Verify email

Password sign-ups must confirm email via the link we send. Google sign-ups are verified automatically.

Create a key

Open the dashboard → API keys → Create key. Copy the secret immediately — it is shown only once.

Export your key:

export POLYORDERBOOKS_API_KEY="pob_xxxxxxxxxxxxxxxx"

All data requests use:

X-API-Key: pob_xxxxxxxxxxxxxxxx

You may also send Authorization: Bearer pob_…. Dashboard session tokens from login do not work on data routes. See Authentication for security guidance.

2. Confirm your API key

After creating a key, confirm it works and review your plan quota:

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/usage" | jq

Example response:

{
  "plan": "starter",
  "organization": "Acme Research",
  "limits": {
    "requests_per_minute": 60,
    "requests_remaining": 58,
    "granularity_allowed": "60s",
    "max_history_days": 7,
    "data_points": {
      "metrics": true,
      "prices": true,
      "books": true
    }
  },
  "reset_at": 1754140860
}

3. Search the catalog

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets?search=bitcoin&limit=10&sort=updated_at&order=desc" \
  | jq '.data[] | {id, slug, question, status}'

Save a slug from the response for the next step.

4. Fetch order book history

Replace MARKET_SLUG with a value from step 3. On Starter, the finest resolution is 60s and history is limited to the last 7 days:

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets/MARKET_SLUG/books" \
  --get \
  --data-urlencode "start_ts=2026-07-26T00:00:00Z" \
  --data-urlencode "end_ts=2026-07-26T06:00:00Z" \
  --data-urlencode "resolution=60s" \
  | jq '.data'

The response groups book snapshots by outcome label (Yes, No, etc.) with timestamps in UTC.

5. Paginate long ranges

When metadata.next_cursor is present, pass it on the next request (keep the same start_ts, end_ts, and resolution):

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets/MARKET_SLUG/books" \
  --get \
  --data-urlencode "start_ts=2026-07-26T00:00:00Z" \
  --data-urlencode "end_ts=2026-07-26T06:00:00Z" \
  --data-urlencode "resolution=60s" \
  --data-urlencode "cursor=CURSOR_FROM_PREVIOUS_RESPONSE"

See Pagination for discovery list cursors.

Python example

curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets?search=btc&limit=5"

import os
import requests

BASE = "https://api.polyorderbooks.com"
headers = {"X-API-Key": os.environ["POLYORDERBOOKS_API_KEY"]}

markets = requests.get(
    f"{BASE}/v1/markets",
    params={"search": "btc", "limit": 5},
    headers=headers,
    timeout=60,
)
markets.raise_for_status()

slug = markets.json()["data"][0]["slug"]

books = requests.get(
    f"{BASE}/v1/markets/{slug}/books",
    params={
        "start_ts": "2026-07-26T00:00:00Z",
        "end_ts": "2026-07-26T06:00:00Z",
        "resolution": "60s",
    },
    headers=headers,
    timeout=120,
)
books.raise_for_status()
print(books.json()["data"])

Next steps

Plans & limits

Starter, Pro, Scale, and Enterprise capabilities.

Discovery filters

Tags, date ranges, sorting, and market detail.

Historical data

Metrics, books, resolutions, and token-level endpoints.

Rate limits

Quotas, 429 handling, and efficient bulk access.

Getting started

Discovery

Historical

Reference

Prerequisites

1. Create an account and API key

2. Confirm your API key

3. Search the catalog

4. Fetch order book history

5. Paginate long ranges

Python example

Next steps

Plans & limits

Discovery filters

Historical data

Rate limits

​Prerequisites

​1. Create an account and API key

​2. Confirm your API key

​3. Search the catalog

​4. Fetch order book history

​5. Paginate long ranges

​Python example

​Next steps

Plans & limits

Discovery filters

Historical data

Rate limits

Prerequisites

1. Create an account and API key

2. Confirm your API key

3. Search the catalog

4. Fetch order book history

5. Paginate long ranges

Python example

Next steps