TOOLING · REFERENCE WALLET

Sandbox wallet

A runnable in-memory wallet implementing the wallet contract — including the unhappy paths. Point your handlers at it and exercise the full cycle in minutes.

LAST UPDATED 2026-07-27

Install & run

npm install https://docs.fidra.tech/pkg/fidra-sandbox-wallet-0.1.0.tgz
npx fidra-sandbox-wallet                        # → http://localhost:4800

The tarball is the canonical distribution channel (works with npm, pnpm and yarn; Node ≥ 18; zero runtime dependencies). Verify the download if your policy requires it:

shasum -a 256 fidra-sandbox-wallet-0.1.0.tgz
# 0ffc7c736f0c45af3979304f99694387f209009cf692268c1e8da499a0879f51

In-memory, zero-dependency, not for production. Wire it into your host page: answer bet_intent by POST /bet, reply fidra:v1:bet_result with the JSON; same for settle_intent → POST /settle.

Endpoints

method · path	body	returns
`POST /bet`	`{ playerId, roundId, gameId?, amount }`	`{ ok, roundId, balance?, reason? }`
`POST /settle`	`{ playerId, roundId, gameId?, payout }`	same shape — `payout: 0` on a loss
`POST /rollback`	`{ roundId }`	void an un-settled bet; refuses settled/already-rolled-back rounds
`GET /balance?playerId=p1`	—	`{ playerId, balance }`
`POST /admin/fail`	`{ mode }`	set a failure mode (below)
`POST /admin/reset`	—	clear balances + rounds + fail mode
`GET /health`	—	`{ ok, failMode }`

What it enforces — the contract's load-bearing parts

roundId idempotency — a repeated /bet or /settle for a seen roundId replays the stored result and never re-mutates the balance. This is what makes the feed's timeout-retry safe.
rollback — credits an un-settled stake back.
losses settle — /settle with payout: 0 closes the round.

Force the failure cases

mode	effect	exercises
`none`	normal	happy path
`insufficient`	`/bet` → `ok:false, reason:insufficient_funds`, no debit	declined bet
`reject`	`/bet` → `ok:false, reason:rejected`	generic decline
`timeout`	delays 3500ms — past the feed's 3000ms budget	client timeout → retry with the same `roundId` → idempotent replay
`error500`	HTTP 500 on `/bet` & `/settle`	wallet backend down

curl -XPOST localhost:4800/admin/fail -d '{"mode":"timeout"}'
curl -XPOST localhost:4800/bet -d '{"playerId":"p1","roundId":"r1","amount":50}'   # hangs 3.5s
curl -XPOST localhost:4800/admin/fail -d '{"mode":"none"}'

Every mode is also settable per-request with ?fail=<mode> on /bet and /settle.

source of truth: packages/sandbox-wallet/README.md fidra is a B2B software supplier — no gambling services operated, no player funds held. g.jgerenaia@tomsons.co