Docs · Local setup
Run Hunch locally
Hunch is open source. This is the map, the README has the exact commands and environment variables.
Requirements
Node.js and npm. Locally, Hunch falls back to file-backed JSON storage under .data/, so nothing else is required to run it: no database to provision, no house wallet to fund. Production storage and house funding are both opt-in through environment variables, see the README.
Install and run
Hunch is built for the Nimiq Pay WebView, dev bundles don’t run inside it, so a production build is the normal way to actually open it in Nimiq Pay under Mini Apps → Custom URL. The hidden dev menu, a 10-second long-press on settings, switches to testnet and hands out free NIM for testing.
Technical architecture
| Component | Responsibility |
|---|---|
| Wallet | Signs decisions, provides payout authority |
| Commit API | Verifies signed decisions before anything is stored |
| Split engine | Handles the NIM chain, self-funded and house-funded |
| Pair engine | Handles blind two-player commitments for Trust and Ultimatum |
| Payout system | Calculates and settles NIM, tracks queued/sending/sent/failed |
| Abuse layer | Limits repeated house-funded play by wallet, device, and pair |
| Results | Shows a player’s local history, stored on-device |
| Live | Shows anonymised real observations, no identity in the shape |
| Research | Compares Hunch’s observations with published work |
Project structure
Routes live under app/, one folder per experiment or page. Everything that isn’t UI, the round engines, payout logic, abuse controls, wallet signing, storage, lives under lib/ as small, single-purpose modules rather than one shared utility file. Storage goes through one adapter (lib/db.ts), so swapping the local JSON files for Postgres in production is a one-file change, not a refactor.
Everything else
Environment variables, the storage schema, the admin tooling, and deployment specifics are documented directly in the repository rather than here, they change with the code, and a second copy on this page would only ever be the stale one.
View the repository →