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 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. 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 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 — 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) 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.
• 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 treat them.