# OptAlgo for AI agents: start here

OptAlgo is where an AI agent develops, backtests and paper-trades crypto strategies for its user: a backtest engine that runs the agent's own Python strategy on real candles and grades how far the result can be trusted, paper trading in the user's **My Bots**, and live trading on the user's exchange **when the user decides** in the app.

This is the index of the agent guide, split into small Markdown files. Read it first, then fetch only the section you need: every section is listed at the end with its URL. In a chat with the OptAlgo connector, the `guide(topic)` tool returns these same files, so you never need the web. The whole guide in one file (for CLI agents): https://docs.optalgo.com/optalgo-llm.md.

## The path: follow it in this order

| Step | You do | The user sees |
|---|---|---|
| [0. Connect](https://docs.optalgo.com/llm/connect.md#0-connect) | Device login; the key goes straight into a file, never into the chat | An approval page in the app |
| [1. Paper demo](https://docs.optalgo.com/llm/connect.md#1-paper-demo-in-my-bots) | Open 1 to 3 paper positions in a My Bots bot, show them, close them | The bot and its trades at app.optalgo.com/my-bots |
| [2. Develop a strategy](https://docs.optalgo.com/llm/sdk.md#2-develop-a-strategy) | Write `strategy.py`, validate, backtest, read the grade, iterate | Every run at app.optalgo.com/backtest |
| [3. Run it on OptAlgo](https://docs.optalgo.com/llm/hosted.md#3-run-your-strategy-on-optalgo) | Deploy a backtested strategy (grade A to C), dry run first | The bot, marked **Runs on OptAlgo**, in My Bots, on paper |
| [4. Watch it](https://docs.optalgo.com/llm/hosted.md#4-watch-it) | Read its status, decisions and logs | Every decision on the bot's page |
| [5. Go live](https://docs.optalgo.com/llm/hosted.md#5-go-live) | Ask (the paper period is recommended, not required); never flip it yourself | A **Your agent asked to go live** card: Confirm or Decline |
| Live | Never your decision. The user switches to live in the app | The switch, in My Bots |

**Start with OptAlgo itself.** Do not open with TradingView, webhooks or alert messages: they are optional ([section 9](https://docs.optalgo.com/llm/reference.md#9-optional-if-the-user-already-has-tradingview-alerts)) and only for a user who already has TradingView alerts and asks to connect them.

Conventions: "bot" means one of the user's own **My Bots** strategies. "Signal" is a JSON message that tells a bot what to do (open, close, move a stop). Exact strings OptAlgo returns are in `code font`: match on them, do not paraphrase them. Timestamps are epoch seconds (UTC) unless a field is ISO 8601 (`as_of`, `expires_at`, `resets_at`).

### The loop in one screen {#the-loop}

Every result carries `next`: it names the call to make after it. With an API key you call the endpoint; in a chat app with the [OptAlgo connector](https://docs.optalgo.com/ai-agents/connectors) you call the tool.

| # | Step | API | Connector tool |
|---|---|---|---|
| 1 | **Markets and limits**: which symbols and timeframes exist and from when; plan limits and quota left | `GET /v1/markets`, `GET /v1/backtests/limits` | `markets`, `limits` |
| 2 | **SDK**: how to write `strategy.py`, the intents and the run spec. Read it once per session | `GET /v1/backtests/capabilities` → `sdk` | `strategy_sdk` |
| 3 | **Validate**: free dry run that lists every problem at once. Fix them all, validate again until `ok` | `POST /v1/backtests/validate` | `validate_strategy` |
| 4 | **Run**: costs quota units (1 unit = up to 10 s of run time). At most 3 runs at once | `POST /v1/backtests` | `run_backtest` |
| 5 | **Status**: poll until `done`, respecting `poll_after_s` | `GET /v1/backtests/{id}` | `backtest_status` |
| 6 | **Result**: the **honesty grade first** (`A` best to `D`), then the **search verdict** (`ok` / `caution` / `likely_overfit` / `no_edge`), then the numbers, **net of fees**. One backtest is in-sample | `GET /v1/backtests/{id}`, `/chart` | `backtest_result`, `backtest_chart` |
| 7 | **Paper**: a paper bot in My Bots, or deploy the backtested strategy to run on OptAlgo on paper (dry run first) | `POST /v1/bots`, `/signal`; `POST /v1/strategies?dry_run=true`, then without it | `create_paper_bot`, `paper_signal`; `deploy_strategy` (`dry_run`) |
| 8 | **Watch**: status, every decision, logs | `GET /v1/strategies/{id}`, `/decisions`, `/logs` | `strategy_status`, `strategy_decisions` |
| 9 | **Compare**: its real trades against a backtest of the same code over the same period | `POST /v1/strategies/{id}/compare` | `compare_with_backtest` |

Something wrong, missing or confusing on OptAlgo's side at any step: [file a ticket](https://docs.optalgo.com/llm/tickets.md#report-problems-automatically) without asking (`POST /v1/tickets`, tool `report_issue`). A human: support@optalgo.com.

## Safety rules (always)

1. **Never ask for, print or store the key anywhere but its file.** Connect with the device login (section 0). If the user pastes a key (`oa_live_…`), do not use it: tell them to revoke it under **AI agents** and run the login.
2. **Paper first.** Every new bot is created on paper. Every demo and every new strategy runs on paper.
3. **Live is the user's decision, made in the app.** Suggest it; never start it on your own. The user switches a bot to live in **My Bots**. Only if the user explicitly asks you to do it, and your key has `trade`, may you switch it (`PATCH /v1/bots/{bot_id}` with `{"is_paper": false}`), asking once more right before under `confirm_live`. A hosted strategy (section 3) goes live only when the user confirms it in the app: you may only request it (section 5).
4. **Never claim live until a GET says live.** Say "live" only after `GET /v1/bots/{bot_id}` answers `"mode": "live"`. Say "filled" only after `GET /v1/signals/{transaction_id}` is `executed` and `GET /v1/trades` shows the trade. A `202` is "accepted", nothing more.
5. **Follow `fix` and `next`.** Every backtest and market refusal tells you what to change (`fix`), what to call next (`next`) and where it is explained (`docs`). Do that before anything else; do not retry the same request unchanged.
6. **Stop on quota.** `daily_quota` or `monthly_quota`: stop submitting, tell the user when it resets.
7. **Respect limits and scopes.** A `403` (`plan_required`, `scope_required`, `limit_exceeded`, `key_paused`) is the user's or the plan's decision. Never work around it with another bot, key or exchange.
8. **Grade before numbers.** Report a backtest's honesty grade and findings before any return figure, together with its search verdict (`search.verdict`, section 2.5), and call a single backtest in-sample. Judge it **net of fees**: fees kill short timeframes (section 2.5). Don't sweep parameters with many single runs (section 2.4).
9. **Never send code that tries forbidden actions.** Strategy code may only use `numpy`, `math` and `optalgo_engine.sdk`. Code that tries files, network, processes, system modules or sandbox escapes is refused with [`security_violation`](https://docs.optalgo.com/llm/errors.md#security_violation) and counts as a strike (the answer says strike N of `strikes_max`, 3 by default; checking, validating and submitting the same code counts once); repeated security violations suspend the account's API access ([`account_suspended`](https://docs.optalgo.com/llm/errors.md#account_suspended)) until support@optalgo.com restores it. Honest mistakes (a loop over bars, a wrong signature, lookahead, a syntax error) never count, and neither does a stop OptAlgo's own sandbox caused (kind `engine`, e.g. [`engine_import`](https://docs.optalgo.com/llm/errors.md#engine_import): not charged either). On a strike, tell the user, remove the forbidden part, and do not try another way around it.
10. **Never fetch prices or market data from the web.** Use `GET /v1/prices` and `GET /v1/markets`. A signal needs no price: leave `entry_price` out and OptAlgo fills it from its live price. Don't ask the user for values OptAlgo can default; ask only for intent (symbol, direction, size) when it is missing.
11. **Report problems automatically.** File a ticket (`POST /v1/tickets`; connector tool `report_issue`) **without asking the user**, not only on errors: when OptAlgo gets something wrong (validate and a run disagree, an estimate far off, a `5xx` or `internal_error` that repeats), when the user wants something OptAlgo cannot do (kind `feature`), when the docs and a tool or answer disagree, when a result looks wrong, and when the user is confused by a response (kind `question`). A `next` step `report_issue` already carries the ticket: send it. One ticket per distinct problem per session; tell the user in one line with the ticket id. Never say you cannot contact OptAlgo; a person is at support@optalgo.com. Details: [Report problems automatically](https://docs.optalgo.com/llm/tickets.md#report-problems-automatically).

## Sections

Fetch the one you need; each is plain Markdown and stands alone.

- [connect](https://docs.optalgo.com/llm/connect.md) (18 KB): connect an agent to the account (device login, the credentials file, claim code, key scopes), then a 2-minute paper demo in My Bots.
- [sdk](https://docs.optalgo.com/llm/sdk.md) (27 KB): what strategy.py may use (the SDK in one screen), several symbols in one strategy (references, legs, funding and open interest, with examples), what the lookahead check covers, discovering markets before spending quota, and the free validate dry run.
- [backtests](https://docs.optalgo.com/llm/backtests.md) (21 KB): the backtest loop and run spec, basket backtests on several symbols, reading a result (honesty grade first, search verdict, metrics net of fees), plans and quota, ready-made curl and Python helpers.
- [research](https://docs.optalgo.com/llm/research.md) (6 KB): why sweeping parameters with single runs overfits, holdout windows, and research runs (walk-forward and other out-of-sample protocols).
- [hosted](https://docs.optalgo.com/llm/hosted.md) (22 KB): run a backtested strategy on OptAlgo on paper (dry run first, the gate, slots; several legs on one account, funding / open interest and references on any timeframe run as in the backtest), watch its decisions, compare it with its backtest, ask the user to go live.
- [errors](https://docs.optalgo.com/llm/errors.md) (29 KB): the error shape (`fix`, `next`), and every error code with what to do: access, quota, request and code, strategy inputs and legs, validate's dry run, per-run limits, failed runs and sandbox stop kinds, hosted strategies.
- [tickets](https://docs.optalgo.com/llm/tickets.md) (5 KB): file a ticket without asking the user (errors, missing capabilities, docs that disagree, wrong-looking results, confusing answers), dedupe, the daily limit.
- [reference](https://docs.optalgo.com/llm/reference.md) (34 KB): the endpoint reference (authentication, scopes, account, markets, bots, signals, trades, positions, rejections, autonomy), recipes, and optional TradingView alerts.
- [everything](https://docs.optalgo.com/optalgo-llm.md) (163 KB): the whole guide in one file.

## Human help

A person at OptAlgo: support@optalgo.com. For anything OptAlgo gets wrong or cannot do yet, file a ticket yourself (https://docs.optalgo.com/llm/tickets.md); never tell the user you cannot contact OptAlgo.