Start · Authentication

Authentication

One bearer key for REST, the WebSocket and MCP. Scopes say what it may call, the policy says how much.

Careful
Paper trading is open. Live trading is not switched on yet: a live key (renko_sk_live_...) cannot be created, there are no wallets, and any live action answers live_off (HTTP 403). Ask the server whether it is on: GET /api/v2/config returns { "live": false } while it is off. Use a test key.

Keys

Send Authorization: Bearer renko_sk_... (or the header x-renko-key: renko_sk_...) on every request, or the same string as the token of the WebSocket hello. Public market data works without a key.

Test key renko_sk_test_...Live key renko_sk_live_...
AvailableNowNot yet: live trading is off
TradesThe simulator only; the server forces mode paperThe owner's connected venues
Venue connectionNot neededNeeded
Result fieldmode: paper on every order and fillmode: live

Create keys on the Agents page (New key, then Test), or with the call below using the session token of a signed-in user. An agent key cannot create keys. The secret is shown once; the backend keeps a hash. Rotate with POST /api/v2/agent/keys/:id/rotate (the old secret stops at once), pause with PATCH /api/v2/agent/keys/:id {"paused":true}, revoke with DELETE. At most 20 active keys per user.

bash
curl -s https://usetomahawk.xyz/api/v2/agent/keys \
  -H "Authorization: Bearer <your session token>" -H "content-type: application/json" \
  -d '{"label":"my agent","env":"test","scopes":["market:read","account:read","orders:execute"],
       "policy":{"executionEnabled":true,"maxOrderUsd":500,"dailyUsd":2000,"maxLeverage":10}}'

Scopes

ScopeAllows
market:readMarkets, books, trades, candles, Solana tokens and Pulse
account:readThe owner's balances, positions, orders and fills
orders:executePreview, place and cancel perps orders
swap:quoteFunding quotes (off while live trading is off)
swap:executeFunding transfers (off while live trading is off)
sol:tradeBuy and sell Solana tokens and manage their orders

Policy

Set per key and enforced in the order service for every order, whether it comes from REST, a script or an MCP tool.

FieldMeaningDefault
executionEnabledOff = read and preview only; nothing that moves money is acceptedfalse
maxOrderUsdLargest single order, USD notional1000
dailyUsdTotal notional per UTC day across everything the key does10000
maxLeverageHighest leverage the key may set or use5
maxSlippageBpsHighest slippage tolerance, basis points100
venuesAllowOnly these venuesall
marketsAllow / marketsDenyPerps symbols or Solana mintsall
ipAllowExact IPs or CIDR ranges the key may be used fromany
Careful
A new key has executionEnabled: false and maxLeverage: 5. The paper account trades at 10x, so a test key needs maxLeverage: 10 or more to place paper orders; below that the answer is policy_denied. Solana trades default to 300 bps of slippage, above the default cap of 100.

A request outside the policy fails with policy_denied (HTTP 403) and is recorded in Activity. Do not retry it. More in Safety.