@0xlimo/iap
Switched off on 0x.limoIn-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.
| Import | Runs in | Exports |
|---|---|---|
@0xlimo/iap (also @0xlimo/iap/client, or ./x1/iap.js on CLI-built sites) | the page | available, purchase, items, inventory, createIapClient, IapError |
@0xlimo/iap/server | your game server (Node 18+) | IapServer, verifyReceipt, fetchKeys, decodeReceipt, publicKeyFromHex, hasServerKey, KEY_FILE, IapError |
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:
| Field | Rules |
|---|---|
sku | your id for the item: lowercase letters, digits, ., _, - (e.g. skin-gold). Never reuse one. |
| name, description | shown in the confirm dialog |
| price | US dollars, in cents, from $0.25 to $500 |
| kind | permanent is owned once (a skin). consumable is bought in quantities and used up by your server (boosts). |
| limit per player | optional 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)
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:
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)
| code | meaning |
|---|---|
canceled | the player closed the dialog |
insufficient_funds | not enough balance (the dialog offers a top-up) |
already_owned | a permanent item the player already has |
limit_reached | the per-player limit |
not_found | no such active item |
not_signed_in | a guest: purchases need an account |
unavailable | purchases are off |
busy | another dialog is open |
failed | any other error |
timeout | no answer in time |
not_in_launcher | the page is not inside the 0x launcher (hide the shop: available()) |
#3. Grant on your server
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 });
});| Method | Endpoint | Returns |
|---|---|---|
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, elseZEROX_API_URL(which x1-host sets), elseZEROX_API, elsehttps://0x.limo. - On 0x hosting, save the key as
x1-iap.keynext to your server and run0x deploy-server.0x publishnever puts a file with that name into the public site. - Server-side failures throw
IapErrorwithcode(the API'serror, orhttp_<status>),statusandbody.
#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.
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()isfalse, so the game runs with no shop. - Unit-test your server with a fake.
new IapServer({api, key, fetch})takes anyfetch, andverifyReceipttakes any key list, so you can sign test receipts with your own Ed25519 key. The SDK'spackages/iap/testshows how. - See also Monetization for pricing, revenue share and payouts.
