# Venym DeFi — the agent layer for DeFi (full reference) > Onchain execution for autonomous AI agents. Cross-chain liquidity across 70+ networks and a > perpetuals DEX with multi-venue routing, exposed as one REST API, an MCP server, and typed SDKs > (TypeScript + Python). Public market data is open; execution uses a scoped venym_sk_ agent key > whose risk policy is enforced server-side before any order reaches a venue. API base: https://defi.venym.io/api Streaming (SSE): https://venym-defi-backend.fly.dev/api (target the backend directly) MCP (remote): https://defi.venym.io/mcp Docs: https://defi.venym.io/docs ## Authentication Public market-data endpoints need no key. Everything that reads private account state or moves funds needs a Venym agent key (venym_sk_live_... / venym_sk_test_...), sent as either header: Authorization: Bearer venym_sk_live_... x-venym-key: venym_sk_live_... Scopes (a key carries a subset): market:read Public market data (a key only raises rate limits). account:read Positions, balances, open orders for the key's subject wallet. orders:execute Place/cancel perp orders, open/close positions. pairs:execute Open/close long/short pair trades. swap:quote Quote swaps + build unsigned (non-custodial) swap transactions. swap:execute Execute cross-chain swaps headlessly via a delegated wallet. Risk policy (per key, enforced before any order is sent; omitted caps use conservative defaults): executionEnabled Master switch — defaults false. No execution until set true. maxOrderUsd Per-order notional ceiling (USD). dailyNotionalUsd Rolling 24h (UTC-day) notional cap. maxLeverage Max leverage for perp orders. venuesAllow Allowlist of venues, e.g. ["hyperliquid","lighter"]. marketsAllow/Deny Symbol allow/deny lists. swapMaxUsd Per-swap value ceiling (USD). swapChainsAllow Allowlist of chain IDs for swaps. maxSlippageBps Hard slippage cap (bps); clamps any requested slippage. ipAllow Optional IP allowlist. Keys are managed by a human owner authenticated with a Venym (Dynamic) session JWT. A key always trades the owner's own wallet. ## Connect an agent harness (MCP) All five harnesses below consume MCP over stdio (npx -y @venym/mcp, reads VENYM_API_KEY) or remote HTTP (https://defi.venym.io/mcp, Authorization: Bearer ...). Without a key only read tools appear. Claude Code — .mcp.json: { "mcpServers": { "venym": { "type": "stdio", "command": "npx", "args": ["-y","@venym/mcp"], "env": { "VENYM_API_KEY": "venym_sk_live_..." } } } } Codex CLI — ~/.codex/config.toml: [mcp_servers.venym] command = "npx" args = ["-y", "@venym/mcp"] [mcp_servers.venym.env] VENYM_API_KEY = "venym_sk_live_..." OpenCode — opencode.json: { "mcp": { "venym": { "type": "local", "command": ["npx","-y","@venym/mcp"], "enabled": true, "environment": { "VENYM_API_KEY": "venym_sk_live_..." } } } } Hermes Agent — ~/.hermes/config.yaml: mcp_servers: venym: command: "npx" args: ["-y", "@venym/mcp"] env: { VENYM_API_KEY: "venym_sk_live_..." } enabled: true OpenClaw — ~/.openclaw/openclaw.json: { "mcp": { "servers": { "venym": { "command": "npx", "args": ["-y","@venym/mcp"], "env": { "VENYM_API_KEY": "venym_sk_live_..." } } } } } ## MCP tools Public (no key): get_markets(search?) List tradable perp markets. get_ticker(symbol,exchange?) Latest price + 24h stats. get_orderbook(symbol,full?) Aggregated bids/asks. get_candles(symbol,interval?,limit?) OHLCV candles. get_trades(symbol,limit?) Recent prints. get_routing(symbol,side?) Best venue for an order. get_market_stats(symbol) 24h volume, funding, OI. watch_trades(symbol,durationMs?,max?) Bounded (<=10s) burst of live trades. watch_orderbook(symbol,durationMs?,max?) Bounded (<=10s) burst of book updates. Account (scope account:read): get_positions() get_balances() get_orders() Execution (scopes orders:execute / pairs:execute): execute_order(symbol,side,type,quantity,price?,reduceOnly?,preferredExchange?) cancel_order(venue,orderId) open_position(symbol,direction,size,leverage?,orderType,limitPrice?) close_position(symbol,direction,size,orderType?,limitPrice?) open_pair_position(longSymbol,shortSymbol,notionalUsd,leverage,slippage?,venue?) close_pair_position(id) Swaps (scopes swap:quote / swap:execute): swap_quote(fromChain,toChain,fromToken,toToken,fromAmount,fromAddress?,toAddress?) swap_prepare(quoteId) -> UNSIGNED tx, sign yourself (non-custodial) swap_execute(quoteId) -> headless via delegated wallet get_swap_status(swapId) Resources: venym://llms.txt, venym://markets, venym://ticker/{symbol} Prompts: analyze_market(symbol), plan_swap(fromToken,toToken,amount) ## REST API Responses use { success, data, timestamp } (a few data endpoints return a raw array). Execution endpoints accept an Idempotency-Key header (strongly recommended for retries). Market data (public): GET /token-pairs GET /aggregated/book?symbol=BTC GET /aggregated/candles?symbol=BTC&interval=1h&limit=200 (raw array) GET /aggregated/routing?symbol=BTC&side=BUY GET /orderbook/:symbol (+ /full, /metrics) GET /trades/:symbol?limit=100 (+ /metrics) GET /charts/:symbol/candles?interval=1h GET /market-data/symbols | /trending | /search | /:symbol/stats GET /trading/:exchange/ticker/:symbol Streaming (SSE; events: book | bar | trade): GET /aggregated/stream?symbol=BTC GET /aggregated/stream/candles?symbol=BTC&interval=1m GET /aggregated/stream/trades?symbol=BTC Account (scope account:read): GET /agent/positions GET /agent/balances GET /agent/orders GET /agent/pair Orders & positions (scope orders:execute): POST /agent/orders { symbol, side, type, quantity, price?, triggerPrice?, reduceOnly?, preferredExchange? } POST /agent/positions/open { symbol, direction, size, leverage?, orderType, limitPrice?, preferredExchange? } POST /agent/positions/close { symbol, direction, size, orderType?, limitPrice? } DELETE /agent/orders/:venue/:orderId Pair trades (scope pairs:execute): POST /agent/pair/open { longSymbol, shortSymbol, notionalUsd, leverage, slippage?, venue? } POST /agent/pair/:id/close Swaps (scopes swap:quote / swap:execute): POST /agent/swap/quote { fromChain, toChain, fromToken, toToken, fromAmount, fromAddress?, toAddress? } POST /agent/swap/prepare { quoteId } -> unsigned tx POST /agent/swap/execute { quoteId } -> headless GET /agent/swap/:swapId Key management (owner JWT): POST /agent/keys { label, scopes, policy } -> raw secret returned once GET /agent/keys | /agent/keys/:id PATCH /agent/keys/:id POST /agent/keys/:id/rotate DELETE /agent/keys/:id GET /agent/keys/:id/usage ## SDK quickstart TypeScript (npm i @venym/sdk): import { VenymClient } from "@venym/sdk"; const venym = new VenymClient({ apiKey: process.env.VENYM_API_KEY }); const book = await venym.markets.getOrderbook("BTC"); const order = await venym.orders.place({ symbol:"BTC", side:"BUY", type:"MARKET", quantity:"0.01" }); for await (const ev of venym.streams.trades("BTC")) { console.log(ev.data); break; } Python (pip install venym): from venym import VenymClient venym = VenymClient(api_key=os.environ["VENYM_API_KEY"]) book = venym.markets.get_orderbook("BTC") order = venym.orders.place(symbol="BTC", side="BUY", type="MARKET", quantity="0.01") ## Errors 401 UNAUTHORIZED · 403 INSUFFICIENT_SCOPE · 403 EXECUTION_DISABLED · 403 ORDER_TOO_LARGE / LEVERAGE_TOO_HIGH / VENUE_NOT_ALLOWED / MARKET_NOT_ALLOWED · 403 SWAP_TOO_LARGE / CHAIN_NOT_ALLOWED · 429 DAILY_CAP · 429 RATE_LIMITED · 400 VALIDATION_ERROR Safety: quotes and prepared swaps never move funds; execution is fail-closed (off until policy.executionEnabled is true and the scope is granted); a key only ever trades the owner's wallet; pass an Idempotency-Key so retries never double-submit.