resolvedmarkets-com Backtest API

openapi: 3.2.0
info:
  title: Resolved Markets Backtest 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: Backtest
  description: Event-driven backtesting engine and natural-language strategy agent. Pro / Enterprise only.
paths:
  /v1/backtest/templates:
    get:
      tags:
      - Backtest
      operationId: listBacktestTemplates
      summary: Pre-built strategy templates
      responses:
        '200':
          description: Templates list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/BacktestTemplate'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/backtest/run:
    post:
      tags:
      - Backtest
      operationId: runBacktest
      summary: Enqueue a backtest from a strategy spec
      description: Visual-builder path. Costs 25 credits (refunded if the queue is unavailable). Pro / Enterprise only. Returns `202 Accepted` with a `runId` — poll `/v1/backtest/runs/{runId}` or stream via SSE.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - spec
              properties:
                spec:
                  $ref: '#/components/schemas/StrategySpec'
      responses:
        '202':
          description: Queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  runId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - queued
        '400':
          description: Invalid spec.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: Queue unavailable (credits refunded).
  /v1/backtest/agent:
    post:
      tags:
      - Backtest
      operationId: runBacktestAgent
      summary: Natural-language → DSL → enqueue
      description: An LLM compiles a free-form prompt into a `StrategySpec`, validates it, and enqueues a backtest. Costs 50 credits (refunded on LLM failure or refusal). Pro / Enterprise only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
                  maxLength: 2000
                chatId:
                  type: string
                  description: Optional chat thread identifier; auto-generated if omitted.
                setup:
                  type: object
                  properties:
                    crypto:
                      type: string
                      enum:
                      - BTC
                      - ETH
                      - SOL
                      - XRP
                      - DOGE
                      - HYPE
                      - BNB
                      default: BTC
                    timeframe:
                      type: string
                      enum:
                      - 5m
                      - 15m
                      - 1h
                      - 4h
                      - 1d
                      default: 5m
                    maxMarkets:
                      type: integer
                      minimum: 1
                      maximum: 50
                      default: 10
                    positionSizeUsd:
                      type: number
                      exclusiveMinimum: 0
                      maximum: 100000
                      default: 10
                history:
                  type: array
                  description: Prior chat turns (last 10 used).
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                        - user
                        - assistant
                      content:
                        type: string
      responses:
        '202':
          description: LLM compiled + enqueued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  runId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - queued
                  spec:
                    $ref: '#/components/schemas/StrategySpec'
                  humanReadableCode:
                    type: string
                  chatId:
                    type: string
        '400':
          description: Missing/oversized message or invalid setup.
        '422':
          description: Agent refused or LLM output failed validation. Credits refunded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - agent_refused
                  reason:
                    type: string
                  preflight:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          description: LLM upstream unavailable (credits refunded).
        '503':
          description: Queue unavailable (credits refunded).
  /v1/backtest/runs/{runId}:
    get:
      tags:
      - Backtest
      operationId: getBacktestRun
      summary: Backtest run status (polling)
      description: Returns live progress from BullMQ while the job is in-flight, then falls back to ClickHouse-persisted state once finished.
      parameters:
      - name: runId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Run status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BacktestRunStatus'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/backtest/runs/{runId}/stream:
    get:
      tags:
      - Backtest
      operationId: streamBacktestRun
      summary: Backtest progress SSE stream
      description: 'Server-Sent Events stream. Events: `state` (initial), `progress`, `done`, `error`. Connection closes after `done` or `error`.'
      parameters:
      - name: runId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: SSE event stream.
          content:
            text/event-stream:
              schema:
                type: string
                description: SSE `event:` + `data:` frames.
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/backtest/history:
    get:
      tags:
      - Backtest
      operationId: listBacktestHistory
      summary: Recent backtest runs
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Run history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        runId:
                          type: string
                        strategyId:
                          type: string
                          nullable: true
                        status:
                          type: string
                        source:
                          type: string
                        summary:
                          $ref: '#/components/schemas/BacktestSummary'
                        error:
                          type: string
                          nullable: true
                        durationMs:
                          type: integer
                        marketsScanned:
                          type: integer
                        tradesCount:
                          type: integer
                        createdAt:
                          type: string
                          format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/backtest/agent/chats:
    get:
      tags:
      - Backtest
      operationId: listAgentChats
      summary: Recent agent chat threads
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      responses:
        '200':
          description: Chat threads.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        chatId:
                          type: string
                        lastTs:
                          type: string
                          format: date-time
                        preview:
                          type: string
                          description: First ~80 chars of the opening user message.
        '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'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    BacktestRunStatus:
      type: object
      properties:
        status:
          type: string
          enum:
          - queued
          - running
          - done
          - failed
        progress:
          type: number
          description: Present while running; 0..1.
        summary:
          $ref: '#/components/schemas/BacktestSummary'
        trades:
          type: array
          items:
            type: object
            additionalProperties: true
        equityCurve:
          type: array
          items:
            type: object
            additionalProperties: true
        durationMs:
          type: integer
        marketsScanned:
          type: integer
        tradesCount:
          type: integer
        error:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
      required:
      - error
    BacktestTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        spec:
          $ref: '#/components/schemas/StrategySpec'
    BacktestSummary:
      type: object
      additionalProperties: true
      description: Aggregate stats produced by the backtest engine (PnL, win rate, drawdown, etc.). Exact shape evolves with the engine.
    StrategySpec:
      type: object
      description: Backtest strategy spec. Schema defined by `StrategySpecSchema` in the backend; tier-clamped before execution.
      additionalProperties: true
  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`.