Build games that earn with iCoin

What is the iCoin SDK?

iCoin is iWin's universal in-game currency. The iCoin SDK is a small JavaScript file you include in your HTML5 game; once loaded, your game gets a window.iwinobject that lets it spend the signed-in player's iCoin balance on items you define.

Under the hood, the SDK speaks to the iWin parent page via postMessage. Your game never sees the player's auth token. The parent makes the authenticated wallet API call on the player's behalf and returns a structured result.

Player identity — no login required

Your game never builds a login screen. The player signs in to iwin.com once (Cognito / Google / Apple / Facebook), and the SDK delivers their identity to your game automatically at handshake time.

What works signed-out vs signed-in

The handshake (when the player IS signed in)

1. Player signs in to iwin.com (one time, owned by iWin's auth).
2. Player opens any game at /online-games/play/<slug>. iWin embeds your game in an iframe.
3. Your game's <script src="...iwin-bridge-v1.js"> loads. window.iwin appears.
4. Game calls await window.iwin.ready() → resolves with the handshake payload:

   {
     sdkVersion: "1.0.0",
     user: { sub: "abc-uuid", displayName: "Pete" } | null,
     balance: 200,
     catalog: [...],
     iapMode: "iwin-catalog" | "quote",
     gameSlug: "your-slug"
   }

5. Game reads hello.user.sub — that's the Player ID. Done.

Typical game-side boot code

// Typical game-side boot flow. No login code needed.

const hello = await window.iwin.ready();

if (hello.user) {
  // Player is signed in. hello.user.sub is the Player ID — stable
  // UUID, same value shown on the player's /profile page.
  startGameForPlayer(hello.user.sub, hello.user.displayName);
} else {
  // Signed out — start the game ANYWAY in anonymous mode. The player
  // can play normally. We'll only prompt login when they try to do
  // something that requires identity (buy iCoin items, etc.).
  startGameAnonymously();
}

// When the player tries to buy something while signed out:
async function onBuyClick(sku) {
  try {
    return await window.iwin.spend({ sku });
  } catch (e) {
    if (e.code === "NOT_AUTHENTICATED") {
      // Prompt login, then retry. The post-login "user" event below
      // also fires so the rest of your UI updates.
      const { signedIn } = await window.iwin.requestLogin();
      if (signedIn) return window.iwin.spend({ sku });
    }
    throw e;
  }
}

// Subscribe to identity changes (sign-in / sign-out mid-session).
// The user.sub on the payload is the player's real Cognito Player ID —
// same UUID shown on their /profile page, same key in iWin's wallet.
window.iwin.on("user", ({ user }) => {
  if (user) {
    console.log("player signed in as", user.sub, user.displayName);
    // Game can now refresh balance, unlock signed-in UI, etc.
  } else {
    console.log("player signed out");
    showLockedShopUI();
  }
});

What's available to the game

For games with their own backend

If your game has a backend (and needs to associate iWin players with a game-internal user record), the canonical pattern is:

• Trust the SDK's sub directly.Game's frontend POSTs { sub } (or whatever player state you need to sync) to your backend; your backend creates/looks up a row keyed on sub. Simple. Trusts the parent — which is iwin.com, so it's safe.
• Stronger proof: opt into spend receipts.Each successful spend can include a KMS-signed JWT containing the player's sub + the wallet ledger entry id. Your backend verifies the signature against /v1/wallet/receipt-public-key. See the Spend receipts section for the verification pattern. Skip unless you genuinely need server-verified identity claims.

Quick Start

Two pricing modes. Pick the one that fits your game.

// In your HTML5 game (loaded inside the iWin player frame):
await window.iwin.ready();

const { items } = await window.iwin.getCatalog();
renderShop(items);

// On "Buy" click:
const res = await window.iwin.spend({ sku: "gems_500" });
if (res.ok) {
  grantInventory("gems_500"); // your game's own state
} else if (res.code === "INSUFFICIENT_FUNDS") {
  await window.iwin.openTopUp();
}

// In your game's frontend:
const quote = await fetch("/api/iap-quote", {
  method: "POST",
  body: JSON.stringify({ sku: "gems_500" }),
}).then(r => r.text());

const res = await window.iwin.spend({ sku: "gems_500", quote });
if (res.ok) grantInventory("gems_500");

Quote-signing snippet (Node + jose)

Your game's backend signs the JWT. Keep the private key in your own secrets store; iWin only sees the public half.

// In your backend (Node example with 'jose'):
import { SignJWT, importPKCS8 } from "jose";

const key = await importPKCS8(process.env.MY_GAME_PRIVATE_KEY_PEM, "ES256");

app.post("/api/iap-quote", async (req, res) => {
  const { sku } = req.body;
  const coins = lookupPrice(sku); // your pricing logic
  const jwt = await new SignJWT({ slug: "my-game", sku, coins, nonce: uuid() })
    .setProtectedHeader({ alg: "ES256" })
    .setIssuedAt()
    .setExpirationTime("5m")
    .sign(key);
  res.type("text/plain").send(jwt);
});

Unity / WebGL integration

Unity WebGL games speak to window.iwinthrough Unity's standard .jslibplugin pattern. Drop two files into your project and you're done. Magic Match is the reference user.

// Assets/Plugins/WebGL/IWinBridge.jslib
//
// Bridges Unity C# DllImports to window.iwin. Each call routes the
// async result back into Unity via SendMessage(gameObjectName,
// "OnIWinResult", json).

mergeInto(LibraryManager.library, {
  IWin_Ready: function (goNamePtr, reqIdPtr) {
    var goName = UTF8ToString(goNamePtr);
    var reqId = UTF8ToString(reqIdPtr);
    if (!window.iwin) {
      SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: "NO_SDK" }));
      return;
    }
    window.iwin.ready()
      .then(function (h) { SendMessage(goName, "OnIWinResult", JSON.stringify(Object.assign({ requestId: reqId, ok: true, type: "ready" }, h))); })
      .catch(function (e) { SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: e.code || "ERROR", message: e.message || String(e) })); });
  },

  IWin_GetBalance: function (goNamePtr, reqIdPtr) {
    var goName = UTF8ToString(goNamePtr);
    var reqId = UTF8ToString(reqIdPtr);
    if (!window.iwin) {
      SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: "NO_SDK" }));
      return;
    }
    window.iwin.getBalance()
      .then(function (r) { SendMessage(goName, "OnIWinResult", JSON.stringify(Object.assign({ requestId: reqId, ok: true, type: "balance" }, r))); })
      .catch(function (e) { SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: e.code || "ERROR", message: e.message || String(e) })); });
  },

  IWin_Spend: function (goNamePtr, reqIdPtr, argsJsonPtr) {
    var goName = UTF8ToString(goNamePtr);
    var reqId = UTF8ToString(reqIdPtr);
    var args;
    try { args = JSON.parse(UTF8ToString(argsJsonPtr)); }
    catch (e) {
      SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: "BAD_ARGS" }));
      return;
    }
    if (!window.iwin) {
      SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: "NO_SDK" }));
      return;
    }
    window.iwin.spend(args)
      .then(function (r) { SendMessage(goName, "OnIWinResult", JSON.stringify(Object.assign({ requestId: reqId, ok: true, type: "spend" }, r))); })
      .catch(function (e) { SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: e.code || "ERROR", message: e.message || String(e) })); });
  },

  IWin_OpenTopUp: function (goNamePtr, reqIdPtr) {
    var goName = UTF8ToString(goNamePtr);
    var reqId = UTF8ToString(reqIdPtr);
    if (!window.iwin) {
      SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: "NO_SDK" }));
      return;
    }
    window.iwin.openTopUp()
      .then(function (r) { SendMessage(goName, "OnIWinResult", JSON.stringify(Object.assign({ requestId: reqId, ok: true, type: "topup" }, r))); })
      .catch(function (e) { SendMessage(goName, "OnIWinResult", JSON.stringify({ requestId: reqId, ok: false, code: e.code || "ERROR", message: e.message || String(e) })); });
  },
});

