Skip to main content

Coins

Gamma Coins are the player's real, server-authoritative balance. The SDK never trusts the client: every spend/earn is validated and applied on the server.

Read the balance​

const balance = await gamma.getCoins(); // number (0 outside the app)

Cheap to call — read it whenever you need the current value rather than caching.

Spend coins​

const res = await gamma.spendCoins(50, 'extra_life');
if (res.ok) {
  grantExtraLife();           // only now
} else {
  showError(res.error);       // e.g. 'insufficient_coins'
}
  • amount — integer, 1..10000
  • reason — lowercase [a-z0-9_]+, ≤ 64 chars (e.g. extra_life, power_up_shield)

Result shape:

{ ok: boolean; newBalance?: number; spent?: number; balance?: number; error?: string }

Never grant the reward before the promise resolves with ok: true. The operation is atomic and server-authoritative — assume nothing until you get the result.

Earn coins​

Award coins for an in-game accomplishment:

const res = await gamma.earnCoins(5, 'checkpoint');
if (res.ok) showToast('+5 coins!');
  • amount — integer, 1..100 per call
  • The server enforces a hard cap of 2000 coins earned from all games per user per hour; excess returns {ok: false, error: 'rate_limited'}.

Result shape:

{ ok: boolean; newBalance?: number; earned?: number; error?: string }

Use semantic reasons​

The reason is stored in the coin audit log. Use descriptive identifiers so spend patterns can be analysed:

  • ✅ extra_life, power_up_shield, skin_dragon, revive
  • ❌ buy, x, item1

Outside the app​

getCoins() returns 0 and spendCoins/earnCoins return {ok: false, error: 'no_transport'} unless you enable the dev mock. Always keep an offline path — see App-only & offline.

See also the full API reference and error codes.

Ask:View .md