API reference
The API describes itself. This page is the map; the OpenAPI document has every field.
The spec
- OpenAPI 3.1, always current: /api/v2/openapi.json (also reachable as /openapi.json).
- Tool list with JSON Schemas: /api/v2/agent/tools (public).
- Base URL:
https://usetomahawk.xyz/api/v2. Auth:Authorization: Bearer renko_sk_....
Envelope and conventions
{ "ok": true, "data": { ... }, "ts": 1794725046239 }
{ "ok": false, "error": { "code": "policy_denied", "message": "...", "details": {} }, "ts": 1794725046239 }Money you own or instruct (orders, fills, positions, balances, fees, previews) is a decimal string such as "0.00125". Market data (books, trades, candles, tickers) is a number. Times are epoch milliseconds. Error codes are listed under Safety.
Routes
| Market data | market:read or public | GET /markets, /markets/{symbol}, /candles, /route, /health/feeds |
| Account | account:read | GET /me, /account, /venues, /orders, /fills |
| Perps trading | orders:execute | POST /orders/preview, POST /orders, DELETE /orders/{id}, POST /orders/cancel-all, POST /positions/close, POST /leverage |
| Solana data | market:read | GET /sol/pulse, /sol/search, /sol/token/{mint} and /candles /trades /holders /top-traders /dev-tokens /bubble-map |
| Solana trading | sol:trade, account:read | POST /sol/quote, POST /sol/trade, GET /sol/fills, POST/GET /sol/orders, DELETE /sol/orders/{id}, GET /sol/portfolio, GET /sol/watchlist |
| Funding | swap:quote, swap:execute | GET /funding/options, POST /funding/quote, POST/GET /funding/transfers. Answers live_off while live trading is off. |
| Config | public | GET /config returns { live }: whether live trading is switched on |
| Agent platform | signed-in user (keys), any key (whoami) | GET /agent/whoami, GET /agent/tools, GET/POST /agent/keys, PATCH/DELETE /agent/keys/{id}, POST /agent/keys/{id}/rotate, POST /agent/pause, GET /agent/activity |
| MCP | any key | POST /mcp |
Placing an order
POST /orders/preview with an OrderIntent returns previewId, legs, fees, margin, notices and placeable. POST /orders takes { intent, clientId, previewId? }: previewId places exactly what you previewed (valid about 15 seconds), intent places fresh. clientId is a UUID you generate; the same one never places twice. See the Quickstart for a run you can paste.
Realtime
wss://renko-terminal-api.fly.dev/ws (the API host: the socket does not go through the site address), JSON text frames. After hello the server sends welcome (and authed with a key). Each sub gets a snap with seq: 0, then delta frames whose seq rises by exactly 1; on a gap, unsub and sub again.
{"op":"hello","v":1,"token":"renko_sk_test_..."}
{"op":"sub","id":1,"ch":"book","params":{"symbol":"BTC","depth":10}}
{"op":"sub","id":2,"ch":"orders","params":{"mode":"paper"}}- Channels:
health markets ticker book trades candles account orders fills notifications sol.pulse sol.token sol.trades sol.candles sol.portfolio. - Private channels (
account orders fills notifications sol.portfolio) need the key inhello, and most take{"mode":"paper"|"live"}. - Limits per connection: 64 subscriptions, 20 messages per second, 16 KiB frames.