0xDocs 0x.limo

Docs / JavaScript SDK

@0xlimo/iap

Switched off on 0x.limo

In-game purchases for web games on 0x. The launcher sells an item when the player confirms, and your server verifies the signed receipt and consumes consumables.

Switched off on 0x.limo

In-game purchases are deployed but switched off (SG_IAP is not set on production). While they are off, every /v1/iap/* route answers 404, and the launcher answers purchase requests with unavailable. Your shop code can ship now: gate it on available() and on a working items() call.

Players pay from their 0x balance. Your game never charges anyone. It asks its parent window (the 0x launcher) to sell an item. The launcher shows the item, the price and the player's balance, and nothing is bought unless the player presses Confirm. The answer carries a signed receipt, and your game server checks it before granting anything.

Registry version: 0.1.0. Typings ship with the package. The generated API reference lists every type and function.

ImportRuns inExports
@0xlimo/iap (also @0xlimo/iap/client, or ./x1/iap.js on CLI-built sites)the pageavailable, purchase, items, inventory, createIapClient, IapError
@0xlimo/iap/serveryour game server (Node 18+)IapServer, verifyReceipt, fetchKeys, decodeReceipt, publicKeyFromHex, hasServerKey, KEY_FILE, IapError
bash
npm install @0xlimo/iap --@0xlimo:registry=https://0x.limo/npm/

#1. Define items

Sign in on https://0x.limo/dev/items, pick your game and add items:

FieldRules
skuyour id for the item: lowercase letters, digits, ., _, - (e.g. skin-gold). Never reuse one.
name, descriptionshown in the confirm dialog
priceUS dollars, in cents, from $0.25 to $500
kindpermanent is owned once (a skin). consumable is bought in quantities and used up by your server (boosts).
limit per playeroptional cap

An item that has sold cannot be deleted, only deactivated. Its kind cannot change, and a new price applies only to new purchases. Create server key on the same page gives you the app's server key (0xsk_<appid>_…), shown once. Keep it on the server and never put it in the page.

#2. Ask for a purchase (the page)

js
import { available, items, purchase, inventory } from "./x1/iap.js";   // or "@0xlimo/iap"

if (available()) {                                   // only inside the 0x launcher
  const { items: onSale, balanceUsd } = await items();
  try {
    const { purchase: p, receipt } = await purchase("boost-pack", { quantity: 1 });
    socket.emit("redeem", receipt);                  // your server grants it
  } catch (e) {
    if (e.code === "canceled") { /* the player said no */ }
    else if (e.code === "insufficient_funds") { /* the dialog offered a top-up */ }
  }
}

purchase() resolves only after the player confirmed and paid. It waits up to 15 minutes, because the dialog may stay open while the player tops up. items() and inventory() time out after 15 s.

The protocol is postMessage to window.parent:

text
game -> launcher  {x1: "iap", v: 1, type: "purchase" | "items" | "inventory", rid, sku?, quantity?}
launcher -> game  {x1: "iap", v: 1, type: "result" | "items" | "inventory", rid, ok, ...}

The client accepts answers only from window.parent and only with a pending rid. createIapClient({launcherOrigin: "https://0x.limo"}) also pins the origin.

#Error codes (IapError.code)

codemeaning
canceledthe player closed the dialog
insufficient_fundsnot enough balance (the dialog offers a top-up)
already_owneda permanent item the player already has
limit_reachedthe per-player limit
not_foundno such active item
not_signed_ina guest: purchases need an account
unavailablepurchases are off
busyanother dialog is open
failedany other error
timeoutno answer in time
not_in_launcherthe page is not inside the 0x launcher (hide the shop: available())

#3. Grant on your server

js
import { IapServer } from "@0xlimo/iap/server";

const iap = IapServer.fromEnv();      // ZEROX_IAP_SERVER_KEY | ZEROX_IAP_SERVER_KEY_FILE | ./x1-iap.key
socket.on("redeem", async (receipt, ack) => {
  const v = await iap.verify({ receipt });             // online: knows refunds and consumption
  if (!v.valid || v.purchase.status === "refunded") return ack({ ok: false });
  if (v.purchase.sku === "skin-gold") return ack({ ok: true, skin: "gold" });
  if (v.purchase.sku === "boost-pack") {
    const c = await iap.consume(v.purchase.id, {
      quantity: 1,
      idempotencyKey: `${v.purchase.id}:${v.purchase.consumed}`,
    });
    if (c.consumed_now === 1) return ack({ ok: true, boost: true, left: c.purchase.remaining });
  }
  ack({ ok: false });
});
MethodEndpointReturns
verify({receipt}) or verify({purchase: "i_…"})POST /v1/iap/server/verify{valid, purchase: {id, appid, steamid, sku, kind, quantity, consumed, remaining, status}}; a receipt for another game is not valid
consume(idOrReceipt, {quantity, idempotencyKey})POST /v1/iap/server/consume (also sends an Idempotency-Key header){purchase, consumed_now}; the same key returns the first answer. 409 with insufficient, not_consumable or refunded.
inventory(steamid)GET /v1/iap/server/players/<steamid>/inventory{steamid, appid, entitlements, purchases}
verifyOffline(receipt)GET /v1/iap/keys (cached)as verifyReceipt; refetches the keys once on an unknown kid
  • The API base is api, else ZEROX_API_URL (which x1-host sets), else ZEROX_API, else https://0x.limo.
  • On 0x hosting, save the key as x1-iap.key next to your server and run 0x deploy-server. 0x publish never puts a file with that name into the public site.
  • Server-side failures throw IapError with code (the API's error, or http_<status>), status and body.

#Receipts offline

A receipt is x1r1.<b64url(payload)>.<b64url(signature)>. The payload is JSON: {"v":1, "kid", "id", "a": appid, "s": steamid, "k": sku, "t": kind, "q": quantity, "p": cents, "c": "USD", "iat"}. 0x signs it with Ed25519 over the ASCII bytes x1-iap-receipt-v1. followed by the payload part. The public keys are at GET /v1/iap/keys.

js
import { fetchKeys, verifyReceipt } from "@0xlimo/iap/server";

const keys = await fetchKeys("https://0x.limo");     // cached 10 minutes
const r = verifyReceipt(receipt, { keys, appid: 4000123 });
if (r.valid) console.log(r.purchase.steamid, r.purchase.sku, r.purchase.quantity);
else console.log(r.reason);   // "not an x1r1 receipt", "bad signature", "unknown key …", "receipt of app …"

Offline verification proves that the purchase was made and paid. It cannot know about a later refund, or about units already used. Grant consumables by consuming online.

#Testing

  • Outside the launcher, available() is false, so the game runs with no shop.
  • Unit-test your server with a fake. new IapServer({api, key, fetch}) takes any fetch, and verifyReceipt takes any key list, so you can sign test receipts with your own Ed25519 key. The SDK's packages/iap/test shows how.
  • See also Monetization for pricing, revenue share and payouts.