# Tokens in Arcade games

Use tokens only when they improve a complete free game. Cosmetics, optional support and extra
content can fit; a score or local save is never proof of a payment or prize entitlement.

## Add the module

In Creator Studio, open Toolbox → Game token purchases → Add module. This saves a pinned copy of
`plugins/token-shop.js`, its guide and license. Importing it is a separate step; the installation
never rewrites your game. You can ask Arcade AI to integrate the installed module.

Use an **SDK game**. Signal Sprint is a complete starter. The platform detects literal lifecycle
calls and injects `window.arcade` into the entry page before your scripts run. Register handlers
before `arcade.ready({})`; touch and keyboard games can use the SDK without camera or microphone.

```js
import { tokenShop } from './plugins/token-shop.js';
const shop = tokenShop();
arcade.on('start', resetRun);
arcade.on('pause', () => { paused = true; });
arcade.on('resume', () => { paused = false; });
arcade.ready({});

buyTrailButton.onclick = async () => {
  buyTrailButton.disabled = true;
  const result = await shop.purchase(10, 'Gold trail for this session');
  if (result.ok) {
    trailColor = 'gold'; // Local session cosmetic, not a durable entitlement.
    message.textContent = 'Gold trail enabled for this session.';
  } else {
    message.textContent = result.reason;
  }
  buyTrailButton.disabled = false;
};
```

Functions such as `resetRun` and the UI variables above are your game's own code. Keep a free
trail/default item and clear pending state when the purchase finishes. Never buy on load, during
a timer, or in response to sensor readings. Explain the item, price and session duration before
the player clicks. An existing token market is required; installing this module does not create one.

## What the player approves

`arcade.token` is the selected game's market metadata or null. `arcade.wallet` is the connected
wallet's address and game-token balance or null. Changes arrive via `arcade.on('token', fn)` and
`arcade.on('wallet', fn)`. `arcade.connectWallet()` asks through the platform UI; a player may decline.
`arcade.buyToken()` opens the game's chart/trade page.

`arcade.pay(amount, note)` asks the platform for a creator purchase in the game's token. The
platform owns confirmation, recipient selection, transaction construction and wallet approval.
Game code cannot choose another recipient or pass raw instructions. The promise returns
`{ok:true, tx}` only for a confirmed purchase; otherwise `{ok:false, reason}`. The shop wrapper
checks that result and blocks overlapping clicks. A cancellation, missing market, unavailable
wallet or network error must leave the free game playable.

This is **not** a wager: no escrow, matchmaking deposit, prize payout or 5% burn occurs.
See [the proposed wager protocol](multiplayer.md). Native free multiplayer rooms do not expose
a general-purpose SDK game server. Real wagering is not enabled by a plugin or manifest.

## Test and verify

Studio previews deny wallet requests and never charge real funds. Test refusal and missing-market
states there. Unit-test your gameplay adapter with a fake SDK for success, cancellation, repeated
clicks and errors. Use a separately configured devnet environment for actual transaction testing;
never use automated mainnet purchases to test a game. Test both phone and desktop controls.

A browser can be modified, including its SDK messages and local storage. A local grant is suitable
only for a session cosmetic that has no financial value. For durable purchases, competitive
advantages, balances or rewards, build a reviewed server that independently verifies finalized
receipts, mint/network, payer, recipient and amount; records each transaction once; and handles
retries. The toolbox does not provide that entitlement server. Do not claim account ownership,
permanent items, refunds or anti-cheat guarantees from this browser helper.

Keep paid mechanics out of scored/wagered modes until rules and verification explicitly support
them. Never treat AI credits (the creator's project budget), in-game soft currency, SOL, and a
game's token as interchangeable balances.