API keys

An OptAlgo API key lets an AI agent (Claude Code, Codex and others) or your own script work with your account through the OptAlgo REST API at https://api.optalgo.com/v1. Every plan can connect an agent, Free included. With a key, your agent can:

• develop strategies with you: write a strategy in Python, check it for free, backtest it on OptAlgo's engine on real candles and read the honesty grade before any number, then improve it run by run; every run appears on your Backtest page;
• trade on paper in My Bots: create bots, open and close positions, and show you the results in the app, with no exchange connection and no money;
• trade live on your exchange account (Plus and Pro, with the Live trading permission), when you decide to;
• read your trades (JSON or CSV), per-bot statistics, equity curves, what your exchange holds right now, balances, a one-call summary and your bots' logs, including the exchange's error message when an order fails;
• connect your Binance account through Binance's own consent screen, without typing an API key anywhere;
• send bug reports, feature requests and questions to the OptAlgo team, and read our replies.

Exchanges other than Binance, your exchange API keys, payments and OptAlgo strategies stay in the app.

Connect an agent without ever handling the key

You never need to copy an API key into a chat. Give your agent one file and let it connect itself; the key goes from OptAlgo straight into a file on your computer.

Using a chat app instead of a coding agent (Claude.ai, ChatGPT, Claude desktop or mobile)? Use the OptAlgo connector instead of a key: add one URL in the chat app and approve it once in OptAlgo. It runs backtests and paper bots, never live trading. Never paste your key into a chat.

1. Tell your agent (Claude Code, Codex or another coding agent):

   Read https://docs.optalgo.com/optalgo-llm.md and connect to my OptAlgo account.
   Then show me the paper demo in My Bots, and help me backtest this idea: <your idea>.

   After connecting, the agent opens a few small paper positions in My Bots (open app.optalgo.com/my-bots to watch them), closes them, and then turns your idea into a strategy and backtests it with you.

   You can also download optalgo-llm.md in the app under AI agents and hand the file over.

2. The agent shows you a link and a short code such as WDJB-MJHT. Open the link (log in to OptAlgo if asked) and check that the page shows the same code.

3. On that page, choose the key's name, its scopes, its autonomy and its limits (the same choices as when you create a key by hand, see below), and click Approve. Click Deny if you did not start this.

4. The agent saves the key in ~/.config/optalgo/credentials.env on your computer, readable only by you, and confirms the connection. It never prints the key, and you get a Telegram notice naming the new key and the agent.

The link and the code expire after 10 minutes. If you approved the wrong request, revoke the key under AI agents; it stops working at once.

On a server or a container where you cannot open a link from the agent's machine, create a claim code under AI agents instead: choose the same name, scopes, autonomy and limits, and give the agent the code (it starts with OPTC-). A claim code works once and expires after 10 minutes, so it is harmless once used, unlike a key.

If you pasted a key into a chat anyway, consider it exposed: revoke it under AI agents and connect with the login above.

The exact commands the agent runs (a shell script and a Python version you can reuse in your own programs) are in section 0 of the agent reference.

Why build on OptAlgo

An agent can place an order with a few lines of code. Running a bot on a real account for months means handling webhooks that arrive twice, responses lost after the exchange accepted the order, stop orders that are refused, Binance keeping stop orders on a separate endpoint, hedge mode, precision rules per market, and the question "what happened to that signal". OptAlgo is that part of the system, so your agent only has to decide what to trade:

