Orderbooks, Trades & History

This page covers activity signals: orderbook depth, trade prints, and time-series history.

Use it to measure liquidity, detect regime changes, and build market-quality metrics.

API conventions

These routes are read-oriented. They are designed for analytics, monitoring, and automation.

• Auth: Authorization: Bearer $ACCESO_API_KEY

• Base URL: https://<YOUR_ACCESO_API_HOST>

• Response envelope: stable success / data / meta

Example: response envelope (shape)

{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "req_1c2d3e",
    "timestamp": 1765939200
  }
}

• Normalization: timestamps are epoch seconds. IDs are opaque strings.

• Pagination (when available): limit, cursor (opaque), direction=asc|desc (route-dependent)

• Freshness: sources can be eventually consistent. “Latest” routes may be briefly cached.

Always treat cursor as opaque. Cursor semantics are endpoint-specific.

Orderbook snapshots

Orderbooks represent current liquidity. Availability varies by market and venue behavior.

What you typically get

• market_id

• as_of (snapshot timestamp)

• bids[] and asks[] as price levels:

  • price

  • size (or quantity)

  • count (optional, number of orders aggregated)

• best quotes:

  • best_bid

  • best_ask

  • spread (when derived)

Common uses

• depth-at-price and depth-at-spread analysis

• spread monitoring

• imbalance and pressure signals (bid vs ask)

Representative routes

• GET /v1/polymarket/markets/<MARKET_ID>/orderbook

• GET /v1/polymarket/markets/<MARKET_ID>/orderbook?depth=25 (when supported)

Example: fetch an orderbook snapshot

curl -sS \
  -H "Authorization: Bearer $ACCESO_API_KEY" \
  "https://<YOUR_ACCESO_API_HOST>/v1/polymarket/markets/<MARKET_ID>/orderbook"

Orderbooks are a point-in-time view. Do not treat them as a replayable event stream. Use the trade feed for executed activity.

Trades and prints

Trades are the cleanest execution signal. They are optimized for analysis and aggregation.

What you typically get

• trade_id (opaque)

• market_id

• timestamp

• price

• size

• side (buy / sell, when derivable)

Representative routes

• GET /v1/polymarket/markets/<MARKET_ID>/trades?limit=200

• GET /v1/polymarket/markets/<MARKET_ID>/volume?window=1h (route-dependent)

Feeds often include pagination. If you store trades, dedupe by trade_id.

Historical data products

Historical routes support modeling and backtests.

Common outputs:

• price series (sampled snapshots)

• OHLCV-style candles

• volume series per window

Common knobs:

• start, end (epoch seconds)

• interval (deployment-dependent)

Example: fetch trade history over a time range

curl -sS \
  -H "Authorization: Bearer $ACCESO_API_KEY" \
  "https://<YOUR_ACCESO_API_HOST>/v1/polymarket/markets/<MARKET_ID>/trades?start=<TS>&end=<TS>&limit=500"