Discovery overview

Discovery endpoints return metadata for markets in our catalog. Responses are served from local storage — not live Polymarket APIs — for predictable latency and consistent snapshots.

Coverage: We currently index Polymarket crypto markets. Markets in other categories are not included in the hosted catalog yet.

Endpoints

Method	Path	Description
`GET`	`/v1/series`	Paginated series catalog
`GET`	`/v1/events`	Paginated events catalog
`GET`	`/v1/markets`	Paginated markets catalog
`GET`	`/v1/markets/{id_or_slug}`	Single market with outcomes and metadata
`GET`	`/v1/tags`	Tag index with occurrence counts

All discovery routes require X-API-Key on the hosted API.

Recommended workflow

Search — GET /v1/markets?search=bitcoin&limit=50
Select — note id or slug from data[]
Detail — GET /v1/markets/{slug} for token ids and resolution state
History — query /prices, /metrics, or /books on the same identifier

List response format

{
  "metadata": {
    "count": 50,
    "limit": 50,
    "next_cursor": "NTA="
  },
  "data": [
    {
      "id": "618831",
      "slug": "will-btc-hit-100k",
      "question": "Will BTC hit $100k?",
      "status": "active",
      "volume": 1250000.0,
      "liquidity": 85000.0,
      "tokens": [
        { "id": "0xabc...", "label": "Yes" },
        { "id": "0xdef...", "label": "No" }
      ]
    }
  ]
}

When metadata.next_cursor is non-null, pass it as the cursor query parameter. See Pagination.

Query parameters

Shared filters

Parameter	Endpoints	Description
`search`	series, events, markets	Case-insensitive full-text search
`limit`	all lists	Page size — default `100`, max `1000`
`cursor`	all lists	Opaque pagination token from `metadata.next_cursor`
`tags`	series, events, markets	Comma-separated tag slugs
`tags_match`	series, events, markets	`any` (default) or `all`
`start_date_min` / `max`	all lists	Filter by start date (ISO date or timestamp)
`end_date_min` / `max`	all lists	Filter by end date (ISO date or timestamp)
`sort`	all lists	`updated_at`, `created_at`, `start_date`, `end_date`
`order`	all lists	`asc` or `desc`

Relationship filters

Parameter	Endpoint	Description
`series_id`, `series_slug`	events	Scope events to a parent series
`event_id`, `event_slug`	markets	Scope markets to a parent event
`include_closed`	markets	Include closed markets when `true`

Market identifiers

{id_or_slug} accepts:

Source market id (e.g. 618831)
URL slug (e.g. will-btc-hit-100k)
Scoped public id (e.g. polymarket:market:618831)

Example

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

Getting started

Discovery

Historical

Reference

Endpoints

Recommended workflow

List response format

Query parameters

Shared filters

Relationship filters

Market identifiers

Example

​Endpoints

​Recommended workflow

​List response format

​Query parameters

​Shared filters

​Relationship filters

​Market identifiers

​Example

Endpoints

Recommended workflow

List response format

Query parameters

Shared filters

Relationship filters

Market identifiers

Example