• Execution you do not have to write: exchange wrappers for Binance futures and spot, Bybit, OKX and Alpaca; a durable signal queue acknowledged only after execution; a client order id on every order and a lookup before any resend; retries for temporary errors only; no position without its stop-loss.
• Autonomy you control: per key, the agent either asks before live trades or trades on its own inside server-enforced limits (maximum allocation and leverage, allowed exchanges, a daily loss stop) that only you can change.
• Security: API keys are stored as hashes with scopes and can be revoked at once; exchange keys are encrypted at rest and never returned by any endpoint; Binance keys are created by Binance itself, restricted to OptAlgo's IP; every API call is logged with the key that made it; you get a Telegram notice on every money-moving API write.
• Many bots, one account: several bots share one exchange account safely, hedge mode is handled, and a multi-symbol bot runs one budget across many coins like a small fund.
• Speed, without stale numbers: a paper trade fills in 13–55 ms with no call to the exchange; a live Binance futures entry took 1.8–3.1 s in production, most of it Binance's own round trips. Balance, position size, the stop orders and leverage are always read live from the exchange.
• Reads for your own tools: trades, PnL, equity curves, positions and balances are one call each, so your agent can draw the dashboards you want.

The full, verified list is in Reliability and safety and in the agent reference.

Who can create keys

Every plan. You can have up to 5 active keys.

• Free: keys with Read, Backtests and Bots: backtests and paper trading only. The Live trading permission needs Plus or Pro.
• Plus and Pro: every permission, including Live trading.

If you move to a smaller plan, your keys keep working for what the new plan allows (paper and backtests on Free); live trading through them answers plan_required until you upgrade again.

Plans

	Free	Plus	Pro
API keys and AI agents	Yes: paper and backtests	Yes, live trading too	Yes, live trading too
Backtest units (1 unit = up to 10 s of run time)	50 per month	30 per day	200 per day
Quota resets	At quota.resets_at	00:00 UTC	00:00 UTC
Symbols per run	3	3	10
History per run (1-minute candles across all symbols)	300,000	550,000 (about 1 year for one symbol)	3,200,000 (about 6 years for one symbol)
Trials per optimisation	40	100	500
Runs at once	1	1	3
Time per run	60 s	90 s	300 s
Memory per run	1.5 GB	2 GB	4 GB
Paper trading in My Bots	Yes, with a monthly paper trade limit	Yes	Yes
Multi-symbol bots	No	Up to 10 open coins	Up to 20 open coins
Strategies hosted on OptAlgo	1, paper	10	20

Units are run time: a run costs max(1, ceil(run_seconds / 10)) units, so up to 10 seconds is 1 unit and a 1-minute run is 6. An optimisation is charged the same way on its total run time. When a run is submitted, OptAlgo estimates its cost and reserves it from your quota (the submit is refused if the estimate is more than you have left); when it ends, the reservation is settled to the measured run time. Every run is also stopped at its plan's time per run. A run stopped by its time or memory cap or by the sandbox is charged; a run that fails on our side costs nothing; a result that already existed costs 1 unit. Checking a strategy and a run before submitting it (POST /v1/backtests/validate) is free, reports every problem at once and shows the estimate. A refused request costs nothing.

Cheaper runs: fewer symbols, a shorter window, a coarser timeframe, the SDK's indicators and primitives instead of Python loops, and fewer optimisation trials.

Busy times: runs wait in a fair queue (Pro, then Plus, then Free, and in turn per user) instead of being refused; besides the runs you may have going at once, up to 3 more can wait. A queued run reports its position and an estimated wait (eta_s); your agent tells you, and the Backtest page shows both.

