resolvedmarkets-com Snapshots API

openapi: 3.2.0
info:
  title: Resolved Markets Snapshots API
  version: 1.2.0
  summary: High-fidelity orderbook data for Polymarket prediction markets and Hyperliquid perpetual futures, plus a backtesting engine and saved-strategy store.
  description: 'REST API for live and historical orderbook snapshots, trades, platform statistics, and event-driven strategy backtesting. Public endpoints (health, public-stats, payment packs) require no authentication. Data endpoints require an `X-API-Key` header where the key starts with `rm_` — get one at https://resolvedmarkets.com/api-keys. Account, subscription, and payment endpoints require a Clerk browser session and are not callable with an API key. WebSocket endpoints exist at `/ws/orderbook` and `/ws/chat` (see Servers / x-websocket).


    Probabilities are USDC prices in 0.01..0.99. Each Polymarket binary market has two tokens — UP (Yes outcome) and DOWN (No outcome) — each with its own orderbook. UP price + DOWN price ≈ 1.00.'
  termsOfService: https://resolvedmarkets.com/pricing
  contact:
    name: Resolved Markets
    email: info@resolvedmarkets.com
    url: https://resolvedmarkets.com
  license:
    name: Commercial — see Pricing page
    url: https://resolvedmarkets.com/pricing
servers:
- url: https://api.resolvedmarkets.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Snapshots
  description: Point-in-time and time-series orderbook snapshots.
