Start · Quickstart

Quickstart

From nothing to a paper order.

Careful
Paper trading is open. Live trading is not switched on yet: live keys cannot be created, wallets do not exist, and a live action answers live_off (HTTP 403). Every example here uses a test key and trades on the simulator.
  1. 1
    Get 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".

    bash
    export RENKO_API_KEY=renko_sk_test_...

    Every request carries Authorization: Bearer $RENKO_API_KEY. Every answer is { "ok": true, "data": ..., "ts": ... } or an error with a code. Public market data needs no key.

  2. 2
    First requests
    bash
    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"

    whoami returns the key's scopes, policy, forcedMode and today's usage.

  3. 3
    First paper order

    Preview, then place with a client-generated UUID (node -e "console.log(crypto.randomUUID())" prints one). Give exactly one of size (base units) or notional (USD), as a decimal string. Check placeable and notices (level block means 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"
    Note
    Your key needs executionEnabled: true and a maxLeverage of at least 10 to place paper orders, otherwise the answer is policy_denied. Set both when you create the key. See Authentication.
  4. 4
    The same in a script

    Plain fetch, no install. Save it as agent.mjs and 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}`);
  5. 5
    Stream a book
    ts
    // 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 hello the server sends welcome and authed; each sub gets a snap with seq: 0, then delta frames. See the realtime protocol.