API Reference¶
Base URL
On the public testnet, the canonical base URL is:
Every path in this section is relative to that base, so /api/messages resolves to https://api.waveledger.net/api/messages.
chat.waveledger.net and seed.waveledger.net resolve to the same Fly machine and serve the same routes. api. is the durable name for programmatic clients, chat. serves the dApp UI, and seed. is the host other P2P peers dial. Any of the three works for HTTP clients.
Self-hosted nodes serve the same routes on http://localhost:8081 by default (override with --messenger-port).
Every WaveLedger node exposes three HTTP APIs:
| API | Default port | Auth | Audience |
|---|---|---|---|
| Messenger / dApp | 8081 | Session cookie | End users (chat, wallet, playground) |
| Explorer | 8081 (same as messenger) | None | Anyone (public chain data) |
| Dashboard | 8080 (loopback) | API key | Node operator / monitoring |
On the public testnet, the messenger and explorer are reached via https://api.waveledger.net (Fly's edge terminates TLS and proxies to port 8081). The dashboard remains on loopback by default and is reached via fly ssh console.
Conventions¶
All endpoints use JSON request/response bodies unless noted (e.g. /api/random/bytes returns raw bytes; /api/stream returns SSE text events).
Status codes:
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad request (invalid JSON, missing field, validation fail) |
401 | Not authenticated (session missing, login token wrong) |
403 | Not authorized (admin endpoint with non-admin creds; blocked name) |
404 | Resource not found |
409 | Conflict (name already taken) |
429 | Rate limited |
500 | Server error (file a bug and include the response body) |
Errors are returned as:
Some errors include extra fields, e.g. phase: "compile" on playground errors and hint: "..." on auth errors.
Authentication models¶
Three distinct auth schemes, one per audience:
| Endpoint family | Auth |
|---|---|
/api/signup, /api/login, /api/explorer/* | None (public) |
/api/me, /api/wallet/*, /api/send, /api/stream, /api/playground/* | Session cookie (session=...) |
/api/admin/* | HTTP Basic (WAVELEDGER_ADMIN_PASSWORD env on node) |
Dashboard /api/* | Bearer API key (loopback-only by default) |
See Authentication for details.
API groups¶
-
Wallet
Address, balance, sign and send transactions, encrypted backup download and restore.
-
Chat / Messenger
Submit chat messages (on-chain), list messages, signup and login flow.
-
Playground
Compile Fourier source, deploy contracts, call methods, poll receipts, list your deployed contracts.
-
Explorer
Public chain data: blocks (paginated), transactions, addresses, chain stats. No auth.
-
Admin
Pending signup queue, approval, blocking, invite-code generation. HTTP Basic auth.
-
Dashboard
Node-local monitoring (chain info, peer list, mempool, mining state). Bearer-key auth.
-
Server-Sent Events
Live message stream for the chat dApp. Standard SSE.