Polymarket Market API

This topic covers public Polymarket discovery, recurring crypto history, resolution discussion, and the signed realtime target handoff.

Operations

Method	Path	Required scope	Purpose
`GET`	`/v1/market/polymarket/markets`	`public`	Read Gamma market catalog rows
`GET`	`/v1/market/polymarket/events`	`public`	Read Gamma event catalog rows
`GET`	`/v1/market/polymarket/search`	`public`	Search public markets/events
`GET`	`/v1/market/polymarket/tags/slug/{tag_slug}/related-tags/tags`	`public`	Read related tags
`GET`	`/v1/market/polymarket/resolution-discussion`	`public`	Read official UMA dispute discussion
`GET`	`/v1/market/polymarket/crypto/counts`	`public`	Read official crypto-topic counts
`GET`	`/v1/market/polymarket/crypto/markets`	`public`	Read the official crypto event feed
`GET`	`/v1/market/polymarket/crypto/rtds-chainlink/history`	`public`	Read recurring-market Chainlink OHLCV history
`GET`	`/v1/market/polymarket/crypto/past-results`	`public`	Read prior recurring interval outcomes
`GET`	`/v1/market/polymarket/crypto/target/{event_key}`	`public`	Read the latest target snapshot
`POST`	`/v1/market/polymarket/crypto/target/stream-ticket`	`public`	Issue a signed realtime target stream ticket

Catalog identity

Gamma event, market, condition, and CLOB token IDs are distinct. Orderable outcomes use the numeric CLOB token ID. Preserve event and market metadata for display, but pass the token identity expected by account metadata and order schemas. Search responses include server-derived tradable; do not re-derive live status from only active, closed, or nominal end time.

Instrument search market results additionally include strategy_ticker, in the form POLYMARKET:<market_slug>. Use it in Live/Paper DSL with an explicit order outcome such as YES or NO. It names one binary market; chart_sources retains the concrete outcome-to-token tickers for chart and direct-order APIs. Strategy creation resolves the readable name server-side, so strategy authors do not need to copy token IDs.

Instrument search market rows from list and search contain the market identity, question, outcomes and current outcome prices, volume, liquidity, round times, catalog-reported order-acceptance flag, parent event identity, and compact outcome-to-token ticker mapping. Aliases of those fields, canonical_ticker, full chart source identity, resolution identifiers such as condition_id, and the resolution rules come from an exact market lookup.

Instrument search event rows contain a short summary of every child market, not the full Gamma event or a first-three-market preview. Each child retains its exact market slug, strategy_ticker, outcomes, current outcome prices, volume, liquidity, catalog-reported order-acceptance flag, round times, recurrence description, and compact outcome-to-token ticker mapping. Use an exact market lookup for full chart source identity.

An exact event or market get also returns the resolution rules as description and, when Polymarket names one, resolution_source; an event states them once rather than in each child. For current price, order-book depth, or price history, pass a chart_sources ticker to the market price, order-book, or OHLCV reads.

Recurring crypto data

History and past-results requests require the exact symbol, variant, and official event time boundaries defined in OpenAPI. Stored RTDS Chainlink data is preferred where available and can be supplemented by Polymarket's exposed Chainlink buckets. Response source headers identify the selected path.

Target state and realtime handoff

Target snapshots have a stable eventKey, monotonic revision, selector version, and one of pending, observed, confirmed, or corrected. A confirmed/corrected snapshot can be immutable; pending/observed snapshots must be refreshed.

For realtime updates:

Read or construct the exact event identity.
Call POST .../target/stream-ticket.
Connect to the returned stream_url before expires_in elapses.
Use the included snapshot as the starting revision and apply only newer revisions from the stream.

The signed ticket is scoped to one stream and is not an API key. Request a new ticket after expiry; never place it in long-lived storage.

Resolution and failures

UMA discussion is returned only when its upstream resource can be established. Upstream failure is a 502 UPSTREAM_ERROR, not a successful status=unavailable placeholder. Catalog caches can serve explicitly supported stale data during short Gamma interruptions; freshness and source headers remain the authority.