walletdocs

Reference

HTTP API

Every route under /api with its method, authentication, request body and response.

All routes live under src/app/api and return JSON unless noted. They accept three kinds of callers:

CallerHowActs as
Browserwallet_session cookie (set by the passkey routes)The signed-in user
Script with a tokenAuthorization: Bearer $WALLET_API_TOKENWALLET_USER_ID, or the owner
Local script, no token configuredNothing, if it passes the local-only rulesWALLET_USER_ID, or the owner

Below, app auth means any of those three. A missing or wrong token gets 401, a token-less request from a non-local host or another site gets 403, and an authorized call before anyone has signed up gets 401.

# With a token configured, add this to every call:
-H "Authorization: Bearer $WALLET_API_TOKEN"

Health

GET /api/health

Open. Runs SELECT 1 against the database and returns {"ok": true}. The Docker healthcheck polls it.

Passkeys and sessions

These are open (they must work signed out) and are called by the sign-in pages; you rarely call them by hand. See Auth & security for the ceremony.

POST /api/auth/register/options

Body: {"name"?: string (≤60), "mode"?: "device" | "phone"}. Signed out, this starts a sign-up: name is required, and it is refused with 403 when sign-ups are closed. Signed in, it starts adding a passkey to your account. Returns WebAuthn creation options and sets the wallet_challenge cookie (5 minutes). phone adds the hybrid hint for the QR code flow.

POST /api/auth/register/verify

Body: {"response": RegistrationResponseJSON, "label"?: string}. Verifies the new credential against the challenge, creates the user on sign-up (the first user becomes the owner) and starts a session. Returns {"ok": true, "user": {"id", "name"}}, or 400 with {"error"}.

POST /api/auth/login/options

Body: {"mode"?: "device" | "phone"}. Returns WebAuthn request options for a discoverable credential and sets the challenge cookie.

POST /api/auth/login/verify

Body: {"response": AuthenticationResponseJSON}. Verifies the assertion, updates the signature counter and starts a 90-day session. Returns {"ok": true, "user": {"id", "name"}}, or 401.

POST /api/auth/logout

Deletes the current session and clears the cookie. Returns {"ok": true}.

GET /api/auth/magic?code=…

Redeems a one-time link printed by npm run auth:link (15 minutes, single use), starts a session and redirects to /settings#security. An invalid or expired code gets a plain-text 401.

Assistant

GET /api/agent

Which backend is configured and whether it can run: {"provider": "anthropic" | "claude-code" | "codex" | "none", "ready": boolean, "reason"?: string, "model"?: string}.

POST /api/agent

App auth. Runs one assistant turn as the caller. Body:

FieldTypeNotes
messagestring, ≤ 20 000 charsMay be empty when attachments is set: the assistant is then asked to import the files.
conversationIdstring, optionalContinue a thread. Omit it, or pass one from another backend, to start a new one.
attachmentsstring[], ≤ 10Upload ids from POST /api/uploads.
channel"web" | "telegram"Formatting style of the answer. Default "web" (Markdown).
streamboolean, optionalStream server-sent events instead of waiting. Accept: text/event-stream does the same.

Without streaming: {"conversationId", "text"}, or 500 with {"error"}. With streaming, the response is text/event-stream with one data: <JSON> line per event, until done or error:

EventFieldsMeaning
conversationid, providerThe thread this turn belongs to (sent first).
textdeltaAnswer text as it's generated.
text_resetDiscard the text streamed so far in this step (retry or model fallback).
tool_startid, name, inputA tool call started.
tool_endid, name, okIt finished.
stepOne model step done; more may follow.
errormessageThe turn failed.
donetextThe final answer.
curl -N -X POST localhost:3000/api/agent -H 'Content-Type: application/json' \
  -d '{"message": "How much did I spend on groceries this month?", "stream": true}'

Turns in the same conversation run one at a time. The route allows up to 300 s.

GET /api/agent/conversations

App auth. Your 50 most recently updated threads: id, title, channel, provider, externalSessionId, createdAt, updatedAt.

GET /api/agent/conversations/:id

App auth. {"conversation", "messages"}, where messages is a display transcript: {role, text, tools: string[], files: string[]} per bubble (tool results and thinking are left out). 404 for an unknown id or someone else's thread.

DELETE /api/agent/conversations/:id

App auth. Deletes the thread and its messages. 204.

Uploads

POST /api/uploads

App auth. multipart/form-data with one or more file fields (up to 10 per request, 15 MB each). Accepted: CSV/TSV, TXT/OFX/QIF/QFX/JSON/MD, PDF, PNG/JPEG/WebP/GIF. Returns one entry per stored file:

[{ "id": "8f0c…", "filename": "october.csv", "size": 18234, "kind": "csv" }]

kind is csv, text, pdf or image. Pass the ids as attachments to /api/agent, or to tools such as import_csv_upload and read_upload. Errors: 400 (no file, unsupported type, a file over 15 MB), 413 when the request declares more than 45 MB.

Requests go through src/proxy.ts, and Next.js buffers at most 16 MB of a proxied body (experimental.proxyClientMaxBodySize), so send large files one per request, as the web app does.

GET /api/uploads

App auth. Your 20 most recent uploads: id, filename, mimeType, size, createdAt.

Tools

GET /api/tools

Every enabled tool: {name, title, description, readOnly, inputSchema}, where inputSchema is JSON Schema. Write tools are missing when WALLET_AGENT_READONLY=1.

POST /api/tools/:name

App auth. The JSON body is the tool's input (see Agent tools). Returns the tool's result as JSON, with cents already converted to currency units. Invalid input, an unknown or disabled tool, or an error inside the tool gives 400 with {"error"}.

curl -X POST localhost:3000/api/tools/record_balance -H 'Content-Type: application/json' \
  -d '{"accountId": 3, "balance": 12500, "note": "from the bank app"}'

MCP

GET | POST | DELETE /api/mcp

App auth. The wallet MCP server over Streamable HTTP, stateless (no session id) with JSON responses. Each request builds a server bound to the caller's user. It exposes every enabled tool plus a wallet_assistant prompt. Returns 401 when no user can be resolved (wrong token, or nobody has signed up yet). Client setup is on MCP & API.

Export

GET /api/export

App auth. Downloads wallet-export-YYYY-MM-DD.json: your accounts, balance snapshots, holdings, categories, rules, transactions, budgets, reminders, saved simulations, conversation list and settings ("format": 2). Chat messages and uploaded files aren't included; back up the database file for a complete copy.

Route index

Generated from the route files under src/app/api at build time.

RouteMethodsSource
/api/agentGETPOST/api/agent/route.ts
/api/agent/conversationsGET/api/agent/conversations/route.ts
/api/agent/conversations/:idGETDELETE/api/agent/conversations/[id]/route.ts
/api/auth/login/optionsPOST/api/auth/login/options/route.ts
/api/auth/login/verifyPOST/api/auth/login/verify/route.ts
/api/auth/logoutPOST/api/auth/logout/route.ts
/api/auth/magicGET/api/auth/magic/route.ts
/api/auth/register/optionsPOST/api/auth/register/options/route.ts
/api/auth/register/verifyPOST/api/auth/register/verify/route.ts
/api/backups/:nameGET/api/backups/[name]/route.ts
/api/exportGET/api/export/route.ts
/api/healthGET/api/health/route.ts
/api/mcpGETPOSTDELETE/api/mcp/route.ts
/api/toolsGET/api/tools/route.ts
/api/tools/:namePOST/api/tools/[name]/route.ts
/api/uploadsGETPOST/api/uploads/route.ts
Edit this page on GitHubReference generated from src/app/api