Integrate an AI Agent

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 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
Creates + funds the venue account, signs the one-time onboard ceremony locally	Discovers markets, researches, backtests, deploys, monitors
Decides how much capital to expose	Operates strictly inside that account's 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):

POST /account/register with the operator's email → operator reads the six-digit code aloud → POST /account/verify → the agent holds st_live_…. No dashboard needed.
Operator funds their venue account and runs the two-call signing ceremony locally → then hands the agent the scoped trading key the same way they handed over the OTP (paste it into the conversation, an env var, or a secret store the agent reads — the handoff is a deliberate human act, and it is the agent-wallet key, never the master key). The agent can confirm funding via the deployment's venue_account readiness probe rather than asking.

Research (repeatable):

GET /context/venues → pick the venue matching the operator's setup.
GET /context/markets?status=backtest_ready → the tradable, validatable universe.
GET /context/candles, GET /context/funding, GET /context/scan → form a thesis with actual data. The evidence fields exist so the agent weighs numbers, not vibes.

Validate (gate):

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 — an entry condition that never fires is a finding, not a formality.
Deploy "mode": "paper" where the venue supports it (freqtrade venues at launch) 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):

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

Stand down (always reachable):

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 /md/<path> (this page: /md/guides/agent-integration).
The index: /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. The key you hold is your operator's money-adjacent trust; treat it like the toxic material rules treat it.