PolyOrderbooks for AI Agents

Coding agents, LLM-powered trading tools, and crawlers can discover PolyOrderbooks three ways — plain-text index files, an MCP server, or the API directly.

Machine-readable index files

Both properties ship llms.txt files in the format proposed by the llms.txt working group.

Product site: https://polyorderbooks.com/llms.txt — product pages, plan tiers, and where to go next
API docs: https://docs.polyorderbooks.com/llms.txt — the developer reference, grouped by use case
API spec: https://docs.polyorderbooks.com/openapi.json — machine-readable OpenAPI definition for the REST endpoints

Each lists only the highest-signal pages, so an agent pulling the index can follow the one or two links that match the task instead of crawling the whole property.

MCP server

The PolyOrderbooks MCP server is the fastest path for a chat or agent that needs archive queries — full L2 ladders, per-outcome price series, and market metrics — without writing REST calls. Install and prompt patterns: MCP server.

Backtest AI (natural-language backtesting)

POST /v1/ai/backtest turns a plain-English crypto up/down strategy into a replayed backtest over resolved Polymarket markets from our archive. An agent uses it to answer questions like “would buying DOWN when the DOWN token crosses below 0.45 on BTC 15m have been profitable?” Request:

{
  "prompt": "Buy DOWN when the DOWN token price falls below 0.45 within the first 5 minutes of BTC 15m markets.",
  "sampleSize": 100,
  "budget": 50
}

Response:

{
  "prompt": "…",
  "strategy": {
    "market": { "coin": "btc", "market_type": "15m" },
    "side": "down",
    "entry": [{ "type": "price", "token": "down", "comparator": "<", "threshold": 0.45, "within_seconds": 300 }],
    "exit": { "take_profit": null, "stop_loss": null, "hold_to_expiry": true },
    "budget_per_trade": 50,
    "sample_size": 100
  },
  "report": {
    "sample_size": 100,
    "markets_found": 120,
    "markets_traded": 3,
    "win_rate": 0.333333,
    "total_pnl": -12.4,
    "equity_curve": [-12.4],
    "trades": [ ]
  }
}

Every run returns the same response shape, and the strategy block is the exact specification the engine executed — market, side, entry conditions, and exit rules — so an agent can always see how its prompt was interpreted. When a request can’t be turned into a strategy, the endpoint explains the problem in the error body rather than silently changing the plan. The engine only ever evaluates prediction-market token prices and order books — it has no BTC/ETH spot price and no percentages. Prompts that depend on an asset price or a percentage are rejected with 400 {"error": "unsupported_signal"} rather than silently approximated.

Boundary and plan

Signals: token prices (0..1) and L2 books for Polymarket crypto up/down markets — no external reference price
Engine fills against the captured ladder (book_ladder), falling back to the best quote or last price (best_quote / last_price); settlement fills are marked settlement
Exits: take_profit, stop_loss, expiry, or end_of_window
History: the optional days field (1–30) selects how far back to look and is capped by the plan — Starter: 1 day; paid plans: 30 days.
Access: every authenticated plan can call it with an API key. Plans differ in the monthly run quota and the backtest window — non-AI plans get 1 free-text + 3 Strategy Builder runs per month; AI plans (backtest-ai, ai-only, dNN-ai SKUs) get 500 free-text + unlimited builder. Over-quota calls return 429 {"error": "limit_reached"}. See Pricing and Authentication

Direct API call with a key:

curl -X POST https://api.polyorderbooks.com/v1/ai/backtest \
  -H "X-API-Key: pob_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Buy DOWN when the DOWN token price falls below 0.45 within the first 5 minutes of BTC 15m markets.","sampleSize":25,"budget":50}'

Structured Strategy Builder specs go in the same request’s strategy field (snake_case). Full request and response shapes are in the Backtest AI section of this portal. Interactive: Backtest AI (login required).

Guidance for agents

Prefer llms.txt over full-site crawls; follow at most one or two links from it.
For historical queries, one MCP call replaces several REST round-trips.
Backtest AI answers directional “what would have happened” questions without exposing raw archives — keep prompts to the strategy shape, not market lists. Raw discovery still uses GET /v1/markets and friends.
System messages: you are working against a real historical archive, ~250ms capture; treat backtest results as evidence on the sample actually traded (markets_traded vs markets_found).

Getting started

Discovery

Historical

Backtest AI

Reference

PolyOrderbooks for AI Agents

Machine-readable index files

MCP server

Backtest AI (natural-language backtesting)

Boundary and plan

Guidance for agents

​Machine-readable index files

​MCP server

​Backtest AI (natural-language backtesting)

​Boundary and plan

​Guidance for agents

Machine-readable index files

MCP server

Backtest AI (natural-language backtesting)

Boundary and plan

Guidance for agents