Authentication
One bearer key for REST, the WebSocket and MCP. Scopes say what it may call, the policy says how much.
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_... | |
|---|---|---|
| Available | Now | Not yet: live trading is off |
| Trades | The simulator only; the server forces mode paper | The owner's connected venues |
| Venue connection | Not needed | Needed |
| Result field | mode: paper on every order and fill | mode: 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.
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
| Scope | Allows |
|---|---|
| market:read | Markets, books, trades, candles, Solana tokens and Pulse |
| account:read | The owner's balances, positions, orders and fills |
| orders:execute | Preview, place and cancel perps orders |
| swap:quote | Funding quotes (off while live trading is off) |
| swap:execute | Funding transfers (off while live trading is off) |
| sol:trade | Buy 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.
| Field | Meaning | Default |
|---|---|---|
| executionEnabled | Off = read and preview only; nothing that moves money is accepted | false |
| maxOrderUsd | Largest single order, USD notional | 1000 |
| dailyUsd | Total notional per UTC day across everything the key does | 10000 |
| maxLeverage | Highest leverage the key may set or use | 5 |
| maxSlippageBps | Highest slippage tolerance, basis points | 100 |
| venuesAllow | Only these venues | all |
| marketsAllow / marketsDeny | Perps symbols or Solana mints | all |
| ipAllow | Exact IPs or CIDR ranges the key may be used from | any |
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.