Polymarket Markets API — Search & Discovery

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 index Polymarket crypto and sports markets. Pass category=crypto or category=sports to pin a request to one archive, or omit it for the union of both.

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	Comma-separated tag slugs
`tags_match`	series	`any` (default) or `all`
`start_date_min` / `max`	series	Filter by start date (ISO date or timestamp)
`end_date_min` / `max`	series	Filter by end date (ISO date or timestamp)
`sort`	all lists	`updated_at`, `start_date`, `end_date`
`order`	all lists	`asc` or `desc`
`category`	all lists and detail	`crypto` or `sports`; omit for both

Categories

api.polyorderbooks.com serves two archives behind one API. category is accepted on every discovery and history route, on /v1/tags, and on /v1/markets/{id_or_slug}.

Request	Result
`?category=crypto`	The crypto archive only
`?category=sports`	The sports archive only
omitted	Both archives, merged and ordered by `updated_at`
any other value	`400 invalid_category`

Omitting category on /v1/series, /v1/events, and /v1/markets returns a union ordered by updated_at; only updated_at is comparable across both archives. Every row carries a category field, so a mixed page needs no client-side filtering. Sorting by start_date or end_date searches the crypto archive only — a sports query under those sorts returns zero rows rather than an error, which looks like an empty catalog. Pin a category explicitly if you need a deterministic sort on sports data:

curl -s "https://api.polyorderbooks.com/v1/events?search=soccer&sort=start_date&category=sports&limit=5" \
  -H "X-API-Key: $POLYORDERBOOKS_API_KEY"

/v1/tags is the exception to the row shape: it returns a flat array of tag strings rather than row objects, so tags have no category field. Filter by category to keep the tag list to one archive, and do not expect a per-tag category to split a result. Asking for the wrong category on a detail route — a crypto market slug with category=sports, for example — returns 404, not an empty list.

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}'

Related reading: Polymarket historical data guide covers prices, trades, and order books across the available sources.

Getting started

Discovery

Historical

Backtest AI

Reference

Polymarket Markets API — Search & Discovery

Endpoints

Recommended workflow

List response format

Query parameters

Shared filters

Categories

Relationship filters

Market identifiers

Example

​Endpoints

​Recommended workflow

​List response format

​Query parameters

​Shared filters

​Categories

​Relationship filters

​Market identifiers

​Example

Endpoints

Recommended workflow

List response format

Query parameters

Shared filters

Categories

Relationship filters

Market identifiers

Example