---
title: Integrate an AI Agent
description: The full human-operated agent flow, request by request.
---

This is the reference integration for the primary Superior user: an AI agent operated by a human. It expands the [Quick Start](/quickstart/introduction) into the complete decision loop, including the parts where the human belongs in it.

## Division of labor

| The human does | The agent does |
|---|---|
| Provides their email, relays one OTP | Everything else over HTTP |
| Funds the managed wallet | Discovers markets, researches, backtests, deploys, monitors |
| Decides how much capital to expose | Operates strictly inside the managed wallet balance |

The design keeps irreversible acts — spending money, signing with a master key — on the human side, and everything repeatable on the agent side.

## The loop

**Onboard (once):**

1. `POST /account/register` with the operator's email → operator reads the six-digit code aloud → `POST /account/verify` → the agent stores `api_key: st_live_…`. No dashboard needed.
2. Operator funds the [managed wallet](/wallet/overview). BYOK handoff with a scoped trading key is coming soon. The agent can confirm funding via the deployment's `venue_account` readiness probe rather than asking.

**Research (repeatable):**

3. `GET /context/venues` → pick the venue matching the operator's setup.
4. `GET /context/markets?query=BTC%20perpetual&limit=100` → search the tradable universe, then select results with `backtest_ready: true` for validation.
5. `GET /context/candles`, `GET /context/funding`, `GET /context/scan` → form a thesis with actual data. The [`evidence` fields](/context/intelligence) exist so the agent weighs numbers, not vibes.

**Validate (gate):**

6. `POST /runtime/backtests` → poll → judge against `market_change_pct`, drawdown, trade count. A strategy that can't beat the market it trades in doesn't proceed. Zero-trade results: read [the logs](/runtime/backtests#get-runtime-backtests-id-logs) — an entry condition that never fires is a finding, not a formality.
7. Deploy `"mode": "paper"` where the venue supports it ([freqtrade venues at launch](/runtime/paper-trading)) and let a few days of live data test the strategy; where paper isn't available yet, substitute a short, small, `alive_until`-bounded live run. Compare metrics to the backtest either way.

**Execute (bounded):**

8. Deploy `"mode": "live"` with managed credentials and `alive_until` set. Start. Report the deployment ID to the operator.
9. Poll `GET /runtime/deployments/:id` + `/metrics` on a sane cadence (minutes). Log summaries where the operator can read them.

**Stand down (always reachable):**

10. `PUT /runtime/deployments/:id/status` with `{ "action": "stop" }` on operator request, on `alive_until`, or on the agent's own risk rule. `DELETE` (after positions close) destroys the key material.

## Reading these docs programmatically

The docs themselves are part of the API surface for agents:

- Every page: raw markdown at `/<path>.md` (this page: `/guides/agent-integration.md`).
- The index: [`/llms.txt`](/llms.txt).
- Error responses link to the relevant page in a `docs_url` field — an agent that hits `credentials_missing` receives the URL that explains the fix.

## Failure etiquette for agents

- `429` → honor `retry-after`, exactly.
- `400` with `details` → the payload is wrong; fix it, don't retry it.
- `5xx` → back off exponentially; deployments keep running through API blips — the control plane and the runtime are separate on purpose.
- Never park credentials in prompts or logs. BYOK is coming soon; when it is enabled, treat scoped venue keys like the [toxic material rules](/runtime/credentials#the-toxic-material-rules-byok) treat them.