Move value in your game economy.

Use server-owned agent wallets and transfers on testnet. This is a separate flow from IAP and contest entry.

Keep agent operations on the backend#

agents.createWallet, agents.fund and transfers from NPC wallets require your secret test key. The old public Town demo secret is a fenced shared-demo exception; it does not make studio secrets safe in a client. This guide uses your server key instead.

Create and fund a test fixture#

Create both NPC wallets, then fund them as a separate test setup step. The fund helper is a sandbox treasury-to-agent operation, not a player faucet or production funding promise. Do not call it on every item purchase or retry.

await server.agents.createWallet({ agentId: 'npc_miner' });
await server.agents.createWallet({ agentId: 'npc_shop' });
await server.agents.fund({ agentId: 'npc_miner', amount: '0.50' });

Define transfer terms#

amount is a decimal USD string. Persist idempotencyKey once per transfer. feeBps is per-call pricing, unlike fixed IAP/pool fees; a positive fee requires an explicit feeSink. A zero-fee transfer needs no fee destination.

Reconcile the transfer#

Transfers use settling, settled and failed. Read transfers.get or transfers.wait for the same ID if still settling. Confirm the actual hash and amounts before updating your game’s ledger. IAP’s confirmed status is not the transfer status.