// Assets/Scripts/IWinBridge.cs
//
// Mount as a GameObject named "IWinBridge" in your boot scene. Make
// it DontDestroyOnLoad so it survives scene transitions.

using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using System.Threading.Tasks;
using UnityEngine;

public class IWinBridge : MonoBehaviour
{
    public static IWinBridge Instance { get; private set; }

#if UNITY_WEBGL && !UNITY_EDITOR
    [DllImport("__Internal")] private static extern void IWin_Ready(string goName, string requestId);
    [DllImport("__Internal")] private static extern void IWin_GetBalance(string goName, string requestId);
    [DllImport("__Internal")] private static extern void IWin_Spend(string goName, string requestId, string argsJson);
    [DllImport("__Internal")] private static extern void IWin_OpenTopUp(string goName, string requestId);
#endif

    private readonly Dictionary<string, TaskCompletionSource<string>> _pending = new();

    private void Awake()
    {
        if (Instance != null && Instance != this) { Destroy(gameObject); return; }
        Instance = this;
        DontDestroyOnLoad(gameObject);
    }

    // ── Async API used from your gameplay code ────────────────────────

    public Task<HelloResult> Ready()                  => Call<HelloResult>(reqId => Native.Ready(name, reqId));
    public Task<BalanceResult> GetBalance()            => Call<BalanceResult>(reqId => Native.GetBalance(name, reqId));
    public Task<SpendResult> Spend(string sku, string quote = null, string clientTxId = null, bool receipt = false)
    {
        var args = JsonUtility.ToJson(new SpendArgs {
            sku = sku,
            quote = quote,
            clientTxId = clientTxId ?? Guid.NewGuid().ToString(),
            receipt = receipt,
        });
        return Call<SpendResult>(reqId => Native.Spend(name, reqId, args));
    }
    public Task<TopUpResult> OpenTopUp()               => Call<TopUpResult>(reqId => Native.OpenTopUp(name, reqId));

