API
Every public route. JSON in and out, no caching, and every address and transaction comes with its explorer link.
Amounts are whole numbers of wei written as strings (1 HYPE is 1000000000000000000). Prices in USD are numbers. Times are milliseconds unless the name says seconds. Errors look like `{ "ok": false, "error": "plain words" }`.
Sign in by signing a one-time message with your wallet: ask `POST /api/auth/nonce`, sign the message it returns, then send the signature to `POST /api/auth/verify`. Send the token you get back as `Authorization: Bearer <token>`. An access key from the connect page works the same way.
Health and settings
| Route | Who may call it | What it does |
|---|
GET /api/health | None | Whether the server, its database and each part are up. |
GET /api/config | None | Public settings: the fee, the fee choices, desk sizes, the explorer, our coin and every contract address. |
Sign in and access keys
| Route | Who may call it | What it does |
|---|
POST /api/auth/nonce | None | Get a one-time message to sign with your wallet. |
POST /api/auth/verify | None | Send the signature and get a session token. |
GET /api/auth/me | Token or key | Who you are signed in as. |
POST /api/access-keys | Signature | Make an access key for an AI app. It is shown once. |
GET /api/access-keys | Session | List your access keys. |
DELETE /api/access-keys/:id | Session | Revoke an access key. |
Jobs and agents
| Route | Who may call it | What it does |
|---|
POST /api/jobs/parse | None | Read a job in plain words and get its rules back, plus what the vault needs to be created. |
GET /api/drafts/:id | None | A job prepared by an AI app, waiting for you to check and sign. |
POST /api/agents | Token or key | Register the vault you just created. Checked on chain against our factory and your wallet. |
GET /api/agents | Optional | Public agents, or yours with ?mine=1. |
GET /api/agents/:id | Optional | One agent: its rules, events and history. Private agents only for their owner. |
POST /api/agents/:id/message | Token or key | Tell your agent something: status, pause, resume, sell all, change a rule, stop. |
Live feed and numbers
| Route | Who may call it | What it does |
|---|
GET /api/feed | Optional | Every event as it happens, as server-sent events. |
GET /api/feed/recent | Optional | The latest events, newest first. |
GET /api/stats | None | Totals from public agents, the burn and the fee hooks. |
GET /api/burns | None | The minute burn: state, budget, totals and the latest burns with both transactions and their inputs. |
GET /api/proof | None | Keeper addresses, contracts, and the latest real actions with their transactions. |
GET /api/errands/providers | None | Each errand seller and what it can do. |
Order book
| Route | Who may call it | What it does |
|---|
GET /api/book | None | The coins whose Hyperliquid order book agents can watch, read from Hyperbook. |
GET /api/book/:coin | None | One checked reading: price, best buy and sell, money on each side within 0.25% of the price, share of buyers and sellers, and its age. |
Perps
| Route | Who may call it | What it does |
|---|
GET /api/perps/markets | None | The Hyperliquid perps markets agents can trade, with the most leverage and margin allowed. |
POST /api/perps/parse | None | Read a perps job in plain words and get its rules back. |
POST /api/perps/prepare | Session | Make a trading key for your job and get the Hyperliquid approval to sign. The key can trade but cannot withdraw. |
POST /api/perps/activate | Session | Send your signed approval. The agent starts watching the price once Hyperliquid lists it. |
GET /api/perps | Session | Your perps agents. |
GET /api/perps/:id | None | One perps agent: its job, events and its position on Hyperliquid. |
POST /api/perps/:id/close | Session | Close the position at market and stop the agent. |
Private jobs
| Route | Who may call it | What it does |
|---|
POST /api/desk/jobs | None | Create a private job from commitments and a delivery address. Returns its access token once. |
GET /api/desk/jobs/:id | Desk token | A private job's progress. |
POST /api/desk/jobs/:id/cancel | Desk token | Cancel before the deposit is used. |
POST /api/desk/jobs/:id/finish | Desk token | Stop an agent job and deliver. |
GET /api/desk/stats | None | Whether the desk is taking deposits, and how many jobs it has run. |
AI apps
| Route | Who may call it | What it does |
|---|
POST /mcp | Optional key | The MCP link for Claude, ChatGPT, Cursor and other AI apps. |
Private agents and private jobs are only ever shown to their owner. In the public feed they appear as a shadow: the kind of event and its time, nothing else.
Check a burn
Anyone can check a minute burn against the rule, from public chain data only. With this project's code, run `node server/burn/verify.js <burn transaction hash>`. It finds the buy that burn belongs to, works out every number of the rule again from the chain, and prints whether it matches, with each number.
