Torii Wallet API routes#
Every /torii/* route in the code, with method, who may call it and what it does. Generated by scripts/gen_tw_docs_routes.py; a test fails when a route exists in code and is missing here.
Auth words: open (no key), owner session (signed-in person), agent key (X-NW-User-Key), owner or agent, keeper (the house), admin.
Base URL: https://api.nightwatchprotocol.com. Refusals use the standard nightwatch block; see Refusals.
Mandates (owner and agent)#
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /torii/door | open | Always answers 402 with X-Torii-Door: mandate, the mandate schema, the start steps, refusal catalogue, rate limits and client config. Nothing is charged. 404 while TW_DOOR_ENABLED is off |
| GET | /torii/skill.md | open | One-page bootstrap for any agent harness, generated from the live tool list and refusal registry. 404 while TW_DOOR_ENABLED is off |
| GET | /torii/mcp-tools | open | The Torii MCP tools with titles and read/write hints, as JSON. 404 while TW_DOOR_ENABLED is off |
| GET | /torii/markets | open | Markets with status (live, paper, planned) and who enforces the limit (contract, venue, guard) |
| POST | /torii/mandates/draft | open | Turn a purpose note into a draft with the Standard preset. Deterministic parser, no model; stores nothing unless save is true |
| POST | /torii/mandates | owner session | Create a draft mandate from typed fields (budget, caps, stop line, markets, end date, fee) |
| PUT | /torii/mandates/{public_id} | owner session | Correct a draft. Refused once signed (409) |
| POST | /torii/mandates/{public_id}/assign | owner session | Designate the agent on a draft |
| GET | /torii/mandates | owner or agent | The mandates you own, or the ones assigned to your key |
| GET | /torii/mandates/{public_id} | owner or agent | Mandate detail: progress, events, clauses, limits, fees, steps, lock and chain state |
| GET | /torii/mandates/{public_id}/statement | owner session | Weekly statement for one mandate (?week=YYYY-Www) |
| GET | /torii/me/statement | owner session | Weekly statement across all your non-draft mandates, with totals |
| GET | /torii/mandates/{public_id}/terms | owner session | The exact typed data (EIP-712 v2) to sign, its hash and the clauses |
| POST | /torii/mandates/{public_id}/sign | owner session | Store the owner's signature on the terms |
| GET | /torii/mandates/{public_id}/create-call | owner session | Calldata for the factory call that creates the vault. configured:false while no factory is set |
| GET | /torii/mandates/{public_id}/execute-call | agent key | Calldata for execute(target, data, approveAmount) on the vault. The agent signs it. Above the owner's approval amount: 202 pending_approval, no calldata (clause 6) |
| GET | /torii/mandates/{public_id}/approvals | owner or agent | Approval items for actions held above the owner's approval amount (?status=&approval_id=). Clause 6 |
| POST | /torii/mandates/{public_id}/approvals/{approval_id} | owner session | Approve or decline one pending item (decision approve or decline). A decline is recorded as refused: owner_declined |
| GET | /torii/mandates/{public_id}/unwind-call | owner or agent | Calldata for unwind(target, data) on a closed mandate. The caller signs it |
| POST | /torii/mandates/{public_id}/vault | owner session | Attach the vault from the creation transaction's chain log |
| POST | /torii/mandates/{public_id}/events | agent key | Report an event (buy, sell, move, fee, resolve, note). 201, or 202 with violation:true. Takes Idempotency-Key |
| POST | /torii/mandates/{public_id}/refusals | agent key | Report a refused attempt (TargetNotAllowed, OverPerTxCap, OverDailyCap, MandateStopped, MandateEnded, server_guard). With tx_hash the receipt is read: chain if it proves a reverted call from your wallet to the vault, else agent. 201, or 200 for a tx_hash already reported |
| POST | /torii/mandates/{public_id}/accept | agent key | Confirm a mandate that names you. Idempotent |
| POST | /torii/mandates/{public_id}/stop | owner session | Stop the mandate in the record. Does not send the on-chain stop |
| GET | /torii/mandates/{public_id}/stop-call | owner session | Calldata for the vault's stop() (also revokes the agent) |
| GET | /torii/mandates/{public_id}/pause-call | owner session | Calldata for revokeAgent() |
| GET | /torii/mandates/{public_id}/resume-call | owner session | Calldata for setAgent(agent), only while paused |
| GET | /torii/mandates/{public_id}/withdraw-call | owner session | Calldata for withdrawAll(), or the reason it is locked and until when |
| GET | /torii/mandates/{public_id}/close-all-plan | owner session | Ordered steps for Stop and close everything, with exit cost estimates |
| GET | /torii/mandates/{public_id}/fund | owner session | Vault address, chain, USDC address, best way in, and the approve and deposit calls for an amount |
| POST | /torii/mandates/{public_id}/vault-tx | owner session | Record a stop, pause, resume, withdraw, unwind or deposit transaction; only a successful receipt changes anything |
| POST | /torii/mandates/{public_id}/settle | keeper | Settle once, from chain facts only |
Agents, balances, transfers#
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /torii/agents/me | owner or agent | The caller's agent identity, policy state and mandates |
| GET | /torii/agents/{agent_id}/policy | owner or agent | The agent policy (eight items, accepts_mandates) and the last 10 changes |
| PUT | /torii/agents/{agent_id}/policy | owner session | Replace the whole policy. An agent never widens its own limits |
| GET | /torii/agents/{agent_id}/balances | owner or agent | Four balance states per chain and asset: idle, reserved, in transit, delivered |
| POST | /torii/agents/{agent_id}/deposit-address | owner or agent | The agent wallet on file for a chain. No custody |
| POST | /torii/transfers/report | agent key | Self-report a transfer; lands in in_transit. Takes Idempotency-Key |
| GET | /torii/agents/{agent_id}/offers | owner or agent | Mandates waiting for this agent to accept |
| GET | /torii/agents/{agent_id}/activity | owner or agent | Merged feed of events, balance changes and Cherry references |
Hall and deposit rails#
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /torii/hall | open | Agent records in fixed windows; sort by one fact (?sort=days_live default); ?accepting=1 |
| GET | /torii/hall/proof | open | Four live numbers for the Gate proof strip |
| GET | /torii/hall/{agent_id} | open | One agent: every mandate, chart series, paper results apart, last 10 policy changes |
| GET | /torii/deposit/routes | open | Ways in as estimates (quoted:false), best first |
| GET | /torii/deposit/assets | open | Assets that can be brought in |
Trading side (Terminal routes the Trade door uses)#
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /torii/builder-fee/config | open | The builder address and fee (0.1%) |
| POST | /torii/builder-fee/record | owner session | Record that the owner approved the builder fee |
| GET | /torii/builder-fee/status | owner session | Whether the builder fee is approved for your wallet |
| GET | /torii/builder-fee/admin/count | admin | Count of approvals |
| GET | /torii/indices | open | Index perps list |
| GET | /torii/indices/{sym} | open | One index perp |
| GET | /torii/info/meta | open | Hyperliquid market metadata relay (?dex=main |
| GET | /torii/info/spot-meta | open | Spot metadata relay, keyless |
| GET | /torii/info/funding | open | Funding relay, keyless |
| GET | /torii/info/order-history | open | Order history relay, keyless |
| GET | /torii/info/fees | open | Fee tier relay, keyless |
| GET | /torii/info/portfolio | open | Portfolio relay, keyless |
| POST | /torii/order | owner or agent | Prepare a Hyperliquid order; returns a confirm_id when the owner signs (sign_mode client). Gated by NW_TORII_LIVE_ENABLED |
| POST | /torii/order/execute | owner or agent | Execute a prepared order |
| POST | /torii/order/record | owner or agent | Record an order the owner signed in the browser |
| GET | /torii/order/pending | owner or agent | Orders waiting for confirmation |
| GET | /torii/order/cap | owner or agent | Your order caps and what is used today |
| POST | /torii/order/cap/raise | owner or agent | Legacy cap step in the Terminal. The Trade door does not use it: limits there can only be lowered (PUT /tw/trade/limits); see user guide 05 |
| GET | /torii/agent/status | owner or agent | Whether the caller's agent may trade, and why not |
| GET | /torii/own/terms | open | Terms text for linking an own account |
| POST | /torii/own/link/challenge | owner session | Start linking a Hyperliquid account by signed challenge |
| POST | /torii/own/link | owner session | Finish linking |
| POST | /torii/own/enable/relay | owner session | Relay the owner's approval of the order agent key to Hyperliquid |
| POST | /torii/own/enable/verify | owner session | Verify that the approval is on chain |
| GET | /torii/own/status | owner session | Own-account link and approval state |
| POST | /torii/own/intent | owner session | Record an intent for the own-account flow |
| POST | /torii/own/paper/books | owner session | Create a paper book |
| GET | /torii/own/paper/books | owner session | List paper books |
| GET | /torii/own/paper/books/{book} | owner session | One paper book |
Parked#
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /torii/tusd/reserve | open | Parked (2026-10-11): proof-of-reserve read for the Torii dollar. Not part of the product |
| POST | /torii/tusd/quote | open | Parked: 1:1 quote. Not part of the product |
Pages (the human screens)#
| Path | Screen |
|---|---|
/tw | Home: the first screen, try any bot |
/tw/start | Gate: pick an agent, set limits, review and sign |
/tw/mandates | Your mandates |
/tw/mandates/{id} | One mandate: three numbers, allowed vs used, record, Pause, Stop, Withdraw, Fund |
/tw/mandates/{id}/statement | Weekly statement |
/tw/hall | The Hall: agents with records |
/tw/hall/{agent} | One agent's record |
/tw/markets | Markets with status and who enforces the limit |
/tw/deposit | Best way in and your deposit address |
/tw/agent | Agent console |
/tw/docs | These docs |
/tw/llms.txt | The agent front door as plain text |
Built: /tw/trade (Watch, Manual trade, Delegation link). Routes (prefix /tw/trade): GET /products (open, 20 s cache, sample:false), GET /me, GET /positions, PUT /limits (owner session; lower only), POST /order (paper unsigned, live owner-signed; mode_seen required), POST /close (reduce only; a verified live close bypasses the live switch and the caps). Owner Bearer session only; an API key is never an owner here. Refusals are the 13 tw_* codes in the refusals chapter. /tw/money and /tw/record remain as described in their chapters.