Which markets: exactly what GET /v1/markets lists when you call it (symbols with backtest: true, the timeframes in data.timeframes, and where each symbol's history starts). The list grows over time: read it, never hard-code it.

Trials of an optimisation are counted as the engine counts them: the largest of n_trials, permutations × permutation_trials, and wf_permutations. Fields you leave out take the engine's defaults (n_trials 50, permutations 100, permutation_trials 20, wf_permutations 50), so a spec that sets only n_trials still counts 2,000 trials and is refused by the trials limit. Set permutations and permutation_trials to small values yourself.

Check your quota with GET /v1/backtests/limits:

{"plan": "Free", "enabled": true, "active_jobs": 0,
 "limits": {"cpu_s": 60, "wall_s": 60, "mem_mb": 1536, "max_symbols": 3, "max_bars": 300000,
            "max_trials": 40, "max_concurrent": 1, "user_code": true},
 "quota": {"period": "month", "units": 50, "used": 12, "remaining": 38, "resets_at": "…", "seconds_per_unit": 10},
 "next": [{"action": "list_markets", "method": "GET", "path": "/v1/markets", "why": "…"}]}

period is month on Free and day on Plus and Pro; when a monthly quota resets, read resets_at. Every backtest row (in the app and in GET /v1/backtests) shows units_estimated, units_charged and run_seconds.

Over the quota, POST /v1/backtests answers 429 with daily_quota (Plus, Pro) or monthly_quota (Free), the units used and remaining, this run's estimated cost, resets_at, and a fix. An agent that gets it must stop submitting: no retries, no loop. It tells you when the quota resets and suggests a smaller run or a bigger plan.

This is not the other 429, engine_refused with "limit": "max_concurrent": your runs at once are all busy, and the agent waits for one to finish. A run over a per-run limit (symbols, history, trials, time, memory) is refused with 413, 422 or 429 engine_refused, naming the limit, the value asked for, the allowed maximum and a fix.

Scopes

Scope	What it allows
read (always on)	Account, exchanges and symbols, connections, bots, trades, statistics, equity, positions, balance, summary, logs, signal outcomes, tickets
backtest	Backtests only: your agent sends strategy code it writes to OptAlgo's backtest engine and reads the results (honesty grade, findings, metrics). No bots, no trading. Keys with bots or trade can run backtests too
bots	Create, edit, start, stop, convert and delete your bots; set ticker weights, pause or remove tickers; start a Binance connection; trade your paper bots (signals and closes). Stopping a bot closes its open positions, live ones included
trade (Plus, Pro)	Live trading with real money: signals and closes on live bots, switching a bot from paper to live, raising a live bot's allocation, creating a live bot. Only keys with this scope can read a bot's strategy key (the TradingView webhook key): anyone holding that key can trade the bot, live included, so it is never shown to other keys

A key approved without trade can never put your money at risk: it cannot switch a bot to live, and if you switch a bot to live in the app, that key's signals on it are refused. To try OptAlgo with an agent, read + backtest + bots (the default) is enough: backtests and paper bots need no exchange connection.

To let an agent write and test strategies without touching your bots, give it a key with only Backtests (read + backtest). Its runs appear on the Backtest page of the app. The agent's step-by-step loop is in the LLM reference (section 2, Develop a strategy).

You can turn Backtests, Bots and Live trading on or off for an existing key at any time under AI agents; it applies on the key's next call, and you get a Telegram notice. When an agent hits a missing scope, the error carries a link that opens that key with the switch ready to confirm.

Create a key by hand (developers)

For your own code you can use the same login (see the API reference), or create a key by hand:

1. Open AI agents in the app sidebar (app.optalgo.com/ai-agents).

2. Click Create API key, give it a name (for example "Backtest server") and choose its scopes, autonomy and limits.

3. Copy the key. It is shown only once. Store it like a password, either in the environment of the program that uses it (OPTALGO_API_KEY) or in ~/.config/optalgo/credentials.env with chmod 600:

   OPTALGO_API_KEY=oa_live_...
   OPTALGO_API_BASE=https://api.optalgo.com/v1

Base URL, errors, rate limits, idempotency, pagination, the OpenAPI schema and ready-made clients in Python and JavaScript are in the API reference.

Revoke a key at any time under AI agents; it stops working immediately.

Autonomy: ask first, or trade on its own

Each key also has an autonomy level, set when you create the key or later in the app under AI agents:

• Confirm live trades (confirm_live, the default): the agent asks you before every live entry, before switching a bot to live, before raising an allocation, and before stopping or deleting a bot with an open trade.
• Full autonomy (full): the agent trades without asking, inside limits that OptAlgo's servers enforce for this key. A maximum allocation per bot and a maximum leverage are required.

Limits you can set on any key (each one optional except the two that full requires; empty means "any"):

Limit	What it stops
max_allocation_per_bot	A live bot created, switched to live or given a higher allocation above this amount (a multi-symbol bot's whole budget counts). Lowering an allocation always works
max_leverage	Entry signals to live bots with a higher leverage
allowed_exchanges	Live bots and live entries on other exchanges
allowed_account_types	Live bots and live entries on other account types (Spot, Futures)
daily_loss_limit	When today's realized loss on your live bots reaches it, the key is paused

The limits apply to live bots; paper bots are never limited. A request that would break a limit is refused before anything reaches your exchange (403 limit_exceeded) and you are told on Telegram. If the server cannot read today's PnL to check the daily loss limit, the live entry is refused, never let through.

A paused key can no longer open live positions, create live bots, switch bots to live, raise allocations or start live bots. It can still close positions, move stops, stop bots, lower allocations, run paper bots and read. Deleting a losing bot does not reset today's loss. Only you can resume the key, in the app; the loss count then starts again from that moment.

Autonomy and limits can only be changed by you, logged in to the app. An API key cannot change its own autonomy, raise its own limits or lift its own pause. You can lower the limits, switch back to confirm, or revoke the key at any time.

Build your own terminal

With a read key your agent (or a 40-line script) can render a live table of your bots, PnL and exchange positions, save your trade history as CSV, or draw the combined equity curve of your bots. The reference has the endpoints, a polling budget and two ready examples: Dashboards and scripts. One rule: a web page must never embed the key; use a small server-side proxy or a local script.

Limits and logging

• 120 requests per minute per key, 30 per minute for signals and closes. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; over the limit the API answers 429 with Retry-After.
• Writes accept an Idempotency-Key header: a retried call with the same key returns the first answer instead of acting twice.
• Details for developers (headers, error codes, paging, versioning): API reference.
• Tickets: 20 per user per UTC day (a repeat of a problem already filed counts once), each submission a batch of up to 10 items.
• Every API call is logged with the key that made it (route, result, the bot and signal it touched; secrets are never stored), and every change to a bot appears in that bot's log as … via API key "<name>". You see what your agent did; we can investigate problems with you.
• Money-moving writes (a changed allocation, mode or max positions, a live bot created, a bot stopped, deleted or converted, a ticker's weight, pause or removal, a Binance connection made) are announced to you on Telegram, naming the key. Turn Telegram notifications on in the app to receive them.

Forbidden code: strikes

Strategy code your agent sends may only use numpy, math and OptAlgo's strategy SDK. Code that tries a forbidden action (reading or writing files, the network, starting processes, system modules, escaping the sandbox) is refused with security_violation and counts as a strike on your account, wherever it arrives: a check, a validation, a backtest or code pasted in the app. The answer says which strike it is ("strike 2 of 3"), with the line and the rule, never the code.

After repeated security violations (3 strikes by default; one strike per code version, so re-checking the same code does not add one) your account's API access is suspended (account_suspended): every API key, agent login, claim code, connected chat and code backtest stops until you contact [email protected] and we restore it. The AI agents and Backtest pages show the suspension.

Honest mistakes never count: a loop over bars, a wrong function signature, lookahead or a syntax error is an ordinary finding with a fix. The same rule applies on every plan.

Keep keys safe

• Never paste a key into a chat, an issue, a TradingView alert, a web page or a public repository. Agents connect through the login above and never need to see it, and chat apps use the connector; if a key was pasted somewhere, revoke it.
• Give an agent only the scopes it needs; leave trade off unless it should trade with real money, and remember that bots can still stop bots (closing positions), lower allocations and connect Binance.
• An agent without the trade scope cannot read your bots' strategy keys. If you already use TradingView alerts and ask the agent to set them up, copy the key from the bot's page in the app and paste it into the alert yourself.
• Tickets filed through the API cannot be replied to or edited through the API; new information goes into a new submission. Anything that looks like an API key in a ticket is cut to its prefix before it is stored.
• Revoke a key you no longer use, or one you think was exposed.