paths:
  /v1/markets/{id}/snapshots:
    get:
      tags:
      - Snapshots
      operationId: listMarketSnapshots
      summary: Historical snapshots for a market
      description: Paginated time-series of orderbook snapshots. Filter with `from`, `to`, `side`. Costs 5 credits. Pass `?context=replay` to invoke the free-tier replay quota gate.
      parameters:
      - $ref: '#/components/parameters/ConditionId'
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - name: limit
        in: query
        required: false
        description: 'Maximum rows to return (default 500). The ceiling depends on the mode: **5000** raw, **2000** with `includebook=true` (rows are ~10x heavier), **50000** with `interval=` (candles are tiny, so a wide window fits in one call). Exceeding the applicable ceiling returns 400 naming it — nothing is silently truncated.'
        schema:
          type: integer
          minimum: 1
          maximum: 50000
          default: 500
      - $ref: '#/components/parameters/Side'
      - $ref: '#/components/parameters/IncludeBook'
      - name: touchsize
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: 'Add best_bid_size / best_ask_size — the size resting AT the best bid/ask, in SHARES (bid_depth_total / ask_depth_total are DOLLARS across the whole book, a different question). Dollars capturable at the touch = best_bid_size * best_bid. Off by default: recent partitions store these columns (~1.3x a scalar read) but older ones compute them from the stored bids/asks arrays (~3x), so opting in keeps existing callers on the cheap path. Free and automatic with includebook=true. An unquoted side reports 0. Only valid on this endpoint — 400 elsewhere. Cannot be combined with `interval` (400): a candle aggregates many books and has no single touch level.'
      - name: interval
        in: query
        required: false
        description: Downsample to OHLC candles instead of raw rows — one candle per (bucket x token_side), with open/high/low/close/vwap_mid (all mid-derived) plus avg spread, depth and snapshot_count. Raises the `limit` ceiling to 50000. Cannot be combined with `includebook` or `touchsize` (400) — candles carry neither orderbook levels nor a single touch level.
        schema:
          type: string
          enum:
          - 1s
          - 5s
          - 15s
          - 30s
          - 1m
          - 5m
          - 15m
          - 30m
          - 1h
          - 4h
          - 1d
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: order
        in: query
        required: false
        description: Sort by timestamp. `asc`/`oldest` = chronological; `desc`/`newest` = reverse-chronological. Defaults to `desc`.
        schema:
          type: string
          enum:
          - asc
          - desc
          - oldest
          - newest
          default: desc
      - name: count
        in: query
        required: false
        description: Set to `false` to skip the count() query when total isn't needed (faster).
        schema:
          type: boolean
          default: true
      - name: context
        in: query
        required: false
        description: Pass `replay` to opt into the free-tier replay quota gate (returns 403 `replay_locked` if exceeded).
        schema:
          type: string
          enum:
          - replay
      responses:
        '200':
          description: Paginated snapshot list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  market_id:
                    type: string
                  total:
                    type: integer
                    nullable: true
                  limit:
                    type: integer
                  offset:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Snapshot'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/snapshot:
    get:
      tags:
      - Snapshots
      operationId: getSnapshotAtTime
      summary: Point-in-time snapshot
      description: Snapshot closest to (but not after) the given timestamp. With `marketId`, returns both UP and DOWN sides bundled. Without `marketId`, returns the latest 2 matching rows as a flat array — narrow with `crypto` and/or `timeframe`. Search window is bounded to 1 hour before the requested timestamp.
      parameters:
      - name: timestamp
        in: query
        required: true
        description: ISO-8601 timestamp.
        schema:
          type: string
          format: date-time
      - name: marketId
        in: query
        required: false
        description: Polymarket conditionId. When provided, the response is a `MarketAtTime` object; when omitted, the response is a `Snapshot[]`.
        schema:
          type: string
      - $ref: '#/components/parameters/Crypto'
      - $ref: '#/components/parameters/Timeframe'
      - $ref: '#/components/parameters/IncludeBook'
      responses:
        '200':
          description: Either a `MarketAtTime` (when `marketId` is supplied) or a `Snapshot[]`.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/MarketAtTime'
                - type: array
                  items:
                    $ref: '#/components/schemas/Snapshot'
        '400':
          description: Missing or invalid `timestamp`.
        '404':
          description: No snapshot found in the 1-hour search window.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/snapshot/latest:
    get:
      tags:
      - Snapshots
      operationId: getLatestSnapshots
      summary: Latest snapshots
      description: Up to 5 snapshots from the last 10 minutes, optionally filtered by crypto and timeframe.
      parameters:
      - $ref: '#/components/parameters/Crypto'
      - $ref: '#/components/parameters/Timeframe'
      - $ref: '#/components/parameters/IncludeBook'
      responses:
        '200':
          description: Snapshot array (length ≤ 5).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Snapshot'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Forbidden:
      description: Authenticated, but the caller's tier or role does not permit this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key / Clerk session.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Out of credits or tier does not permit this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    MarketAtTime:
      type: object
      description: Response shape for `GET /api/snapshot` when `marketId` is supplied. Both sides of the binary market at the requested timestamp.
      properties:
        market_id:
          type: string
        timestamp:
          type: string
          format: date-time
        crypto:
          type: string
        timeframe:
          type: string
        crypto_price:
          type: number
          nullable: true
        up:
          $ref: '#/components/schemas/Snapshot'
        down:
          $ref: '#/components/schemas/Snapshot'
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
      required:
      - error
    Snapshot:
      type: object
      properties:
        market_id:
          type: string
        token_id:
          type: string
        token_side:
          type: string
          enum:
          - UP
          - DOWN
        crypto:
          type: string
        timeframe:
          type: string
        timestamp:
          type: string
          format: date-time
        crypto_price:
          type: number
          nullable: true
        best_bid:
          type: number
        best_ask:
          type: number
        mid_price:
          type: number
        spread:
          type: number
        bid_depth_total:
          type: number
        ask_depth_total:
          type: number
        event_timestamp:
          type: string
          format: date-time
          description: When Polymarket emitted the orderbook event (their clock).
        capture_timestamp:
          type: string
          format: date-time
          description: When we processed/stored it (our clock). capture - event = ingestion latency.
        sequence_number:
          type: integer
          description: Per-token count of orderbook events the collector APPLIED. Capture stores at most one row per 50ms per token and drops unchanged books, so a jump between adjacent rows is normal sampling (98.4% of pairs), NOT a dropped update. Resets on re-subscribe; 0 on backfilled rows. Do not build gap detection on it.
        crypto_price_age_ms:
          type: integer
          description: Age in ms of the spot crypto_price at capture (-1 when not tracked). Absent on interval/OHLC rows.
        bids:
          type: array
          description: Only present when `includebook=true`.
          items:
            $ref: '#/components/schemas/OrderbookLevel'
        asks:
          type: array
          description: Only present when `includebook=true`.
          items:
            $ref: '#/components/schemas/OrderbookLevel'
    OrderbookLevel:
      type: object
      properties:
        price:
          type: number
        size:
          type: number
  parameters:
    ConditionId:
      name: id
      in: path
      required: true
      description: Polymarket conditionId (hex string).
      schema:
        type: string
    Crypto:
      name: crypto
      in: query
      required: false
      description: Filter by crypto symbol.
      schema:
        type: string
        enum:
        - BTC
        - ETH
        - SOL
        - XRP
        - DOGE
        - HYPE
        - BNB
    To:
      name: to
      in: query
      required: false
      description: ISO-8601 exclusive upper bound for capture timestamp.
      schema:
        type: string
        format: date-time
    From:
      name: from
      in: query
      required: false
      description: ISO-8601 inclusive lower bound for capture timestamp.
      schema:
        type: string
        format: date-time
    Timeframe:
      name: timeframe
      in: query
      required: false
      description: Polymarket binary timeframe.
      schema:
        type: string
        enum:
        - 5m
        - 15m
        - 1h
        - 4h
        - 1d
    Side:
      name: side
      in: query
      required: false
      description: Restrict to one token side.
      schema:
        type: string
        enum:
        - UP
        - DOWN
    IncludeBook:
      name: includebook
      in: query
      required: false
      description: Include full bid/ask arrays. Defaults to false to avoid expensive ZSTD decompression.
      schema:
        type: boolean
        default: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key prefixed with `rm_`. Generate at https://resolvedmarkets.com/api-keys.
    ClerkSession:
      type: apiKey
      in: cookie
      name: __session
      description: Clerk browser session cookie. Used for account, payment, and admin endpoints. Not callable from API-key clients.
externalDocs:
  description: Interactive API docs and getting-started guides
  url: https://resolvedmarkets.com/docs
x-websocket:
  description: 'WebSocket endpoints. Authenticate via a `{ "type": "auth", "apiKey": "rm_..." }` message after connecting; the server replies `{ "type": "auth", "status": "ok" }` within 5 seconds or closes with code 4001.'
  endpoints:
  - path: /ws/orderbook
    description: 'Real-time orderbook stream. After auth, subscribe with `{ "type": "subscribe", "crypto": "BTC" }`.'
  - path: /ws/chat
    description: Operator chat. Admin connections require a one-time ticket from `POST /v1/admin/chat/ws-ticket`.