    // ── Internals ─────────────────────────────────────────────────────

    private Task<T> Call<T>(Action<string> invoke)
    {
        var reqId = Guid.NewGuid().ToString();
        var tcs = new TaskCompletionSource<string>();
        _pending[reqId] = tcs;
        try { invoke(reqId); }
        catch (Exception e) { tcs.SetException(e); _pending.Remove(reqId); }
        return tcs.Task.ContinueWith(t => {
            var json = t.Result;
            var env = JsonUtility.FromJson<Envelope>(json);
            if (!env.ok) throw new IWinException(env.code, env.message);
            return JsonUtility.FromJson<T>(json);
        });
    }

    // Called by .jslib via SendMessage(name, "OnIWinResult", json).
    public void OnIWinResult(string json)
    {
        try {
            var env = JsonUtility.FromJson<Envelope>(json);
            if (_pending.TryGetValue(env.requestId, out var tcs)) {
                _pending.Remove(env.requestId);
                tcs.SetResult(json);
            }
        } catch (Exception e) {
            Debug.LogError($"IWinBridge: parse failed: {e.Message}");
        }
    }

    // ── Wire to the .jslib (no-ops outside WebGL builds) ──────────────

    private static class Native
    {
#if UNITY_WEBGL && !UNITY_EDITOR
        public static void Ready(string n, string r) => IWin_Ready(n, r);
        public static void GetBalance(string n, string r) => IWin_GetBalance(n, r);
        public static void Spend(string n, string r, string j) => IWin_Spend(n, r, j);
        public static void OpenTopUp(string n, string r) => IWin_OpenTopUp(n, r);
#else
        public static void Ready(string n, string r) => throw new IWinException("NO_PARENT", "iCoin SDK only works in WebGL builds");
        public static void GetBalance(string n, string r) => throw new IWinException("NO_PARENT", "iCoin SDK only works in WebGL builds");
        public static void Spend(string n, string r, string j) => throw new IWinException("NO_PARENT", "iCoin SDK only works in WebGL builds");
        public static void OpenTopUp(string n, string r) => throw new IWinException("NO_PARENT", "iCoin SDK only works in WebGL builds");
#endif
    }

    // ── Serializable result types (Unity's JsonUtility only handles top-level) ──

    [Serializable] private class Envelope { public string requestId; public bool ok; public string code; public string message; public string type; }
    [Serializable] private class SpendArgs { public string sku; public string quote; public string clientTxId; public bool receipt; }

