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

# Quickstart

> From signup to your first historical order book query in under five minutes.

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

## Prerequisites

* A [PolyOrderbooks account](https://polyorderbooks.com/signup) (free Starter tier)
* `curl` or any HTTP client
* Familiarity with ISO-8601 UTC timestamps

## 1. Create an account and API key

<Steps>
  <Step title="Sign up">
    Register at [polyorderbooks.com/signup](https://polyorderbooks.com/signup) with email/password or Google.
  </Step>

  <Step title="Verify email">
    Password sign-ups must confirm email via the link we send. Google sign-ups are verified automatically.
  </Step>

  <Step title="Create a key">
    Open the [dashboard](https://polyorderbooks.com/dashboard) → **API keys** → **Create key**. Copy the secret immediately — it is shown only once.
  </Step>
</Steps>

Export your key:

```bash theme={null}
export POLYORDERBOOKS_API_KEY="pob_xxxxxxxxxxxxxxxx"
```

All data requests use:

```http theme={null}
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](/authentication) for security guidance.

## 2. Confirm your API key

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

```bash theme={null}
curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/usage" | jq
```

Example response:

```json theme={null}
{
  "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

```bash theme={null}
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**:

```bash theme={null}
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`):

```bash theme={null}
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](/historical/pagination) for discovery list cursors.

## Python example

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
    "https://api.polyorderbooks.com/v1/markets?search=btc&limit=5"
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Plans & limits" icon="tags" href="/pricing">
    Starter, Pro, Scale, and Enterprise capabilities.
  </Card>

  <Card title="Discovery filters" icon="filter" href="/discovery/overview">
    Tags, date ranges, sorting, and market detail.
  </Card>

  <Card title="Historical data" icon="clock" href="/historical/overview">
    Metrics, books, resolutions, and token-level endpoints.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/rate-limits">
    Quotas, 429 handling, and efficient bulk access.
  </Card>
</CardGroup>