Guides · Safety

Safety model

Execution is gated by scopes and a server-side risk policy. Quotes and prepared swaps never move funds. Orders that breach policy never reach a venue.

Risk gates

—Fail-closed — execution is off until policy.executionEnabled is true and the matching scope is granted.
—Pre-trade checks — size, leverage, venue, market, and slippage caps are checked before an order is sent. A breach returns 4xx; nothing is placed.
—Daily notional cap — reserved atomically per key, per UTC day; reverted if execution fails.
—Least privilege — grant only the scopes an agent needs; keep maxOrderUsd / dailyNotionalUsd tight.

Idempotency

Send an Idempotency-Key header on every execution request. Retries with the same key are de-duplicated, so a network blip never double-submits. This is essential for autonomous loops.

Custody

—Non-custodial — swap_prepare returns an unsigned transaction you sign with your own wallet. Venym never holds your keys.
—Delegated — perp execution and headless swaps run against credentials the owner has explicitly stored, bounded by the key's policy. A key can only ever trade the owner's own wallet.

Treat agent keys like production secrets. Scope them narrowly, set an expiresAt, optionally pin an ipAllow list, and rotate regularly. Run with VENYM_READONLY=1 wherever execution isn't needed.

Error & status catalog

HTTPCodeMeaning

401UNAUTHORIZEDMissing, invalid, or revoked agent key.

403INSUFFICIENT_SCOPEKey lacks the scope the endpoint requires.

403EXECUTION_DISABLEDpolicy.executionEnabled is not true.

403ORDER_TOO_LARGEOrder notional exceeds maxOrderUsd.

403LEVERAGE_TOO_HIGHLeverage exceeds maxLeverage.

403VENUE_NOT_ALLOWEDVenue not in venuesAllow.

403MARKET_NOT_ALLOWED / MARKET_DENIEDSymbol blocked by the allow/deny lists.

403SWAP_TOO_LARGE / CHAIN_NOT_ALLOWEDSwap value or chain blocked by policy.

429DAILY_CAPRolling 24h notional cap reached.

429RATE_LIMITEDPer-key request rate limit hit (see Retry-After).

400VALIDATION_ERRORMalformed request body.

Rate limits

Per-key limits apply on top of a global IP limit: roughly 600/min for reads, 60/min for execution, 30/min for swaps (overridable per key via policy.rateLimits). On 429, back off using the Retry-After header — the SDKs do this for you.

Questions? Back to overview · Authentication.