Build your own app
Build your own scanner, companion, or collection viewer. WaveBeasts accepts generic signals and exposes account state over HTTP.
Two APIs
Local engine: http://127.0.0.1:8777. Read /capabilities, submit POST /scan, or inspect /collection. If configured, local mutations use X-WB-Token.
Online account: https://wavebeasts.com. Registered device codes authenticate with X-WB-Node-Token. These are different tokens. Create a node on the website; do not embed a user’s code in a public application build.
| Account endpoint | Purpose |
|---|---|
| GET /api/account | Private identity, email, plan, balances and device details |
| POST /api/snapshot | Rate-limited ScanBundle submission |
| GET /api/beasts | Collection, wild sightings, bag and health |
| POST /api/catch | Catch a sighting using a drive |
| POST /api/sightings/dismiss | Dismiss one of your queued wild sightings |
| GET /api/shop · POST /api/buy | Catalog and purchases |
| POST /api/import | Premium local collection import |
| POST /api/sync | Refresh verified beasts once per day |
| GET /api/buddy | Premium companion state and accrued events |
| POST /api/buddy/slot · /api/buddy/care | Select/unslot a companion or apply care |
ScanBundle
{"schema":"wavebeast.scanbundle","v":1,"signals":[
{"kind":"code","strength":1,"value":{"symbology":"manual","data":"A-REAL-CODE"}}
]}Supply actual readings. A valid scan can return a beast, resources, or nothing. Handle HTTP 403 (code rejected), 402 (Premium required), 409 (action conflict), and 429 (wait before retrying). Prices, balances and account rolls are validated by the server.
For the standalone binary’s CLI, Android share intents and deep links, see the integration guide. The website wiki describes the current account features.
One selected host
Engine clients should read GET /host and show its host.kind and host.url prominently. GET /state returns beasts, currency, and items from that authority. Standard scan, catch, shop, inventory, collection, release and training routes follow the selected host. An unavailable host returns an error; it never falls back to a different wallet.
Account linking uses POST /node/config. Select a self-hosted engine with POST /host/config and {"kind":"engine","url":"http://host:8777","token":"optional engine token"}, or choose {"kind":"local"} for this engine’s own database. Existing local saves remain separate and intact. Use the same account or host in each client.
Buddy activity choices
buddy.cooldowns gives the effective seconds until each action is available, including the shared activity lock. A blocked care request returns HTTP 429 with retry_after_sec and the current buddy. Do not retry automatically.
buddy.activity is null when idle, otherwise contains action, ends_at (UTC timestamp) and remaining_sec. buddy.care_options describes each action's duration_sec, cooldown_sec, immediate effects, relationship_gain, xp_gain and decay_multiplier. Use these fields to show the tradeoff before the user chooses. Count down locally, then refresh authoritative state. These account-wide locks survive device and companion changes. See Buddy care for timing and maintenance examples.
For engine clients, GET /state includes scan_ready_in (seconds); account clients receive the same field from GET /api/beasts. Successful scan replies include next_snapshot_in, and rate-limit replies include retry_after. Disable Sweep during the wait and while a request is in flight; count down locally and refresh state on resume. Never auto-submit when the countdown expires.
For Premium accounts, GET /api/account includes recent_snapshots: at most 20 newest submissions across that account’s nodes, with id, node_name, at, outcome and detail. Free accounts receive an empty list. These are submission results, not raw sensor payloads.
Health, history and journals
These private endpoints accept your X-WB-Node-Token. GET responses must not be cached publicly.
| Endpoint | Use |
|---|---|
| GET /api/nodes/status | Health for the account’s nodes. No access tokens or raw readings. |
| GET /api/activity?before=&kind= | 20 newest entries; pass next_before to fetch older ones. Optional kind filter. |
| GET /api/beast/{id} | Owned beast detail plus journal: traits, origin, memories, notes and favorite. |
| POST /api/beast/profile | beast_id, optional boolean favorite, notes (280 chars) and nickname (24 chars). |
POST /api/node/check-in with your usual client version and an optional health object. Example:
{"client":{"id":"my-custom-node","app_v":"1.0.0"},"health":{"heartbeat_sec":120,"mode":"auto","next_attempt_at":"2026-09-23T12:30:00Z","last_attempt_at":"2026-09-23T12:00:00Z","sensors":[{"name":"wifi","status":"available"}],"error":"","failures":0}}Modes: auto, manual, paused or sleeping. Sensor statuses: available, configured, unavailable or unknown. Safe error codes: connection, auth, update_required, resolver, invalid, server, sensor. Send categories, never raw sensor readings. Check-ins do not generate snapshots or rewards.