    [Serializable] public class HelloResult   { public string sdkVersion; public long balance; public string iapMode; public string gameSlug; }
    [Serializable] public class BalanceResult { public long balance; public string currency; }
    [Serializable] public class SpendResult   { public long balance; public string ledgerSk; public bool idempotent; public string sku; public long coins; public string receipt; }
    [Serializable] public class TopUpResult   { public bool opened; }
}

public class IWinException : Exception
{
    public string Code { get; }
    public IWinException(string code, string message) : base(message) { Code = code; }
}

// In any gameplay script, after IWinBridge is in the scene:
//
// IWinBridge.Instance must be reachable from the moment your shop UI
// appears. Mounting it in your boot scene (with DontDestroyOnLoad)
// is the standard pattern.

using UnityEngine;
using System.Threading.Tasks;

public class ShopController : MonoBehaviour
{
    public async void OnGemsClicked()
    {
        // 1. Fetch a fresh quote from YOUR backend (Magic Match's case:
        //    POST https://magicmatch.example.com/v1/iap-quote)
        var quote = await MyGameBackend.FetchIapQuote("gems_500");

        try
        {
            var result = await IWinBridge.Instance.Spend("gems_500", quote);
            // result.coins = how many iCoins were debited (server-authoritative)
            // result.ledgerSk = wallet ledger entry id (audit trail)
            GrantGems(500);
            ShowToast($"Spent {result.coins} coins · balance now {result.balance}");
        }
        catch (IWinException e) when (e.Code == "INSUFFICIENT_FUNDS")
        {
            await IWinBridge.Instance.OpenTopUp(); // opens modal or /store per game's catalog topUpMode
        }
        catch (IWinException e) when (e.Code == "WALLET_FROZEN")
        {
            ShowError("Your wallet is frozen pending a chargeback investigation.");
        }
        catch (IWinException e)
        {
            ShowError($"Purchase failed: {e.Code}");
        }
    }
}

Spend receipts (optional)

For games that have their own backend and want cryptographic proof a spend happened — instead of trusting the parent page's word — opt into a receipt JWT per spend. iWin signs it with KMS; your backend verifies against our published ES256 public key.

Most games don't need this. The parent page's { ok: true } response is already trustworthy because the parent is iwin.com. Receipts are a defense-in-depth layer for game backends that want to grant items off a verified server-side message rather than a browser-side claim.

1. Request a receipt

// In your game:
const result = await window.iwin.spend({
  sku: "gems_500",
  receipt: true,           // ← opt-in
});

// result.receipt is a compact JWT string:
//   "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IiJ9.<payload>.<signature>"
//
// Pass it to your game's backend (over HTTPS) for verification before
// you trust the player to have actually paid.
sendReceiptToYourBackend(result.receipt);

2. Verify it server-side

Fetch GET /v1/wallet/receipt-public-keyonce, cache the PEM, verify each receipt locally. Same pattern as iWin's DRM public-key flow.

// In your game's backend (Node + jose):
import { jwtVerify, importSPKI } from "jose";

// Fetch + cache iWin's public key once at startup:
const pkRes = await fetch("https://api.iwin.com/stage/v1/wallet/receipt-public-key");
const { publicKeyPem } = await pkRes.json();
const verifier = await importSPKI(publicKeyPem, "ES256");

// Per request:
app.post("/api/verify-receipt", async (req, res) => {
  try {
    const { payload } = await jwtVerify(req.body.receipt, verifier, {
      issuer: "iwin-wallet",
    });
    // payload = {
    //   iss: "iwin-wallet",
    //   sub: <player cognitoSub>,
    //   slug: "magic-match",
    //   sku: "gems_500",
    //   coins: 500,
    //   ledgerSk: "2026-05-28T19:00:00.000Z#abc-123",
    //   refType: "game",
    //   refId: "magic-match:gems_500",
    //   clientTxId: "run_42",
    //   iat: 1748466000,
    //   exp: 1748466300,
    // }
    grantItemInYourBackend(payload.sub, payload.sku, payload.coins);
    res.json({ ok: true });
  } catch (e) {
    res.status(400).json({ error: "invalid_receipt", detail: e.message });
  }
});

Receipt claims

Modal top-up (v1.1.0)

