resolvedmarkets-com Markets API

openapi: 3.2.0
info:
  title: Resolved Markets 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: Markets
  description: Polymarket prediction market data.
paths:
  /v1/categories:
    get:
      tags:
      - Markets
      operationId: listCategories
      summary: List enabled categories
      description: All enabled categories with active market counts and capture rates.
      responses:
        '200':
          description: Category list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    category:
                      type: string
                    displayName:
                      type: string
                    activeMarkets:
                      type: integer
                    captureIntervalMs:
                      type: integer
                    refreshIntervalMs:
                      type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/markets/live:
    get:
      tags:
      - Markets
      operationId: listLiveMarkets
      summary: List active markets
      description: Returns markets currently being tracked, filtered by the caller's tier policy. Filter further with `category`, `subcategory`, `crypto` and `timeframe`, and cap the payload with `limit`/`offset` — an unfiltered call on a full-access tier returns ~2,000 markets.
      parameters:
      - $ref: '#/components/parameters/Category'
      - $ref: '#/components/parameters/Subcategory'
      - name: crypto
        in: query
        required: false
        description: Restrict to one coin (BTC/ETH/SOL/XRP/DOGE/HYPE/BNB). Only crypto markets carry this field, so it also excludes every non-crypto category.
        schema:
          type: string
      - name: timeframe
        in: query
        required: false
        description: Restrict to one timeframe. A per-config discriminator, not a cadence — crypto uses 5m/15m/1h/4h/1d/hit-price, other categories use their own values (weather `daily-high`, sports `game`, …).
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Cap the number of markets returned, applied after the filters above. Passing `limit` or `offset` sorts the response soonest-expiring first (`expiresIn` ascending, ties broken by `conditionId`), so a truncated list is the NEXT N markets rather than an arbitrary N. With neither, markets are returned in discovery order.
        schema:
          type: integer
          minimum: 1
          maximum: 5000
      - name: offset
        in: query
        required: false
        description: Row offset for paging a windowed list. Also applies the soonest-expiring-first sort.
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Array of live markets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Market'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/markets/by-slug/{slug}:
    get:
      tags:
      - Markets
      operationId: getMarketBySlug
      summary: Lookup market by slug
      description: Fuzzy-matched slug lookup (e.g. `btc-updown-5m`). Falls back to ClickHouse for closed markets when the slug looks like a conditionId.
      parameters:
      - $ref: '#/components/parameters/Slug'
      responses:
        '200':
          description: Market record (live or historical).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Market'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/markets/by-slug/{slug}/orderbook:
    get:
      tags:
      - Markets
      operationId: getOrderbookBySlug
      summary: Live orderbook by slug
      parameters:
      - $ref: '#/components/parameters/Slug'
      responses:
        '200':
          description: UP and DOWN orderbooks plus market metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  market_id:
                    type: string
                  crypto:
                    type: string
                  timeframe:
                    type: string
                  slug:
                    type: string
                  crypto_price:
                    type: number
                    nullable: true
                  up:
                    $ref: '#/components/schemas/TokenBook'
                  down:
                    $ref: '#/components/schemas/TokenBook'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/markets/{id}/orderbook:
    get:
      tags:
      - Markets
      operationId: getOrderbook
      summary: Live orderbook by conditionId
      description: In-memory live orderbook for both UP and DOWN tokens. Free-tier callers receive depth-truncated books (20 levels per side).
      parameters:
      - $ref: '#/components/parameters/ConditionId'
      responses:
        '200':
          description: UP and DOWN orderbooks plus metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  marketId:
                    type: string
                  crypto:
                    type: string
                  timeframe:
                    type: string
                  cryptoPrice:
                    type: number
                    nullable: true
                  up:
                    $ref: '#/components/schemas/TokenBook'
                  down:
                    $ref: '#/components/schemas/TokenBook'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/markets/{id}/summary:
    get:
      tags:
      - Markets
      operationId: getMarketSummary
      summary: Aggregated market stats
      description: Spread, depth, price range, and per-side breakdown over the last 7 days.
      parameters:
      - $ref: '#/components/parameters/ConditionId'
      responses:
        '200':
          description: Aggregated stats.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/markets/history/recent:
    get:
      tags:
      - Markets
      operationId: listRecentMarkets
      summary: Tracked markets, recent first
      description: All tracked markets with snapshot counts, live status, and per-request `replay_locked` overlay. Reads the pre-aggregated `market_stats` materialized view and merges with the live market registry. Tier-scoped.
      parameters:
      - $ref: '#/components/parameters/Category'
      - $ref: '#/components/parameters/Subcategory'
      - $ref: '#/components/parameters/Crypto'
      - $ref: '#/components/parameters/Timeframe'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Recent markets list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_markets:
                    type: integer
                  total_snapshots:
                    type: integer
                  live_count:
                    type: integer
                  closed_count:
                    type: integer
                  markets:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecentMarketRow'
                  replay_quota:
                    type: object
                    properties:
                      unlimited:
                        type: boolean
                      tier:
                        type: string
                      perBucket:
                        type: integer
                      allowedCount:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          description: ClickHouse temporarily unavailable.
  /v1/markets/history:
    get:
      tags:
      - Markets
      operationId: listMarketHistory
      summary: Full market history
      description: All tracked markets — filter by category, subcategory, crypto, and timeframe. Tier-scoped.
      parameters:
      - $ref: '#/components/parameters/Category'
      - $ref: '#/components/parameters/Subcategory'
      - $ref: '#/components/parameters/Crypto'
      - $ref: '#/components/parameters/Timeframe'
      responses:
        '200':
          description: Full market list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_markets:
                    type: integer
                  total_snapshots:
                    type: integer
                  live_count:
                    type: integer
                  closed_count:
                    type: integer
                  markets:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecentMarketRow'
        '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'
    RateLimited:
      description: Rate limit exceeded.
      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'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ConditionId:
      name: id
      in: path
      required: true
      description: Polymarket conditionId (hex string).
      schema:
        type: string
    Subcategory:
      name: subcategory
      in: query
      required: false
      description: Filter by subcategory (e.g. BTC, NBA, FOMC).
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return (max 500).
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    Crypto:
      name: crypto
      in: query
      required: false
      description: Filter by crypto symbol.
      schema:
        type: string
        enum:
        - BTC
        - ETH
        - SOL
        - XRP
        - DOGE
        - HYPE
        - BNB
    Slug:
      name: slug
      in: path
      required: true
      description: Market slug (e.g. `btc-updown-5m`). Fuzzy matched.
      schema:
        type: string
    Timeframe:
      name: timeframe
      in: query
      required: false
      description: Polymarket binary timeframe.
      schema:
        type: string
        enum:
        - 5m
        - 15m
        - 1h
        - 4h
        - 1d
    Category:
      name: category
      in: query
      required: false
      description: Filter by market category.
      schema:
        type: string
        enum:
        - crypto
        - sports
        - economics
        - weather
        - social
        - exchange
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
      required:
      - error
    RecentMarketRow:
      type: object
      properties:
        market_id:
          type: string
        crypto:
          type: string
        timeframe:
          type: string
        category:
          type: string
        subcategory:
          type: string
        first_seen:
          type: string
          format: date-time
        last_seen:
          type: string
          format: date-time
        snapshot_count:
          type: integer
        is_live:
          type: boolean
        end_date:
          type: string
          format: date-time
          nullable: true
        question:
          type: string
          nullable: true
        replay_locked:
          type: boolean
          description: 'Overlay added per-request: true if the caller''s tier does not permit replaying this market.'
    Market:
      type: object
      properties:
        market_id:
          type: string
        conditionId:
          type: string
        slug:
          type: string
        question:
          type: string
        category:
          type: string
        subcategory:
          type: string
        crypto:
          type: string
        timeframe:
          type: string
        tokenIds:
          type: array
          items:
            type: string
        tokenIdUp:
          type: string
        tokenIdDown:
          type: string
        endDate:
          type: string
          format: date-time
        expired:
          type: boolean
        expiresIn:
          type: integer
          description: Milliseconds until endDate; 0 if expired.
    OrderbookLevel:
      type: object
      properties:
        price:
          type: number
        size:
          type: number
    TokenBook:
      type: object
      properties:
        token_id:
          type: string
        side:
          type: string
          enum:
          - UP
          - DOWN
        best_bid:
          type: number
        best_ask:
          type: number
        mid:
          type: number
        spread:
          type: number
        bids:
          type: array
          items:
            $ref: '#/components/schemas/OrderbookLevel'
        asks:
          type: array
          items:
            $ref: '#/components/schemas/OrderbookLevel'
        depth5_bid:
          type: number
        depth5_ask:
          type: number
  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`.