In-game purchases
Switched off on 0x.limoSell items in your game for the player's 0x balance with @0xlimo/iap — the launcher confirms, your server verifies the signed receipt and consumes units.
Sell items in your game, such as a skin or a pack of boosts, for the player's 0x balance. Your game can only ask. The 0x launcher shows the player the item, the price and their balance, and nothing is bought unless they press Confirm. Your game server then checks the signed receipt with 0x and grants the item. Your share is settled like a game sale.
Switched off on 0x.limo
In-game purchases are deployed but switched off on 0x.limo. While they are off, every in-game purchase route answers 404, the developer routes behind the items page answer 404 too, and in the launcher purchase() rejects with unavailable. You can integrate and unit-test against the SDK now (see Test it). This page will drop this callout when purchases go live.
Game ── purchase("boost-pack") ──► Launcher ── player confirms, paid from balance ──► receipt ──► Your server: verify, consume, grant#1. Define your items
Sign in at https://api.0x.limo/dev/items, pick your game and add items:
| Field | Rules |
|---|---|
sku | Your id for the item: ^[a-z0-9][a-z0-9._-]{0,63}$ (e.g. skin-gold). Unique per game, and never reused for another item. |
name, description | What the player sees in the confirm dialog: 1–80 and 0–500 characters. |
price | US cents, from 25 ($0.25) to 50000 ($500). |
kind | permanent: owned once (a skin, a level pack). consumable: bought in quantities and used up by your server (boosts, coins). |
max_per_player | Optional: at most this many (not refunded) per player. A permanent item is always 1. |
active | Inactive items can't be bought. Purchases already made stay valid. |
Once an item has been sold, it can't be deleted (it is deactivated instead) and its kind can't change. A new price applies to new purchases only.
On the same page, Create server key gives you the game's server key, 0xsk_<appid>_… (keys made before the rename to 0x start with x1sk_ and keep working). It is shown once, and creating a new one revokes the old one. Keep it on your game server only, never in the page.
The same operations over the API, with your 0x account's token:
| Method and path | |
|---|---|
GET /v1/dev/iap/apps | your games, with their items and server-key prefix |
GET /v1/dev/apps/{appid}/iap/items | items, server key {prefix, created_at}, fee_percent, min_price, max_price |
PUT /v1/dev/apps/{appid}/iap/items/{sku} | {name, description?, price, kind, max_per_player?, active?} → 201 new, 200 updated |
DELETE /v1/dev/apps/{appid}/iap/items/{sku} | {deleted: true}, or {deactivated: true} if it was sold |
POST /v1/dev/apps/{appid}/iap/server-key | {key, prefix, created_at} (shown once; revokes the previous key) |
GET /v1/dev/apps/{appid}/iap/purchases | the last 100 sales |
#2. Ask for a purchase (the page)
npm install @0xlimo/iap --@0xlimo:registry=https://0x.limo/npm/Sites built with the 0x CLI also get it as ./x1/iap.js next to the game, so you don't need a bundler.
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(); // names, prices, what the player owns
try {
const { purchase: p, receipt } = await purchase("boost-pack", { quantity: 1 });
socket.emit("redeem", receipt); // your server grants it (step 3)
} catch (e) {
if (e.code === "canceled") { /* the player said no */ }
else if (e.code === "insufficient_funds") { /* they can top up and try again */ }
}
}purchase() resolves only after the player has confirmed and paid. Quantity is 1–100 (always 1 for a permanent item). It rejects with an IapError whose code is one of:
code | Meaning |
|---|---|
canceled | the player closed the dialog |
insufficient_funds | not enough balance (the dialog offers a top-up) |
already_owned, limit_reached | a permanent item they have, or the per-player limit |
not_found | no such active item |
not_signed_in | a guest: purchases need an account |
unavailable, busy, failed, timeout | purchases off, another dialog open, or an error |
not_in_launcher | the page isn't running in the 0x launcher (use available() to hide your shop) |
inventory() lists what the player owns in your game: entitlements (permanent items: owned; consumables: available units) and purchases.
Why a game can't charge anyone: the game runs on its own origin inside the launcher's frame and talks to the launcher with postMessage. It never sees the player's account or token. The launcher decides which game is buying (the one it is playing, never a value taken from the message), so a game can only sell its own items, and only after the player presses Confirm. Only the launcher's origin may confirm a purchase.
#3. Grant it on your server
Never grant an item on the page's word. Check the receipt on your server.
IapServer.fromEnv() looks for the key in ZEROX_IAP_SERVER_KEY, then in the file named by ZEROX_IAP_SERVER_KEY_FILE, then in x1-iap.key in the server's directory. On 0x hosting, save the key as x1-iap.key next to server.mjs and run 0x deploy-server. 0x publish never puts a file of that name into your public site, but keep it out of git. On 0x hosting the host sets ZEROX_API_URL; elsewhere the API defaults to https://0x.limo.
import { IapServer } from "@0xlimo/iap/server";
const iap = IapServer.fromEnv();
socket.on("redeem", async (receipt, ack) => {
const v = await iap.verify({ receipt }); // online: knows about 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" }); // permanent
if (v.purchase.sku === "boost-pack") { // consumable: one unit per use
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 });
});| Call | HTTP (Authorization: Bearer 0xsk_…) | Answer |
|---|---|---|
verify({receipt}) or verify({purchase: "i_…"}) | POST /v1/iap/server/verify | {valid, purchase}. A receipt of another game, a bad signature or an unknown purchase → {valid: false, reason}. |
consume(id, {quantity, idempotencyKey}) | POST /v1/iap/server/consume (Idempotency-Key) | {purchase, consumed_now}. The same key returns the first answer, so a retry never uses a unit twice. 409 not_consumable, insufficient {remaining}, refunded. |
inventory(steamid) | GET /v1/iap/server/players/{steamid}/inventory | {steamid, appid, entitlements, purchases} |
The Orb Rush template does exactly this (examples/arena/server.mjs and shop.js in the SDK): a gold runner (permanent) and +10-point boosts (consumable).
#Receipts offline
A receipt is x1r1.<payload>.<signature>. The payload is base64url JSON:
{"v":1,"kid":"…","id":"i_…","a":4000123,"s":"<steamid>","k":"boost-pack","t":"consumable","q":1,"p":99,"c":"USD","iat":1792000000}It is signed with Ed25519 by 0x over the ASCII bytes x1-iap-receipt-v1. followed by the payload part. The public keys (the current and previous ones, by kid) are at GET https://api.0x.limo/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);Offline verification proves the purchase was made and paid. It can't know about a later refund or about units already used. Granting permanent items with it is fine, but grant consumables by consuming online.
#Players' side
These routes are for the launcher, but you may see them in its traffic. All of them need a signed-in account; a guest gets 403 account_required.
| Method and path | |
|---|---|
GET /v1/apps/{appid}/iap/items | active items with what the player owns, and the balance |
POST /v1/apps/{appid}/iap/intents {sku, quantity?} | an intent that lives 10 minutes: {intent, balance, can_afford, missing} |
POST /v1/iap/intents/{id}/confirm | the launcher's Confirm → 201 {purchase, receipt, wallet}. Confirming again → 200 with replayed: true. 409 insufficient_funds keeps the intent open (top up and confirm again), 410 expired. |
POST /v1/iap/intents/{id}/cancel | |
GET /v1/me/iap/purchases?appid= | the player's purchases, newest first |
GET /v1/me/iap/purchases/{id}/receipt | the receipt again, for a game that lost it |
#Money and refunds
Each purchase is a sale from the balance, split like a game sale: the platform fee and your share, which goes to your account through settlement. A refund by 0x support returns the whole price to the player's balance and revokes the item: a permanent item is no longer owned, and a consumable's remaining units can no longer be consumed. Your share is taken back. Players can't refund a purchase themselves.
Steam-compatible games
ISteamInventory::StartPurchase in the Steamworks compatibility layer is refused for priced items while payments are on ("purchases need the player's confirmation in the 0x launcher"). To sell items through 0x, use @0xlimo/iap.
#Test it
- Outside the launcher,
available()isfalse, so your game runs without a shop, as it should. - Unit-test your server with fakes:
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). - Once purchases are on: inside the launcher, buy your own items from a test account that has a balance. The receipts are real, and the server key works the same.