v1.0.0 reacted to iwin.openTopUp() by redirecting the parent page to /store. That kills the iframe — and your game session with it. v1.1.0 adds a second mode: render a modal over the game iframe, with content authored in Builder.io per game. When the player picks a coin pack, Stripe Checkout opens embedded inside the same modal (no new tab, no redirect). On payment success the modal detects the wallet credit and auto-closes, and your game resumes immediately.

1. Direct call

Game asks for the modal explicitly. The promise resolves when the modal closes (funded or dismissed) so you can branch your retry logic on the outcome.

// Explicit per-call request for the modal experience.
const result = await window.iwin.openTopUp({
  mode: "modal",      // ← "modal" | "redirect" | omit to use catalog default
  shortfall: 250,     // optional — surface in modal copy
});

// Resolves AFTER the player closes the modal (or it auto-closes on
// successful top-up). result shape:
//   { opened: true, mode: "modal",
//     funded: true|false,
//     newBalance?: <coins>,   // present when funded
//     dismissed?: true }       // present when the player closed
//                              // without paying
if (result.funded) {
  // Wallet was credited — retry the failed spend.
  await window.iwin.spend({ sku: "gems_500" });
}

2. Auto recovery macro

Pass autoTopUp to spend() and the SDK handles the INSUFFICIENT_FUNDS recovery flow for you. The same clientTxIdis reused on the retry so a network blip can't double-charge.

// One-call ergonomics: auto-open the modal on INSUFFICIENT_FUNDS
// and auto-retry the spend once the wallet is funded.
const result = await window.iwin.spend({
  sku: "gems_500",
  autoTopUp: {
    mode: "modal",     // "modal" | "redirect"
    retry: true,       // default — set false to fund without retrying
  },
});

// Three terminal states:
//   1. Spend went through first try → result is the normal spend result.
//   2. Spend insufficient → modal opened → player funded → SDK retried
//      the spend → result is the retry's spend result.
//   3. Player dismissed the modal → original INSUFFICIENT_FUNDS
//      rejection propagates to your catch block.
//
// With retry=false the second state surfaces as a resolved object:
//   { ok: false, code: "INSUFFICIENT_FUNDS",
//     toppedUp: true, newBalance: <coins> }
// — your game can decide whether to re-fire the spend itself.

Mode resolution

1. Per-call openTopUp({ mode: "modal" | "redirect" }) wins.
2. Otherwise the parent reads the per-game catalog topUpMode — admins set this at /admin/games/<slug>. Three values: "modal", "redirect", or unset.
3. Default — v1.0.0 behavior: router.push("/store").

Authoring the modal content

Modal contents are authored in Builder.io against the top-up-modal model. The fetch includes userAttributes: { game, shortfall } so editors can target a specific entry per game and per shortfall band. If no entry is published, the modal renders a built-in fallback with a single coin pack — fail-safe but boring.

Three custom Builder blocks are available to drop into the entry:

• Coin packages (top-up modal) — the 5-package grid. Each Buy button swaps the modal body to an embedded Stripe Checkout form (no new tab); the host page + your game iframe stay mounted throughout.
• Shortfall hint — dynamic copy with {shortfall} / {shortfallFormatted}placeholders, so you can author copy like "You need 250 more iCoins to continue."
• Dismiss button (top-up modal) — closes the modal with dismissed: true; same behavior as the X / Esc.

Modal content target: https://stage-prime.iwin.com/developers/icoin-sdk documents the SDK; Builder.io Studio (model top-up-modal) is where the in-game modal actually lives.

Canvas-hosted games (Unity WebGL)

If iWin renders your game as a <canvas> in our page chrome, you do NOT include the iwin-bridge-v1.js script tag. The host page installs window.iwin directly on the same document where your build runs. The API surface is byte-for-byte identical to the iframe SDK — same method names, same { ok: true, ... } response shape, same IwinError reject contract.

For Unity-WebGL builds the typical wiring is a .jslib file that bridges between your C# spend code and window.iwin.spend(...):

