Safety
The server enforces all of this on every request. A model cannot talk its way past it.
Policy and scopes
Every order passes the key's policy (see Authentication). Give a read-only agent market:read and account:read only. A refused request is policy_denied, forbidden or unauthorized: stop, do not look for a way around it.
Kill switch
POST /api/v2/agent/pause with {"paused":true} pauses every key the user owns; {"paused":false} resumes. It needs a signed-in user, not an agent key. One key: PATCH /api/v2/agent/keys/:id {"paused":true}. GET /api/v2/agent/activity lists what each key did.
clientId: no double orders
Every order, position close and Solana trade carries a client-generated UUID clientId. The same clientId again returns the original result and never places a second order.
- Generate it before the first attempt and reuse it on every retry. The client in
packages/sdkdoes this (see TypeScript client). - Retry only network errors, timeouts, 429 and 5xx. Never retry
policy_denied,bad_request,forbidden,live_off. - A preview id lives about 15 seconds. A retry may send the
intentinstead, with the sameclientId.
Order state "unknown"
unknown means the call to the venue timed out: the order may be live, filled or never have arrived. The server looks the client order id up at the venue and never re-sends. An agent that sees it must:
- not place the order again, and not place an offsetting one;
- keep watching: the
ordersstream, orGET /orders?status=allin a loop; - if it is still unknown after the wait, check positions (
GET /account) and stop trading that market.
Solana fills stay submitted until the transaction lands (confirmed), fails or expires. A timer never marks one failed.
Errors
{ "ok": false, "error": { "code", "message", "details?" } }. Codes: bad_request, unauthorized, forbidden, not_found, conflict, rate_limited, venue_not_connected, venue_rejected, venue_unavailable, venue_timeout, insufficient_margin, stale_market_data, preview_expired, policy_denied, signing_unavailable, not_supported, live_off, unavailable, internal. live_off (403) means live trading is not switched on: paper trading still works, and a retry will not help.
Rules for agents
- Start on a test key and check
modein every result. Treat an unexpectedliveas a stop condition. - Preview before placing; do not place when
placeableis false. - Money is a decimal string. No float arithmetic on it.
- Keep keys out of prompts, logs and repositories. Rotate one that leaked.