REST API

API reference

Base URL https://defi.venym.io/api. Responses use a { success, data, timestamp } envelope (a few data endpoints return a raw array). Execution endpoints accept an Idempotency-Key header.

Market data

Public — no key required.

GET/token-pairspublic
All tradable markets and per-venue availability.
GET/aggregated/book?symbol=BTCpublic
Aggregated orderbook snapshot across venues.
GET/aggregated/candles?symbol=BTC&interval=1h&limit=200public
OHLCV bars (raw array, TradingView shape). Intervals: 1m·5m·15m·1h·4h·1d.
GET/aggregated/routing?symbol=BTC&side=BUYpublic
Best-venue routing recommendation + alternatives.
GET/orderbook/:symbolpublic
Per-symbol book; /full and /metrics variants available.
GET/trades/:symbol?limit=100public
Recent trade prints; /metrics for windowed flow stats.
GET/charts/:symbol/candles?interval=1hpublic
Per-venue historical candles.
GET/market-data/symbols · /trending · /search · /:symbol/statspublic
Symbol universe, movers, search, and 24h stats.
GET/trading/:exchange/ticker/:symbolpublic
Per-venue ticker.
bash
curl "https://defi.venym.io/api/aggregated/routing?symbol=ETH&side=BUY"

Streaming (SSE)

Content-Type: text/event-stream. Named events book · bar · trade, with : heartbeat comments every 5s. Target the backend directly to avoid proxy buffering, or just use the SDK / MCP watch_* tools.

GET/aggregated/stream?symbol=BTCpublic
Live aggregated orderbook (event: book).
GET/aggregated/stream/candles?symbol=BTC&interval=1mpublic
Live candles (event: bar).
GET/aggregated/stream/trades?symbol=BTCpublic
Live trade prints (event: trade).
bash
curl -N "https://venym-defi-backend.fly.dev/api/aggregated/stream/trades?symbol=BTC"

Account

Requires a key with scope account:read. Keyed to the key's subject wallet.

GET/agent/positionsaccount:read
Open positions across venues.
GET/agent/balancesaccount:read
Balances across venues.
GET/agent/ordersaccount:read
Open orders.
GET/agent/pairaccount:read
Open pair positions.

Orders & positions

Requires scope orders:execute and policy.executionEnabled = true.

POST/agent/ordersorders:execute
Smart-routed order. Body: { symbol, side: "BUY"|"SELL", type: "MARKET"|"LIMIT"|"STOP_MARKET"|"STOP_LIMIT", quantity, price?, triggerPrice?, reduceOnly?, preferredExchange? }
POST/agent/positions/openorders:execute
Body: { symbol, direction: "LONG"|"SHORT", size, leverage?, orderType, limitPrice?, preferredExchange? }
POST/agent/positions/closeorders:execute
Body: { symbol, direction, size, orderType?, limitPrice? }
DELETE/agent/orders/:venue/:orderIdorders:execute
Cancel an open order on a venue.
bash
curl -X POST https://defi.venym.io/api/agent/orders \
  -H "Authorization: Bearer $VENYM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "symbol": "BTC", "side": "BUY", "type": "MARKET", "quantity": "0.01" }'

Pair trades

Requires scope pairs:execute. A single position split into balanced long/short perp legs.

POST/agent/pair/openpairs:execute
Body: { longSymbol, shortSymbol, notionalUsd, leverage, slippage?, venue? } — or the engine-native { pearMarketId, usdValue, longAssets, shortAssets }.
POST/agent/pair/:id/closepairs:execute
Close a pair position (unwinds both legs).

Swaps

Cross-chain via LiFi/SideShift (EVM + Solana). quote and prepare need swap:quote; headless execute needs swap:execute. (EVM headless execution is live; Solana headless is operator-gated — use the non-custodial prepare path. See recipes.)

POST/agent/swap/quoteswap:quote
Body: { fromChain, toChain, fromToken, toToken, fromAmount, fromAddress?, toAddress? }. Returns quotes + a quoteId.
POST/agent/swap/prepareswap:quote
Returns an UNSIGNED transaction/route for the quote (sign with your own wallet).
POST/agent/swap/executeswap:execute
Executes headlessly via a delegated wallet. Pass an Idempotency-Key.
GET/agent/swap/:swapIdswap:quote
Poll swap status.

Key management

Authenticated with your Venym (Dynamic) session JWT — see authentication.

POST/agent/keysowner JWT
Mint a key (raw secret returned once).
GET/agent/keys · /agent/keys/:idowner JWT
List / fetch keys (redacted).
PATCH/agent/keys/:idowner JWT
Update label, scopes, policy.
POST/agent/keys/:id/rotateowner JWT
Rotate (revoke + re-mint).
DELETE/agent/keys/:idowner JWT
Revoke.
Errors return { success: false, error, code }. See the safety model for the full error and rate-limit catalog.