Start · Authentication

Authentication & agent keys

Public reads need no key. Anything that moves funds requires a scoped agent key whose risk policy is enforced server-side, before any order reaches a venue.

Agent API keys

Keys look like venym_sk_live_… (or venym_sk_test_…). Send a key on every request as either header:

http

Authorization: Bearer venym_sk_live_...
# or
x-venym-key: venym_sk_live_...

Keys are stored only as a salted hash — the raw secret is shown once, at mint or rotate. Never ship a key in client-side code. Rotate with POST /api/agent/keys/{id}/rotate.

Scopes

A key carries a set of scopes. Each tool / endpoint declares the scope it needs.

market:readPublic market data. No key required — a key only raises your rate limits.

account:readPositions, balances, and open orders for the key's subject wallet.

orders:executePlace / cancel perp orders and open / close positions.

pairs:executeOpen and close long/short pair trades.

swap:quoteQuote swaps and build unsigned (non-custodial) swap transactions.

swap:executeExecute cross-chain swaps headlessly via a delegated wallet.

Risk policy

Every key carries a risk policy. Requests that breach it are rejected with a 403 / 429 before reaching a venue. Omitted caps fall back to conservative defaults (e.g. $100/order, $500/day).

executionEnabledMaster switch. Defaults to false — no execution until you set it true.

maxOrderUsdPer-order notional ceiling (USD).

dailyNotionalUsdRolling 24h (UTC-day) notional cap across all execution.

maxLeverageMaximum leverage for perp orders.

venuesAllowAllowlist of venues, e.g. ["hyperliquid","lighter"].

marketsAllow / marketsDenySymbol allow / deny lists, e.g. ["BTC","ETH"].

swapMaxUsdPer-swap value ceiling (USD).

swapChainsAllowAllowlist of chain IDs for swaps.

maxSlippageBpsHard slippage cap (basis points). Clamps any requested slippage.

ipAllowOptional IP allowlist for the key.

json

{
  "label": "momentum-bot",
  "scopes": ["market:read", "account:read", "orders:execute", "pairs:execute"],
  "policy": {
    "executionEnabled": true,
    "maxOrderUsd": 500,
    "dailyNotionalUsd": 2500,
    "maxLeverage": 5,
    "venuesAllow": ["hyperliquid", "lighter"],
    "marketsAllow": ["BTC", "ETH", "SOL"],
    "maxSlippageBps": 50
  }
}

Managing keys

Key management is authenticated with your Venym (Dynamic) session JWT — a human owner mints keys for their agents. A key always trades the owner's own wallet.

POST/api/agent/keysowner JWT

Mint a key. Returns the raw secret once.

GET/api/agent/keysowner JWT

List your keys (redacted).

PATCH/api/agent/keys/{id}owner JWT

Update label, scopes, or policy.

POST/api/agent/keys/{id}/rotateowner JWT

Revoke and re-mint (new secret).

DELETE/api/agent/keys/{id}owner JWT

Revoke a key.

GET/api/agent/keys/{id}/usageowner JWT

Daily notional + order counts.

Auth errors

—401 UNAUTHORIZED — missing, invalid, or revoked key.
—403 INSUFFICIENT_SCOPE — the key lacks the required scope.
—403 EXECUTION_DISABLED — policy.executionEnabled is not true.
—403 ORDER_TOO_LARGE / LEVERAGE_TOO_HIGH / VENUE_NOT_ALLOWED — a policy cap was breached.
—429 RATE_LIMITED / DAILY_CAP — per-key rate limit or daily notional cap hit.

See the safety model for the full error catalog.