// In your Unity build's .jslib (PlayerInternal.jslib or similar):
mergeInto(LibraryManager.library, {
  IwinSpend: function(skuPtr, clientTxIdPtr, quotePtr) {
    var sku = UTF8ToString(skuPtr);
    var clientTxId = UTF8ToString(clientTxIdPtr);
    var quote = quotePtr ? UTF8ToString(quotePtr) : undefined;

    // window.iwin is installed by iWin's host page BEFORE your build's
    // jslib executes. No <script src=".../iwin-bridge-v1.js"> tag
    // needed for canvas-hosted games — that file is for iframe games.
    if (!window.iwin) {
      // Defensive: log and reject. If this ever fires, the iWin host
      // page didn't mount the bridge above the canvas (regression).
      console.error("window.iwin missing");
      return;
    }

    window.iwin.spend({ sku: sku, clientTxId: clientTxId, quote: quote })
      .then(function(r) {
        // Send the result back to C# via SendMessage.
        SendMessage("IwinController", "OnSpendSuccess", JSON.stringify(r));
      })
      .catch(function(err) {
        // err.code is one of the SDK error codes (INSUFFICIENT_FUNDS,
        // QUOTE_INVALID, etc.) — same contract as the iframe SDK.
        SendMessage("IwinController", "OnSpendError", err.code || "ERROR");
      });
  },

  IwinOpenTopUp: function(shortfall) {
    if (!window.iwin) return;
    window.iwin.openTopUp({ shortfall: shortfall, mode: "modal" })
      .then(function(r) {
        SendMessage("IwinController", "OnTopUpResolve", JSON.stringify(r));
      });
  },
});

Boot / identity handshake

Canvas builds get the player identity from window.iwin.getBoot() (equivalently the window.iwin.boot property), populated synchronously by the host page before your build boots. This is the canonical surface — new builds should read it instead of any game-specific global.

// Canvas builds read their player-identity payload from the canonical
// SDK surface BEFORE the first frame. iWin's host page populates this
// synchronously, before your build's code runs.
const boot = window.iwin.getBoot();   // or window.iwin.boot
// {
//   schema: "iwin.boot/1",
//   playerId,                 // signed-in Player ID, or a minted guest UUID
//   isGuest,                  // bool
//   platform: "webgl",
//   appVersion,               // your build's version string
//   email,                    // canvas/first-party only — omitted for iframe
//   loginProvider,            // canvas/first-party only ("google"/"email"/...)
//   cognitoToken,             // canvas/first-party only — raw Cognito ID token
//   previousGuestPlayerId,    // present once, for the guest→login merge
// }
startGameForPlayer(boot.playerId, { isGuest: boot.isGuest });

Optional handshake

The iframe SDK requires await iwin.ready()because the parent's iwin.hello arrives asynchronously over postMessage. Canvas-mode ready() resolves immediately with the same payload (user / balance / catalog / iapMode), so the call is optional — but recommended for symmetry with the iframe SDK if your build supports both transports.

// Optional: await the handshake before issuing the first spend. In
// canvas mode the handshake resolves synchronously (no postMessage
// round-trip), so this is essentially a guard against a misconfigured
// host page rather than a perf concern.
if (window.iwin && window.iwin.ready) {
  window.iwin.ready().then(function(payload) {
    // payload.user, payload.balance, payload.iapMode all populated.
  });
}

What's different in canvas mode

• No origin allowlist.Your build runs in iWin's window (same document), so the postMessage origin checks aren't applicable. There's no cross-document boundary to police.
• No <script> tag, no SHA-256 pin. The host page is the source of truth for window.iwin; you can't subresource-integrity-pin a function the host installs. The published iwin-bridge-v1.js integrity meta is for iframe games only.
• Top-up modal lives in iWin's UI.Even in fullscreen — the modal's portal mounts inside the fullscreen target so it stays visible. Your build doesn't need to handle the top-up UI itself.
• One window.iwin per page. If your build attempts to install its own window.iwin, iWin's will overwrite yours (and vice versa). Build-time guards on your side (only assigning when !window.iwin) are good hygiene.

API reference

Every method on window.iwin. All methods return promises; errors throw an IwinError with a .code field from the error-code table below.

window.iwin.ready() → Promise<HelloPayload>

Resolves when the parent's handshake message arrives. Always await this before calling other methods (the SDK queues until it resolves anyway, but ready() lets you confirm signed-in state, balance, and catalog at startup).

