# Tomahawk: full reference for models Perpetuals on Hyperliquid, Aster, Lighter and Pacifica with one routed order, plus the Solana memecoin board and trading. STAGE: paper trading is open. Live trading is NOT switched on yet. GET /api/v2/config returns { live: false }; live keys cannot be created, there are no wallets, and live actions answer error code live_off (HTTP 403). Use a test key (renko_sk_test_...) for everything below. Base URL: https://usetomahawk.xyz. REST: https://usetomahawk.xyz/api/v2. Realtime: wss://renko-terminal-api.fly.dev/ws (the API host; the socket does not go through the site address). ## Auth Authorization: Bearer . Tokens: a signed-in user's session access token, or an agent key. Agent keys: renko_sk_test_... (simulator only, the server forces mode "paper", no venue connection needed) and renko_sk_live_... (the owner's connected venues, inside the key's policy; not available while live trading is off). Create keys on the Agents page (a signed-in user only; an agent key cannot create keys). The secret is shown once; rotate with POST /api/v2/agent/keys/:id/rotate. Public market data needs no token. Scopes: market:read, account:read, orders:execute, sol:trade, and swap:quote / swap:execute for funding (funding answers live_off while live is off). Policy per key: executionEnabled (default false: read and preview only), maxOrderUsd, dailyUsd (per UTC day), maxLeverage, maxSlippageBps, venuesAllow, marketsAllow, marketsDeny (perps symbols or Solana mints), ipAllow. A request outside the policy fails with error code policy_denied (HTTP 403). Do not retry it. ## Response envelope Success: { "ok": true, "data": , "ts": } Failure: { "ok": false, "error": { "code": , "message": , "details"?: }, "ts": } Error codes (HTTP status): bad_request 400, unauthorized 401, forbidden 403, not_found 404, conflict 409, rate_limited 429, venue_not_connected 409, venue_rejected 422, venue_unavailable 503, venue_timeout 504, insufficient_margin 422, stale_market_data 503, preview_expired 409, policy_denied 403, signing_unavailable 503, not_supported 422, live_off 403, unavailable 503, internal 500. Retry only network errors, timeouts, 429 and 5xx, and only with the same clientId. Never retry policy_denied or live_off. ## Numbers Money the user owns or instructs (orders, fills, positions, balances, fees, previews) is a decimal STRING such as "0.00125". Never parse it as a float for arithmetic that goes back to a venue. Market data (books, trades, candles, tickers) is a JSON number. Times are epoch milliseconds. ## REST routes (relative to /api/v2) Market data (market:read, public): - GET /markets -> Market[] (symbol, instruments per venue with stepSize, priceRule, maxLeverage, fees) - GET /markets/:symbol -> Market - GET /candles?symbol=BTC&res=1m|5m|15m|1h|4h|1d&venue=&from=&to=&limit= -> Candle[] {t,o,h,l,c,v} - GET /route?symbol=BTC&side=buy|sell&size=|notional=&venues=a,b -> best executable route from fresh books - GET /health/feeds -> venue feed health Account (account:read): - GET /me -> userId, wallets, venues, paperBalanceUsd - GET /account?mode=live|paper -> equity, available margin, positions per venue - GET /orders?mode=&status=open|closed|all&symbol=&venue=&limit= (open includes status "unknown") - GET /fills?mode=&symbol=&venue=&from=&to=&limit= - GET /venues Trading (orders:execute): - POST /orders/preview body: OrderIntent -> OrderPreview {previewId, legs, estAvgPrice, estSlippageBps, feeUsd, marginUsd, notices[], placeable, expiresAt}. A preview id lives about 15 seconds. - POST /orders body: { previewId? | intent?, clientId: } -> { orders: Order[] } - DELETE /orders/:id -> Order - POST /orders/cancel-all body: { symbol?, venue?, mode? } - POST /positions/close body: { symbol, venue, fraction (0,1], slippageBps?, mode, clientId } - POST /leverage body: { symbol, venue, leverage, marginMode? } OrderIntent: { symbol, side: "buy"|"sell", type: market|limit|stop_market|stop_limit|take_profit_market|take_profit_limit (default market), size (base units) XOR notional (USD), price (limit types), triggerPrice (stop and take-profit types), tif: gtc|ioc|post_only, reduceOnly, leverage, marginMode: cross|isolated, venue: "auto"|hyperliquid|aster|lighter|pacifica, takeProfit {triggerPrice, price?}, stopLoss {triggerPrice, price?}, slippageBps 1..500, mode: live|paper }. The server picks venue, rounding, fees, margin and the liquidation estimate. Read notices: level "block" means it cannot be placed. Order status: new -> sent -> open | partially_filled | filled | rejected; open/partially_filled -> filled | canceled | expired. "unknown": the venue call timed out. The order may be live. NEVER re-send. The server resolves it by looking the client order id up. Watch it (orders stream or GET /orders?status=all) until it leaves "unknown"; check positions before trading that market again. Solana (mounted at /api/v2/sol): - GET /sol/pulse -> { new, final_stretch, migrated } token cards with risk fields - GET /sol/search?q= - GET /sol/token/:mint, /candles?res=1s|5s|15s|1m|5m|15m|1h&unit=price_usd|market_cap_usd, /trades, /holders, /top-traders, /dev-tokens, /bubble-map - GET /sol/portfolio?mode= - POST /sol/quote body: SolTradeIntent -> SolQuote - POST /sol/trade body: { intent: SolTradeIntent, clientId } -> SolFill (sol:trade) - GET /sol/fills?mode=&mint=&limit=, GET /sol/fills/:id - POST /sol/orders (limit_buy, limit_sell, stop_loss, take_profit, trailing_stop, dca), GET /sol/orders, DELETE /sol/orders/:id - POST /sol/withdraw, GET/PUT/DELETE /sol/watchlist[/:mint] SolTradeIntent: { mint, side, amountSol (buys, SOL to spend) | amountTokens | sellPct (sells), slippageBps (default 300), priorityFeeSol?, tipSol?, mev: off|fast|secure, mode }. SolFill status: submitted -> confirmed | failed | expired. Never treat "submitted" after a timeout as failed. Funding (swap:quote, swap:execute; answers live_off while live trading is off): - GET /funding/options, POST /funding/quote, POST /funding/transfers, GET /funding/transfers[/:id] Config (public): - GET /config -> { live: boolean } Agent platform: - GET /agent/whoami (agent key): scopes, policy, forcedMode, usageToday - GET /agent/tools (public): tool list with JSON schemas, scopes and a mutates flag - GET/POST /agent/keys, PATCH/DELETE /agent/keys/:id, POST /agent/keys/:id/rotate (signed-in user) - GET /agent/activity (signed-in user) - POST /agent/pause body { paused: boolean }: kill switch for every key the user owns (signed-in user) - POST /mcp: hosted MCP server (JSON-RPC over HTTP), same tools and the same bearer key ## Realtime protocol (wss://renko-terminal-api.fly.dev/ws, protocol version 1) JSON text frames. 1. client -> { "op": "hello", "v": 1, "token": "" } (omit token for public data) 2. server -> { "op": "welcome", "v": 1, "sid", "ts", "userId" } 3. client -> { "op": "sub", "id": , "ch": , "params": {...} } 4. server -> { "op": "snap", "id", "seq": 0, "data" } then { "op": "delta", "id", "seq": n, "data" } (seq +1 each) or { "op": "evt", "id", "data" } 5. A gap in seq: send unsub then sub again. 6. server -> { "op": "status", "id", "state": "live"|"degraded"|"down" }. Mark data stale unless live. 7. client -> { "op": "unsub", "id" }, { "op": "ping", "t" } (server answers pong). Server sends tick every 10 s. No frame for 25 s: reconnect. 8. { "op": "auth", "token" } re-authenticates; { "op": "err", "code", "msg" } and { "op": "bye", "code" } come from the server. Limits: 64 subscriptions, 16 KB frames, 20 messages per second per connection. Channels and params: - health {}; markets {}; ticker {symbol}; book {symbol, venue: agg|, depth: 10|25|50}; trades {symbol, venue: all|}; candles {symbol, venue?, res} - private (need the key in hello): account {mode}, orders {mode}, fills {mode}, notifications {}, sol.portfolio {mode} - sol.pulse {}, sol.token {mint}, sol.trades {mint}, sol.candles {mint, res, unit} Book deltas carry changed levels; size 0 removes a level. Levels are [price, size]; the aggregate book adds a per-venue size array. orders: snapshot = open orders, then evt for every order state change including terminal ones. ## Tools 29 tools. The same tool list is served by GET /api/v2/agent/tools, POST /api/v2/mcp (alias /mcp) and the stdio server in packages/mcp (not on npm). Each tool has name, description, inputSchema (JSON Schema), scopes and mutates (true = can move money). Tools run through the REST API with the caller's key, so scopes and policy apply. A refused tool call returns an error result with the REST error code, for example {"error":{"code":"policy_denied","message":"..."}}. ## TypeScript There is no npm package yet. Use plain fetch (Node 20+): send Authorization: Bearer , read { ok, data, error }, and reuse the clientId on retries. A typed client exists in the repository (packages/sdk, not published): build it with pnpm -C packages/sdk build, then import the built dist/index.js. createRenko({ apiKey, baseUrl?, wsUrl?, mode?, WebSocketImpl? }) gives rest, realtime, placeOrder, waitForOrder, streamBook, streamTrades, streamTicker, streamOrders, streamPulse, sol.buy, sol.sell, sol.waitForFill. Errors carry the server code in .code. ## Limits of this build Live trading is off (see STAGE above). With it off these answer live_off: every wallet and funding route (and the funding tools), venue connect and disconnect, perps previews/orders/cancel-all/closes/leverage in live mode, Solana trades and resting orders in live mode, every Solana withdrawal, creating a live key, and any private call with a live key. The same calls in paper mode work. A test key cannot touch a venue account or move funds. A new key has maxLeverage 5 and maxSlippageBps 100: paper perps orders need maxLeverage >= 10, and Solana trades default to 300 bps slippage, so pass slippageBps: 100 or raise the cap. Private WebSocket channels take { mode }. REST v2 has no per-key request rate limit; key create/rotate is 10 per minute; WebSocket 20 messages per second. OpenAPI 3.1: GET /api/v2/openapi.json. ## Rules for agents 1. Start on a test key. Check mode in every result. 2. Preview before placing; do not place when placeable is false or a notice has level block. 3. Use one clientId per intended order and reuse it on every retry. 4. On status "unknown" do not re-send; wait, then verify positions. 5. Stop on unauthorized, forbidden and policy_denied. Do not look for a way around the policy. 6. Money fields are decimal strings. 7. Never put a key in a prompt, a log or a repository.