> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polyorderbooks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PolyOrderbooks for AI Agents

> What AI agents and LLM crawlers can use — llms.txt discovery files, the official MCP server, and the natural-language Backtest AI endpoint.

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](https://llmstxt.org/).

* **Product site:** [https://polyorderbooks.com/llms.txt](https://polyorderbooks.com/llms.txt) — product pages, plan tiers, and where to go next
* **API docs:** [https://docs.polyorderbooks.com/llms.txt](https://docs.polyorderbooks.com/llms.txt) — the developer reference, grouped by use case
* **API spec:** [https://docs.polyorderbooks.com/openapi.json](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](/integrations/mcp).

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
  },
  "source": "llm",
  "report": {
    "sample_size": 100,
    "markets_found": 120,
    "markets_traded": 3,
    "win_rate": 0.333333,
    "total_pnl": -12.4,
    "equity_curve": [-12.4],
    "trades": [ ]
  }
}
```

Two parse paths, one response shape:

* **LLM parse** (`source: "llm"`) — a free-tier Gemini-backed model converts the prompt into the strict strategy JSON.
* **Rule fallback** (`source: "rules"`) — if the model is unavailable or the response is invalid, a deterministic keyword parser takes over, and a `note` says so.

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`
* Access: **Pro plan or above**, bearer-authenticated. Free Starter keys get `403 {"error": "plan_required"}`. See [Pricing](/pricing) and [Authentication](/authentication)

Interactive: [Backtest AI](https://polyorderbooks.com/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, \~1-second capture; treat backtest results as evidence on the sample actually traded (`markets_traded` vs `markets_found`).