Returns: { sdkVersion, user, balance, catalog, gameSlug, iapMode, environment }

window.iwin.getBalance() → Promise<{ balance, currency }>

Reads the player's current iCoin balance. Returns null balance if the player isn't signed in.

window.iwin.getCatalog() → Promise<{ items, iapMode }>

Returns the SKU list for iWin-catalog mode games. For signed-quote mode games, items is empty — your game already knows its catalog.

Returns: { items: [{ sku, title, description, coins, imageUrl, sort }], iapMode: 'iwin-catalog' | 'quote' }

window.iwin.spend({ sku, clientTxId?, quote?, gameContext?, receipt?, autoTopUp? }) → Promise<SpendResult>

Charge the player's wallet for the given SKU. clientTxId auto-generates via crypto.randomUUID() if you omit it. For signed-quote mode games, pass the JWT your backend signed as `quote`. gameContext is opaque metadata stored in the ledger. Set `receipt: true` to get back a KMS-signed JWT proving the debit happened. v1.1.0: pass `autoTopUp: { mode, retry }` to auto-open the top-up flow on INSUFFICIENT_FUNDS and (default) retry the spend once funded; same clientTxId is reused on the retry — see Modal top-up section.

Returns: { ok: true, balance, ledgerSk, idempotent, sku, coins, receipt? } OR { ok: false, code, message } OR (with autoTopUp.retry=false) { ok: false, code: 'INSUFFICIENT_FUNDS', toppedUp, newBalance }

window.iwin.openTopUp({ shortfall?, mode? }) → Promise<TopUpResult>

Open the player's top-up flow. v1.0.0 just navigated the parent to /store. v1.1.0 adds `mode: 'modal' | 'redirect'`; 'modal' renders a Builder.io-authored dialog over your game iframe and holds this promise until the player closes it. Omit `mode` to use the per-game catalog default. Useful after an INSUFFICIENT_FUNDS error — or use the `autoTopUp` macro on spend() instead.

Returns: { opened: true, mode: 'modal' | 'redirect', funded: boolean | null, newBalance?, dismissed? }

window.iwin.requestLogin() → Promise<{ signedIn }>

Triggers the parent's sign-in modal. Returns the post-attempt signed-in state.

window.iwin.on(event, callback) → unsubscribe

Subscribe to parent push events: 'balance' (after spend/topup/refund), 'user' (sign-in/out), 'catalog' (admin republish), 'error'. Returns an unsubscribe function.

window.iwin.off(event, callback)

Manual unsubscribe (rarely needed; on() returns the same function).

Error codes

Every IwinError.code value, what causes it, and the recommended response.

Security model

Things you don't need to worry about — iWin handles them for you:

• Coin amounts are never trusted from the iframe.The parent looks up the price server-side from either the SKU catalog or a JWT signed by your registered public key. Even if your game's JavaScript is tampered with, the worst a player can do is request a different SKU.
• Origin allowlist on every postMessage. The parent only accepts messages from the games CDN (and any extra origins your game is registered for).
• Idempotent spends. If the network drops mid-spend and the game retries with the same clientTxId, the player is only charged once.
• Rate limit. Max 10 spends per minute per iframe instance. Rejects with RATE_LIMITED.
• Auth never crosses the iframe. The Cognito session token stays on the iWin parent; your iframe-hosted game never sees it. The boot/identity handshake is transport-redacted: iframe games get a playerId-only subset, while canvas-mode first-party builds (running inside iWin's own document) receive the full payload via window.iwin.getBoot().
• Frozen wallets. If a player has a chargeback in progress, spends reject with WALLET_FROZEN until resolved.

Versioning policy

The SDK URL includes the major version: iwin-bridge-v1.js. Within a major we only ship additive changes — any code written against v1.0.0 keeps working verbatim against v1.1.0+. Breaking changes ship as -v2.js. Your <script src> tag stays pinned to the version you tested against.

The handshake includes a sdkVersionfield; mismatch between the SDK and the parent's expected version is logged but doesn't block the bridge.

Getting your game listed

Third-party games hosted outside iWin's games CDN need a catalog row + an allowedOrigins entry. Email devs@iwin.com with your game URL and we'll provision the integration.