Guides · Safety

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/sdk does 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 intent instead, with the same clientId.

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 orders stream, or GET /orders?status=all in 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 mode in every result. Treat an unexpected live as a stop condition.
  • Preview before placing; do not place when placeable is false.
  • Money is a decimal string. No float arithmetic on it.
  • Keep keys out of prompts, logs and repositories. Rotate one that leaked.
Careful
Live trading is not switched on yet; everything here runs on test keys. See Limits.