Concepts: policy, plans, paper and live
How the policy, plans, metering and the two modes fit together.
The policy
A policy is attached to the key and enforced on every call. Values are clamped, not trusted: maxNotionalUsd 1–10 000, dailyCapUsd 1–100 000, unknown operations are refused, coins are upper-cased and capped at 50.
| Field | What it controls |
|---|---|
| allowedOps | which operations the key may perform |
| maxNotionalUsd | the largest single call |
| dailyCapUsd | the most metered notional per UTC day |
| allowedCoins | the markets the key may touch |
Two envelopes on a trade
The key policy is the first envelope: a per-call or daily violation is 403 and the agent is never touched. The platform risk envelope is the second: max positions, position size, leverage, stop-loss/take-profit and daily breakers. A size above the platform cap is clamped; a breaker refusal is 409.
Plans and their ceilings
The account's plan sets the maximum the key policy may ask for. The effective limit is the tighter of the two. Paid plans replace the 8 bps per-order fee.
| Plan | Keys | Per call | Per day | Fee |
|---|---|---|---|---|
| Sandbox | 1 | $50 | $200 | 8 bps |
| Builder | 3 | $500 | $5,000 | — |
| Growth | 10 | $2,500 | $50,000 | — |
| Scale | 100 | $10,000 | $100,000 | — |
Paper and live
Paper mode uses real market data and simulated fills; the ledger persists across cold starts. Live mode places real orders through the approved agent wallet. The same endpoints and the same policy apply to both — only the venue changes.
Metering
Executed orders are recorded as agent_op events (notional, fee, mode). spentTodayUsd is summed from those events, and remainingTodayUsd is dailyCapUsd − spentTodayUsd − this order. Quotes and invoices are not metered because no money moves.
Errors tell you whose decision it was
| Status | Meaning | What to do |
|---|---|---|
| 400 | Malformed body, bad address, non-positive amount | Fix the request |
| 401 | Missing or invalid key | Re-issue the key |
| 403 | The key's policy refuses (op, cap, allowlist) | Surface it; do not retry unchanged |
| 409 | The platform guard refuses (positions, breakers, funds, market, no route) | Surface it; back off |
| 429 | Rate limit (100 requests/minute per IP) | Honour Retry-After |
Keys and revocation
Each key has permissions (read, write) and a policy. Delete a key and its secret stops working immediately; pause the agent in the cockpit to stop new entries while exits keep running. On Hyperliquid you can revoke the agent wallet itself.