Developers / local simulation

Build against the demo, understand its limits.

The local runtime lets software talk to a simulated wallet ledger. Use it to explore the flow before building a real integration.

Open the integration instructions ↓

Three pieces, in plain language.

Runtime: a local service that holds made-up wallet records.
Game API: a way for game code to request demo actions.
MCP: an interface for tools to inspect and interact with that local service.

Connecting to wallet status is not permission to pay. Production approval, game purchases and treasury payouts still need implementation.

Technical details: runtime, Game API and MCP

Wallet runtime · Game API · agent MCP

One local authority. Two deliberate bridges.

Start the wallet on this Mac, then let a game or an authorized agent use a narrowly scoped local interface. The private hosted site explains the route but never reaches into localhost or asks for a token.

Local runtimeNOT CHECKED BY THIS PAGE

Private hosted siteGUIDANCE ONLY

Wallet valueSIMULATED · NO MONETARY VALUE

GAME PROCESS

Game SDK

Game bearer token stays in that process. Rewards require a stable event key.

LOCAL SOURCE OF TRUTH

Wallet authority

Policy, redacted snapshots, activity, and the simulated append-only ledger.

AUTHORIZED AGENT

IUNUA MCP

Named tools use a separate local credential and remain inside wallet policy.

01 / WALLET AUTHORITYMANUAL START · LOOPBACK ONLY

Start the local wallet runtime

Run from the checkout root. This starts the managed simulated wallet authority and Game API on 127.0.0.1:8787; status and stop never print a credential.

Terminal

node services/wallet-runtime/cli.mjs start
node services/wallet-runtime/cli.mjs status
node services/wallet-runtime/cli.mjs stop

02 / AGENT BRIDGELOCAL AGENT TOOLS · OPT-IN

Register the MCP server

Replace the placeholder with this checkout's absolute path. The MCP process reads its mode-0600 local agent credential; no bearer token is stored in the MCP configuration.

Terminal

codex mcp add iunua-wallet -- node "/absolute/path/to/services/wallet-mcp/server.mjs"

03 / GAME BRIDGESIMULATED REWARD · IDEMPOTENT

Run the SDK example

Loads the game credential into this one process, then records a bounded demo reward. Keep the same event key when retrying so one game event cannot pay twice.

Terminal

IUNUA_GAME_TOKEN="$(< ".iunua-wallet/game.token")" node packages/game-sdk/examples/node-reward.mjs

Local wallet authority

The runtime owns the simulated ledger, policy, activity history, and separate game and agent permissions. It binds to 127.0.0.1—not the public internet.

Game API

A game can read its allowed snapshot and record a 1–80 unit reward with a stable idempotency key. It cannot silently export keys or move real value.

MCP for agents

Authorized local agents receive named wallet tools through the MCP server. Every operation remains constrained by runtime policy and the prototype boundary.

Demo apps are separate

The current macOS, iOS, and browser-extension demo stores are not yet synchronized with this authority. Their displayed balances do not update automatically.

Why the private site cannot show “running”

This deployed page is remote content. It intentionally performs no browser request to 127.0.0.1, contains no credential field, and uses no persistent browser storage. Verify the service from Terminal or through the registered MCP health tool instead.