> ## Documentation Index > Fetch the complete documentation index at: https://docs.polysimulator.com/llms.txt > Use this file to discover all available pages before exploring further. # Simulate Fill ## OpenAPI ````yaml /openapi.json post /v1/simulation/fill openapi: 3.1.0 info: title: Polysimulator API summary: HFT-style paper-trading API for Polymarket simulation. description: >- PolySimulator HFT API v1 — Virtual trading environment for Polymarket prediction markets. Practice trading with real market data using paper money, then switch to live trading by changing only your API credentials. termsOfService: https://polysimulator.com/legal/terms contact: name: PolySimulator url: https://polysimulator.com license: name: Proprietary — usage subject to Polysimulator Terms of Service url: https://polysimulator.com/legal/terms version: 1.0.0-beta servers: - url: https://api.polysimulator.com description: Production - url: https://staging-api.polysimulator.com description: Staging security: - ApiKeyAuth: [] tags: - name: API Keys description: >- Bootstrap, create, list, revoke API keys, mint short-lived WebSocket tokens, list rate-limit tiers. - name: Account description: >- Balance, equity curve, portfolio composition, open positions, trade history. - name: Export description: >- Pro data export — streamed CSV downloads for offline analysis, backtesting, and tax/accounting. v1: GET /v1/export/trades.csv (FILLED trades, keyset-paginated). Dual session + API-key auth. - name: Profile Analysis description: >- Trading-profile analytics — Sharpe, win-rate, drawdown, holding-period histograms. - name: Wallets description: >- Multi-wallet management (MAIN / SANDBOX / API / COMPETITION). List, switch active wallet, per-wallet balance + history. - name: Trading description: >- Place, cancel, batch, and list orders. Cancel-all + cancel-market-orders sweep endpoints. PolySimulator-native order surface. - name: Market Data description: >- Polymarket market metadata + live prices (POST /v1/prices/batch, /v1/markets, /v1/markets/{condition_id}/candles). - name: CLOB Read (Public) description: >- Polymarket-shape read endpoints (book, midpoint, spread, price, last-trade-price, tick-size, neg-risk, time). Wire-compatible with py-clob-client. - name: CLOB Compat description: >- Polymarket-shape order surface (POST /v1/order with nested body, POST /v1/orders batch, GET /v1/data/orders PM-envelope). Use these for drop-in py-clob-client compatibility. - name: WebSocket description: >- WebSocket subscription endpoints — /v1/ws/prices for live market data, /v1/ws/executions for order-state updates. - name: Billing description: >- Stripe-backed subscriptions, top-ups, customer portal, refund policy, paid-tier resets. - name: Status description: System-status surface — uptime, component health, recent incident markers. - name: Health description: >- Health, liveness, readiness, and authenticated-identity probes (/v1/health, /v1/health/live, /v1/health/ready, /v1/me). - name: Football description: >- Football / World-Cup 2026 enrichment — live score, minute, momentum, possession, xG, shotmap, commentary, lineups, group standings, knockout bracket, and head-to-head. Public read-only sports facts the UI merges with tradable Polymarket prices; degrades to empty shapes on upstream failure. - name: Simulation description: >- Historical fill simulation, archive coverage, and curated backtests. Dark until FEATURE_SIMULATION_API_ENABLED is on. - name: Integrations description: >- Outbound alert delivery integrations (Discord) — per-user subscriptions managed under /v1/integrations/*. Mirrors the /me/webhook + /me/push routes for the older channels. paths: /v1/simulation/fill: post: tags: - Simulation summary: Simulate Fill operationId: simulateFill parameters: - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key - name: POLY_API_KEY in: header required: false schema: anyOf: - type: string - type: 'null' title: Poly Api Key - name: Poly-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: Poly-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SimulateFillRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SimulateFillResponse' headers: X-RateLimit-Limit: description: >- Requests permitted in the current minute window for this key's tier. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the current minute window. schema: type: string X-RateLimit-Reset: description: Unix-seconds timestamp when the current minute window resets. schema: type: string X-RateLimit-Limit-Per-Second: description: Requests permitted per second for this key's tier. schema: type: string X-RateLimit-Remaining-Per-Second: description: Requests remaining in the current one-second window. schema: type: string X-RateLimit-Tier: description: Rate-limit tier name applied to this request (free, pro, ...). schema: type: string X-Polysim-RateLimit-Limit: description: Alias of X-RateLimit-Limit (requests per minute for this tier). schema: type: string X-Polysim-RateLimit-Remaining: description: Alias of X-RateLimit-Remaining (requests remaining this minute). schema: type: string X-Polysim-RateLimit-Reset: description: Alias of X-RateLimit-Reset (minute-window reset, unix seconds). schema: type: string X-Polysim-RateLimit-Limit-Per-Second: description: Alias of X-RateLimit-Limit-Per-Second. schema: type: string X-Polysim-RateLimit-Remaining-Per-Second: description: Alias of X-RateLimit-Remaining-Per-Second. schema: type: string X-Polysim-RateLimit-Tier: description: Alias of X-RateLimit-Tier (tier name applied to this request). schema: type: string X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '401': description: Invalid or expired API key content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '403': description: Missing required permission or plan volume cap content: application/json: schema: $ref: '#/components/schemas/PlanDenialError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '409': description: Idempotency key reuse content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '422': description: Body validation failure or universe exclusion content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '429': description: Rate limit or simulation volume cap exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string '503': description: Metering, job store, or archive unavailable content: application/json: schema: $ref: '#/components/schemas/ApiError' headers: X-Polysim-Code: description: >- Stable short code identifying the error class. SDK consumers should branch on this header rather than the body text. Domain codes (INVALID_KEY, MARKET_NOT_FOUND, RATE_LIMIT_EXCEEDED, …) are preferred; HTTP_ fallbacks ship when no domain code applies. The full list is mirrored in /llms.txt under ‘Error Format’. schema: type: string enum: - INVALID_KEY - MISSING_API_KEY - INSUFFICIENT_PERMISSION - INSUFFICIENT_BALANCE - MARKET_CLOSED - INVALID_ORDER_MIN_TICK_SIZE - MARKET_NOT_FOUND - ORDER_NOT_FOUND - RATE_LIMIT_EXCEEDED - BOOK_UNAVAILABLE - INVALID_TOKEN_ID - VALIDATION_FAILED - UPGRADE_REQUIRED - ACCESS_RESTRICTED - COHORT_FULL - AUTH_STATE_INCOMPLETE - INTERNAL_ERROR - TOKEN_NOT_FOUND - INVALID_CURSOR - UPSTREAM_UNAVAILABLE - UNSUPPORTED_ORDER_TYPE - DUPLICATE_CLIENT_ORDER_ID - ORDER_EXECUTION_FAILED - DEADLINE_OVERSHOT_BUT_PERSISTED - PERSISTENCE_UNKNOWN - INVALID_BODY - INVALID_SOURCE - CLOSED_BETA - API_PRO_COMING_SOON - TIER_KEY_LIMIT_EXCEEDED - INVALID_REQUEST - INVALID_WINDOW - BACKTEST_MONTHLY_CAP - BACKTEST_MARKET_CAP - BACKTEST_WINDOW_CAP - SIMULATION_HOURS_EXCEEDED - METERING_UNAVAILABLE - JOB_STORE_UNAVAILABLE - CONDITION_HOUR_NOT_COVERED - ARCHIVE_UNAVAILABLE - ARCHIVE_NOT_FOUND - UNIVERSE_EXCLUDED - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_CONFLICT_PENDING - NOT_FOUND - HTTP_400 - HTTP_401 - HTTP_403 - HTTP_404 - HTTP_409 - HTTP_422 - HTTP_429 - HTTP_500 - HTTP_502 - HTTP_503 X-Request-Id: description: >- Request id for log correlation. Echoes the caller's ``X-Request-Id`` when supplied, otherwise a server-minted UUID. Stamped on every response (success and error). schema: type: string components: schemas: SimulateFillRequest: properties: condition_id: type: string maxLength: 256 minLength: 1 title: Condition Id token_id: anyOf: - type: string maxLength: 256 - type: 'null' title: Token Id outcome: type: string maxLength: 200 title: Outcome default: 'Yes' side: type: string enum: - BUY - SELL title: Side default: BUY shares: type: string title: Shares description: Share quantity as a decimal string at: type: string title: At description: UTC ISO-8601 timestamp of the reconstructed book fill_model: type: string enum: - midpoint - top_of_book - depth_walk - depth_walk_depletion title: Fill Model default: depth_walk limit_price: anyOf: - type: string - type: 'null' title: Limit Price description: Optional limit. BUY will not walk above; SELL will not walk below. latency_ms: type: integer maximum: 60000 minimum: 0 title: Latency Ms description: >- Round-trip latency to model, in milliseconds. The order is priced against the book as it stood when the order ARRIVED, not when it was decided. RECOMMENDED: 104, our measured production API p50 — a backtest at 0 ms assumes you traded on a book nobody could have seen yet, which flatters fast strategies. It defaults to 0 only because changing it would silently move every existing caller's results without a line of their code changing. default: 0 queue_position: type: string title: Queue Position description: >- Position in the queue at each price level: 0.0 = front (filled first), 1.0 = back (filled last). Only affects RESTING orders. Defaults to 1.0 deliberately. We cannot observe our own order in the venue's queue, so the only honest default is to assume you were last. Assuming the front is the easiest way to manufacture an edge that does not survive live trading. default: '1.0' type: object required: - condition_id - shares - at title: SimulateFillRequest examples: - at: '2026-08-04T18:00:00Z' condition_id: '0xabc123' fill_model: depth_walk outcome: 'Yes' shares: '10' side: BUY SimulateFillResponse: properties: vwap_fill_price: anyOf: - type: string - type: 'null' title: Vwap Fill Price filled_shares: type: string title: Filled Shares remaining_shares: type: string title: Remaining Shares slippage_bps: anyOf: - type: string - type: 'null' title: Slippage Bps impact_bps: anyOf: - type: string - type: 'null' title: Impact Bps levels_used: type: integer title: Levels Used fee: type: string title: Fee book_age_ms: anyOf: - type: integer - type: 'null' title: Book Age Ms price_source: type: string title: Price Source confidence: type: string enum: - high - medium - low - provisional title: Confidence fill_model: type: string enum: - midpoint - top_of_book - depth_walk - depth_walk_depletion title: Fill Model fee_model: type: string title: Fee Model token_id: anyOf: - type: string - type: 'null' title: Token Id comp_token_id: anyOf: - type: string - type: 'null' title: Comp Token Id provenance: $ref: '#/components/schemas/Provenance' leakage: $ref: '#/components/schemas/LeakageDisclosure' type: object required: - vwap_fill_price - filled_shares - remaining_shares - slippage_bps - impact_bps - levels_used - fee - book_age_ms - price_source - confidence - fill_model - fee_model - provenance - leakage title: SimulateFillResponse examples: - book_age_ms: 0 comp_token_id: tok_no confidence: high fee: '0.1200' fee_model: polymarket_v2_taker fill_model: depth_walk filled_shares: '10.0000' impact_bps: '0' leakage: book_depth_available: true data_source: archive fee_model: polymarket_v2_taker fill_model: depth_walk missing_periods: [] signals_used_pre_decision_data_only: true slippage_model: book_walk levels_used: 1 price_source: archive provenance: bbo_confidence: high deduped_events: 0 ghost_guard_triggered: false hour: 2026-08-04T18 hour_status: valid remaining_shares: '0.0000' slippage_bps: '0' token_id: tok_yes vwap_fill_price: '0.4000' ApiError: properties: error: type: string title: Error description: Stable machine-readable error code; also returned in X-Polysim-Code. message: anyOf: - type: string - type: 'null' title: Message description: Human-readable error description. Never branch on this value. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Additional context populated for verbose responses. request_id: anyOf: - type: string - type: 'null' title: Request Id description: Support correlation id; always returned in X-Request-Id. type: object required: - error title: ApiError description: |- Structured error response for all API v1 endpoints. ``error`` is the stable machine-readable code and ``message`` is human prose. SDK consumers must branch on ``error`` (or the identical ``X-Polysim-Code`` header), never on ``message``. Diagnostic ``details`` and the in-body ``request_id`` are added only when callers opt in with ``X-Polysim-Verbose: true``; ``X-Request-Id`` is always present. PlanDenialError: properties: error: type: string title: Error description: Stable machine-readable error code; also returned in X-Polysim-Code. message: anyOf: - type: string - type: 'null' title: Message description: Human-readable error description. Never branch on this value. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Additional context populated for verbose responses. request_id: anyOf: - type: string - type: 'null' title: Request Id description: Support correlation id; always returned in X-Request-Id. feature_key: anyOf: - type: string - type: 'null' title: Feature Key description: Entitlement key the caller's plan lacks. upgrade_url: anyOf: - type: string - type: 'null' title: Upgrade Url description: Where to upgrade; carries ?feature=. limit: anyOf: - type: integer - type: 'null' title: Limit description: The plan cap that was hit. type: object required: - error title: PlanDenialError description: >- 403 body for a plan-imposed cap, carrying the fields that make it actionable. A subclass rather than three new fields on ``ApiError``: that model is the error shape for EVERY ``/v1`` endpoint, and widening it would publish ``upgrade_url`` and ``limit`` on routes that have nothing to do with plans. Subclassing keeps all four base fields, so nothing changes for existing consumers, and scopes the new three to the responses that actually carry them. Provenance: properties: hour_status: type: string enum: - valid - degraded - missing - quarantined - partial title: Hour Status bbo_confidence: type: string enum: - high - medium - low - provisional title: Bbo Confidence ghost_guard_triggered: type: boolean title: Ghost Guard Triggered default: false deduped_events: type: integer title: Deduped Events default: 0 hour: anyOf: - type: string - type: 'null' title: Hour type: object required: - hour_status - bbo_confidence title: Provenance LeakageDisclosure: properties: data_source: type: string title: Data Source missing_periods: items: type: string type: array title: Missing Periods fill_model: type: string title: Fill Model fee_model: type: string title: Fee Model book_depth_available: type: boolean title: Book Depth Available signals_used_pre_decision_data_only: type: boolean title: Signals Used Pre Decision Data Only default: true slippage_model: type: string title: Slippage Model default: none latency_ms: type: integer title: Latency Ms default: 0 queue_position: type: string title: Queue Position default: '1.0' queue_position_note: type: string title: Queue Position Note default: >- 1.0 = back of queue. We cannot observe our own order in the venue's queue, so the honest default is to assume you were filled last. type: object required: - data_source - fill_model - fee_model - book_depth_available title: LeakageDisclosure securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Issue from /v1/keys (or admin-issued for enterprise tier). ````