API reference
A full, generated reference for the server API is coming. Until then, the routes the app exposes today, with pointers to where each is documented.
Coming soon
A complete, generated API reference — every route, its request and response schema, error codes, and examples — is on the way. This page is a placeholder that lists the routes that exist today and links to where each is explained in full. Treat the shapes below as descriptive, not yet contractual.
The server's job is deliberately small. Your browser talks to the venue directly for market data and order placement; it talks to our server for three things only: confirming who you are, provisioning and governing your Agent Wallet, and running the AI suggestion engine. Everything below is one of those three.
Conventions
These hold across every route and will not change in the generated reference:
- Base path — every route is mounted under
/api. - Auth — every request carries
Authorization: Bearer <Privy JWT>. The acting user is resolved from the verified token, never from the body. See Self-custody for the auth contract. - Errors — failures return
{ "error": { "code", "message", "issues?" } }.issuesis a field-keyed map, present only for validation failures. Stack traces and internal details never appear on the wire.
Routes today
Suggestions
| Method & path | What it does | Documented in |
|---|---|---|
POST /api/suggestions | Validate, check the cache, fan out to providers and pay on a miss, return one merged result plus the per-provider breakdown. | AI suggestions |
GET /api/suggestions/history | List your stored suggestions, newest first. | AI suggestions |
The paid path settles through x402. To plug in your own provider behind this engine, see Connect your AI.
Agent treasury
The wallet that pays for AI calls, and the scoped delegation that governs it.
| Method & path | What it does | Documented in |
|---|---|---|
GET /api/agent-treasury/wallet | Read your Agent Wallet (provisioning is idempotent). | Self-custody |
POST /api/agent-treasury/wallet | Provision your Agent Wallet if it does not exist yet. | Self-custody |
GET /api/agent-treasury/delegation | Read the current delegation status. | Self-custody |
POST /api/agent-treasury/delegation | Grant a scoped, capped, expiring spending delegation. | Self-custody |
POST /api/agent-treasury/delegation/revoke | Revoke the delegation immediately. | Self-custody |
What the generated reference will add
- Full request and response schemas for every route, derived from the server's Zod DTOs so they cannot drift from the code.
- The complete error-code table, mapped from each route's error tags to its HTTP status.
- Worked request and response examples, including the validate-before-pay
422and the x402 settlement path.
If you are building against the API now, the route tables above plus the linked pages are the source of truth. Nothing here is expected to change shape; this page will become the index for the deeper reference once it lands.