Quickstart
From nothing to a paper order.
live_off (HTTP 403). Every example here uses a test key and trades on the simulator.- 1Get a test key
Sign in to the terminal, open the Agents page, choose New key, pick Test, tick the scopes you need and copy the secret. It is shown once. A test key trades on the simulator only: the server forces
mode: "paper".bashexport RENKO_API_KEY=renko_sk_test_...Every request carries
Authorization: Bearer $RENKO_API_KEY. Every answer is{ "ok": true, "data": ..., "ts": ... }or anerrorwith acode. Public market data needs no key. - 2First requestsbash
curl -s https://usetomahawk.xyz/api/v2/markets/BTC -H "Authorization: Bearer $RENKO_API_KEY" curl -s https://usetomahawk.xyz/api/v2/agent/whoami -H "Authorization: Bearer $RENKO_API_KEY"whoamireturns the key's scopes, policy,forcedModeand today's usage. - 3First paper order
Preview, then place with a client-generated UUID (
node -e "console.log(crypto.randomUUID())"prints one). Give exactly one ofsize(base units) ornotional(USD), as a decimal string. Checkplaceableandnotices(levelblockmeans it cannot be placed). The limit price here is far below the market, so the order rests open until you cancel it.bash# preview: venue, rounding, fees, margin. The previewId is valid for about 15 seconds. curl -s https://usetomahawk.xyz/api/v2/orders/preview \ -H "Authorization: Bearer $RENKO_API_KEY" -H "content-type: application/json" \ -d '{"symbol":"BTC","side":"buy","type":"limit","size":"0.001","price":"50000","tif":"post_only","mode":"paper"}' # place: the previewId from above and a fresh UUID curl -s https://usetomahawk.xyz/api/v2/orders \ -H "Authorization: Bearer $RENKO_API_KEY" -H "content-type: application/json" \ -d '{"previewId":"<previewId>","clientId":"<a fresh UUID>"}' # cancel: the order id from the answer curl -s -X DELETE https://usetomahawk.xyz/api/v2/orders/<order id> \ -H "Authorization: Bearer $RENKO_API_KEY"NoteYour key needsexecutionEnabled: trueand amaxLeverageof at least 10 to place paper orders, otherwise the answer ispolicy_denied. Set both when you create the key. See Authentication. - 4The same in a script
Plain fetch, no install. Save it as
agent.mjsand run it with Node 20 or later.ts// agent.mjs (Node 20 or later: node agent.mjs) const BASE = "https://usetomahawk.xyz"; const KEY = process.env.RENKO_API_KEY; async function call(method, path, body) { const res = await fetch(`${BASE}/api/v2${path}`, { method, headers: { Authorization: `Bearer ${KEY}`, "content-type": "application/json" }, body: body ? JSON.stringify(body) : undefined, }); const json = await res.json(); if (!json.ok) throw new Error(`${json.error.code}: ${json.error.message}`); return json.data; } const intent = { symbol: "BTC", side: "buy", type: "limit", size: "0.001", price: "50000", tif: "post_only", mode: "paper" }; const preview = await call("POST", "/orders/preview", intent); if (!preview.placeable) throw new Error(JSON.stringify(preview.notices)); const clientId = crypto.randomUUID(); // one per order; reuse it on a retry const { orders } = await call("POST", "/orders", { previewId: preview.previewId, clientId }); console.log(orders[0].mode, orders[0].status, orders[0].venue); // paper open <venue> await call("DELETE", `/orders/${orders[0].id}`); - 5Stream a bookts
// book.mjs (Node 22 or later has a global WebSocket) const ws = new WebSocket("wss://renko-terminal-api.fly.dev/ws"); ws.onopen = () => { ws.send(JSON.stringify({ op: "hello", v: 1, token: process.env.RENKO_API_KEY })); ws.send(JSON.stringify({ op: "sub", id: 1, ch: "book", params: { symbol: "BTC", depth: 10 } })); }; ws.onmessage = (e) => console.log(JSON.parse(e.data)); // welcome, authed, snap (seq 0), then delta (seq 1, 2, ...)After
hellothe server sendswelcomeandauthed; eachsubgets asnapwithseq: 0, thendeltaframes. See the realtime protocol.