Payments for games

Test-USDC payments for games on Base Sepolia — 1% IAP — try the sandbox: no wallet, no signup. Beta · testnet only (fake money, real on-chain ids). Mainnet / pk_live_ is not available yet.

Start here — IAP smoke (Path A)

First track: sell an item. Complete T0-IAP in one scroll. Skill entry is the parallel track next — Start here · Skill. Same install · same public key. Node 18+.

1. Install

$ npm i @playmos/sdk

1b. Preflight — sandbox settle READY?

Server-settle needs a funded sandbox signer. Before debugging a 504:

curl -sS https://api.sandbox.playmos.io/health | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const p=JSON.parse(d).capabilities.payments;console.log(p.serverSettle);console.log(JSON.stringify(p.signerBalance));})"

2. Take a payment (client / sandbox — T0 smoke)

Public key — safe in demos and host pages. No wallet required on the sandbox server-settle path.

import { Playmos } from "@playmos/sdk";

// Public sandbox key — client-safe, like Stripe's pk_test_.
// No wallet needed: Playmos server-settles the test payment for you.
const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });

const payment = await playmos.pay({
  gameId: "game_sandbox_iap", // public sandbox IAP game — include it (this key spans IAP + skill)
  amount: "0.99",             // USD string — sandbox server-settle cap $1.00/request
  sku: "gems_500",            // your product id
  playerId: "player_abc",     // your opaque user id
});

payment.id;     // "pay_…"     — real, server-issued (ULID)
payment.status; // "confirmed" — real, on Base Sepolia
payment.txHash; // 0x…         — open on sepolia.basescan.org/tx/{txHash}

2b. Confirm on-chain (sandbox — same public key)

On the sandbox, the public key can read a payment by id. Call verify() with the same client to see confirmed land — this is the win that sells the product. Still never grant an item from the client alone.

// Same public client as step 2 — publishable keys may read GET /v1/payments/:id
const result = await playmos.verify(payment.id);
// Poll until status === "confirmed" (sandbox settle can be async ~3–6s)
console.log(result.status); // "confirmed"
// That is T0 complete: pay_… + confirmed + BaseScan. Do NOT grant yet from the client.

3. Grant on your server (T1 — secret key)

Never grant on the client pay() return alone. For production-shaped integrations, call verify() on your backend with a secret sk_test_ (see Keys), then grant. Get a secret: curl -sS -X POST https://api.sandbox.playmos.io/v1/keys -H 'content-type: application/json' -d '{"label":"my-studio"}' — self-serve, no email. Keep the secret server-only.

import { Playmos } from "@playmos/sdk";

// Your server — the secret key lives here, never in a client bundle.
const server = new Playmos({ apiKey: process.env.PLAYMOS_SECRET! }); // sk_test_…

const result = await server.verify(payment.id); // on-chain read — idempotent, safe to retry

// Terminal success is exactly "confirmed" (IAP + entries) — not "settled" / "succeeded".
if (result.status === "confirmed") {
  grantItem(result.playerId, result.sku);
}

$ mkdir playmos-t0 && cd playmos-t0 && npm init -y && npm i @playmos/sdk
$ cat > t0.mjs <<'EOF'
import { Playmos } from "@playmos/sdk";
const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });
const payment = await playmos.pay({
  gameId: "game_sandbox_iap", amount: "0.99", sku: "gems_500",
  playerId: "player_" + Date.now(),
});
let result = await playmos.verify(payment.id);
for (let i = 0; i < 30 && result.status !== "confirmed"; i++) {
  await new Promise(r => setTimeout(r, 500));
  result = await playmos.verify(payment.id);
}
console.log({ id: payment.id, status: result.status, tx: payment.txHash });
EOF
$ node t0.mjs

Start here — skill entry smoke (Path B)

Second track: player pays into a skill prize pool with enterRound(). Same public sandbox key as IAP — no wallet. Proves the entry money path on Base Sepolia. Not a full multi-player contest; not operator open/lock/settle (that needs your self-serve sk_test_ — see Advanced under Path B).

1. Same install (skip if you already ran IAP)

$ npm i @playmos/sdk

Preflight sandbox READY the same way as IAP (see above). Skill entries also spend the sandbox settle budget.

2. Enter a round (client / sandbox — T0 skill)

Public key · no wallet · one paid entry. Skill is pay-per-play — re-running creates a new entry when you use a new idempotencyKey. Reusing the same key returns the same entry (not a second charge).

import { Playmos } from "@playmos/sdk";

const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });
const playerId = "player_" + Date.now();
const idempotencyKey = "entry-" + playerId + "-docs-smoke";

const entry = await playmos.enterRound({
  gameId: "game_sandbox_skill", // public sandbox skill game
  // Unique round per run so entry price matches amount (shared rounds pin first open price)
  roundId: "docs-smoke-" + playerId,
  amount: "1.00",               // USD string — sandbox cap $1.00/request
  playerId,
  idempotencyKey,               // same key re-run = same entry; new key = new paid entry
});

// entry.id is entry_… (skill entry — not pay_…; IAP uses pay_). Confirm on-chain with the same public key:
let result = await playmos.verify(entry.id);
// Poll if still pending until status === "confirmed" (~3–6s)
// Terminal success for entry = "confirmed" — not "settled" (settled is the round-lifecycle word after operator settle)
console.log(result.status); // "confirmed"
console.log({ id: entry.id, tx: entry.txHash });

const result = await server.verify(payment.id); // safe to retry
if (result.status === "confirmed") {
  await grantItemOnce({ key: payment.id, playerId: result.playerId, sku: result.sku });
}

3. What skill T0 does not include

rounds.open / lock / settle / operator payout on-chain need your self-serve sk_test_ (mint via POST /v1/keys) — not the public key. Public pk_ on live /v1/rounds* gets a clean 403 (not an outage). Self-serve full lifecycle for a cold studio = mock: true — open→enter→lock→settle→prize→withdraw offline (no network). Pass wallet on mock withdraw (live uses the connected provider). Mock is not live money and may still diverge on edge cases — see mock callout under Keys. Full multi-entrant + hub kit: Path B · advanced.

$ cat > t0-skill.mjs <<'EOF'
import { Playmos } from "@playmos/sdk";
const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });
const playerId = "player_" + Date.now();
const entry = await playmos.enterRound({
  gameId: "game_sandbox_skill",
  roundId: "docs-smoke-" + playerId,
  amount: "1.00",
  playerId,
  idempotencyKey: "entry-" + playerId,
});
let result = await playmos.verify(entry.id);
for (let i = 0; i < 30 && result.status !== "confirmed"; i++) {
  await new Promise(r => setTimeout(r, 500));
  result = await playmos.verify(entry.id);
}
console.log({ id: entry.id, status: result.status, tx: entry.txHash });
EOF
$ node t0-skill.mjs

Three fee models, one SDK

Pick a path

Most studios: Path A only. What is the player / client doing?

Your stack

Pick how you ship. Default: Web / JS + Start here. Engines use a host page or system browser.

Keys & environments

One table. Client-safe vs server-only — learn this once. Caps: sandbox server-settle $1 / request · 5 / min · $20 / day.

Status words: IAP / contest entry success = confirmed. Transfer success = settled. Do not mix them.

Path A · Standard game — in-app purchases

The default path for any studio selling items. The player taps once, USDC settles on-chain, and you keep 99% — flat 1% to Playmos, no ~30% app-store tax. Canonical install + pay() + verify: Start here (do not re-copy a drifted snippet).

Sandbox server-settle cap $1 / request (and rate limits) — full table: Keys & environments. Demo amounts use "0.99".

The player experience — one tap

You get this by calling pay() — you don't build any wallet UI. Your player sees a checkout they already know: dollars, one confirm, no crypto. USDC settles on Base in the background, and you keep 99%.

await playmos.pay({
  sku:      "gems_100",
  amount:   "0.99",   // USD
  playerId,
});

How it works — you keep 99%

Four steps. Playmos operates a small service and an on-chain contract; it never holds your money. The 99% is in your wallet the instant a purchase confirms.

Next: grant only after verify / webhook — same rule as Start here.

pay() reference

const payment = await playmos.pay(input); — Input:

Returns Payment:

Amounts are strings on purpose — "0.99", never 0.99 — so floating-point rounding can never corrupt a price.

Path B · Skill-based games — stablecoin prizes

Player entry smoke is parallel to IAP. First hour: Start here · Skill (enterRound → verify with public key). Below: modes, gameIds, hub kit pins, and the advanced multi-entrant operator lifecycle.

Smoke test vs multi-entrant pool read first

Smoke test — one enterRound sandbox only

Proves the entry money path on Base Sepolia. Not a multi-player contest. Public sandbox key (see Keys) — no wallet required.

import { Playmos } from "@playmos/sdk";

const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });

// Recommended: hold across outer re-runs (#252). SDK auto-retries 504 inside one call.
// Omit → NEW key per call → full script re-run can double-enter.
const idempotencyKey = "entry-player_abc-bmtest:T1-smoke-1";

// SMOKE: one entry. Pass a roundKey to share an on-chain round; omit it for a one-shot.
const entry = await playmos.enterRound({
  gameId: "game_sandbox_skill",
  roundId: "5m-5944009",     // off-chain window id
  roundKey: "bmtest:T1",     // since #230, honored on no-wallet server-settle as the on-chain key
  amount: "1.00",
  playerId: "player_abc",
  idempotencyKey,             // recommended: hold across outer re-runs (#252)
});
// No-wallet server-settle is ASYNC (#221): status starts "pending"/"created" and confirms in ~3-6s.
const confirmed = await playmos.verify(entry.id); // poll → "confirmed"; 60/30/10 split on-chain

Advanced · multi-entrant skill lifecycle Playmos-operated

Only for contests that need a real pooled round. Requires the own-wallet (client-signed) entry path so players join the exact roundId you opened. Operator calls use your self-serve secret on your server (never the browser) — see Keys.

B2 · Game-hub kit (pin roundKey + identity)

If your server opens rounds and verifies entries — it reads hasEntered(roundKey, identity) on-chain (the pattern the Playmos game-hub kit uses) — then the on-chain entry must carry your exact roundKey and identity, or your server won't recognize it. Two ways:

Option 1 — the drop-in (recommended). entryProvider({ gameId }) returns a { connect, payEntry } that satisfies a game kit's payment-provider interface:

gameConfig.paymentProvider = playmos.entryProvider({ gameId });

Option 2 — call enterRound() yourself with the exact values:

const wallet   = await playmos.connect();
const identity = `${wallet}#${nonce}`;
const roundKey = `${onchainRoundId}:${tier}`;
// Hold across retries — omit mints a NEW key per call (double-enter on 504 re-run) (#252)
const idempotencyKey = `entry-${identity}-${roundKey}`;

const entry = await playmos.enterRound({
  gameId, roundId, amount: "4.99", playerId: identity,
  roundKey,
  identity,
  idempotencyKey,
});

B3 · Game-server loop (confirm → session → submit → leaderboard)

enterRound / entryProvider only moves USDC on-chain. A real skill game still needs your game server (Playmos game-hub kit) to admit the player, issue a ranked session, accept a score, and show the board. Wrong pool/round on the server → empty field / $0 pool (#237, #245).

// After SDK enterRound is confirmed:
const HUB = process.env.GAME_HUB_URL;

await fetch(`${HUB}/entry/confirm`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ identity, wallet, roundId: onchainRoundId, tier: "T1" }),
});

const session = await fetch(`${HUB}/session`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ identity, wallet, roundId: onchainRoundId, tier: "T1" }),
}).then((r) => r.json());

await fetch(`${HUB}/submit`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ identity, log: runLog }),
});

const board = await fetch(`${HUB}/leaderboard/${onchainRoundId}/T1`).then((r) => r.json());

Full lifecycle — open → enter → lock → settle → withdraw

enterRound() is one step of five. The round lifecycle — open, lock, settle — is driven from your backend with your secret key, but the on-chain rounds are opened/locked/settled by the Playmos service's OPERATOR_ROLE key against the Playmos-operated PrizePool (the V1 first-party, 60/30/10 model — see the V1 scope note at the top of this section). Never put a secret key in the browser.

// Operator client — SECRET key, backend only.
const ops = new Playmos({ apiKey: process.env.PLAYMOS_SECRET }); // sk_test_…

// 1) OPEN with YOUR payout rule (no scores on-chain)
await ops.rounds.open({
  gameId: "game_sandbox_skill",
  roundId: "round-42",
  entryAmount: "4.99",
  payout: { kind: "top-n", splitsBps: [5000, 3000, 2000] }, // top 3 · sum = 10000
});

// 2) Players ENTER on the OWN-WALLET path (not no-wallet smoke) → pool grows, 10% fee at entry

// 3) Your server ranks ENTRANT wallets (best-first). Scores stay yours.

// 4) LOCK — closes entries, splits the pot 60/30 (this pool / next seed)
await ops.rounds.lock({ roundId: "round-42" });

// 5) SETTLE — ranking (SDK applies your rule) or exact winners amounts
const result = await ops.rounds.settle({
  roundId: "round-42",
  results: { ranking: ["0xaaa…", "0xbbb…", "0xccc…"] },
});
// result → { roundId, txHash, poolPaid, winners:[{wallet,amount}], status:"settled" }
// Note: settle status "settled" is the ROUND lifecycle word — IAP/entry success remains "confirmed"

Payout rules for open / settle: { kind:"winner-take-all" } · { kind:"top-n", splitsBps:[…] } (bps must sum to 10000) · { kind:"custom", amounts:["1.50", …] }.

Pure helper (positional only — do not pass an object as the first arg): computePayout(pool: bigint, ranking: 0x…[], rule). Example: computePayout(150_000n, ["0xaaa…"], { kind: "winner-take-all" }) — pool is micro-USDC bigint.

Then: your server issues the play

The SDK settles the payment on-chain — it does not run your game. After a confirmed entry, your server still owns the ranked-ticket / session logic: confirm the entry (call verify(entry.id) — an on-chain read — or handle the payment.confirmed webhook), then issue your single-use session ticket. verify() re-reads the chain to prove the entry is real; it does not mint your game's ticket — that logic stays yours.

The 60/30/10 split

Each entry is split on-chain, automatically. Players get an effective 90% back, smoothed across rounds.

Pay-per-play & best score

• Pay-per-play: every paid attempt is a fresh entry that grows the pool; replay as many times as you like to chase a higher score. The best score per wallet counts on the leaderboard.
• Free Practice mode has no stakes and no contract call — always on for grinding.
• The pool is trustless escrow — the stakes live in the contract until settlement. settle credits each winner inside the contract; each winner then calls withdraw() to collect (pull-payment). No one custodies players’ money.

Path C · In-game economies testnet beta

In-game economies = commerce between any actors that can hold a wallet — player ↔ player, player ↔ NPC, NPC ↔ NPC (AI-driven or scripted). Not an “AI-only” product: the money primitive is entity-agnostic transfer(); wallet assignment stays on agents.* (API names unchanged).

Pick one money model per product action. Do not use transfer() to fake an IAP receipt, and do not use pay() for NPC↔NPC commerce.

Town golden path — createWallet → fund → transfer

The first thing to run for Path C. Playmos Town: five NPC wallets trading real test USDC on Base Sepolia. Fee is per-call feeBps (0 = bounty, 500 = 5% P2P, 10000 = 100% shop).

import { Playmos } from "@playmos/sdk";

// Server only — see Keys for sk_test_ vs agents sandbox exception.
const playmos = new Playmos({ apiKey: "sk_test_playmos_agents_sandbox" });

// 1) Give an NPC a wallet (pure — never moves money). Idempotent.
await playmos.agents.createWallet({ agentId: "npc_pico_miner" });

// 2) Fund it from the sandbox treasury.
await playmos.agents.fund({ agentId: "npc_pico_miner", amount: "0.50" });

// 3) Actor → actor with per-call fee (P2P 5%).
const t = await playmos.transfer({
  from: "npc_pico_miner",
  to:   "npc_bruna_blacksmith", // 0x address OR agentId
  amount: "0.10",
  feeBps: 500,                // 0 = bounty · 500 = 5% · 10000 = 100% shop
  feeSink: "0xYourTreasury",  // optional on sandbox; required on live
});

// 4) Terminal success for transfer = "settled" (not IAP "confirmed").
const done = t.status === "settling" ? await playmos.transfers.wait(t.id) : t;
console.log(done.status, done.txHash); // settled + 0x…

Custody: the organization launching the game owns its agents' wallets. Playmos assigns wallets and settles transfers but never holds the keys. Production key custody is post-V1. NPCs are gasless on the sandbox path (EIP-3009; relay pays gas).

• Status: transfer success = settled (IAP/entry = confirmed).
• Fee: per-call feeBps 0–10000; feeSink optional on sandbox, required on live.
• from/to: 0x address or agentId.
• Confirm: transfers.wait(id) or transfer(input, { confirm: true }).
• Runnable: PLAYMOS_SK_TEST=… PLAYMOS_FEE_SINK=0x… node docs/examples/playmos-town-sdk.mjs

Advanced · transfer reference, escrow, marketplace testnet

Optional value-movement surfaces on top of the Town path. Still Base Sepolia only — not a claim that a full marketplace product is shipped.

Path D · x402-shaped HTTP payments testnet

Not Start here. Default studios still use IAP. Path D is for HTTP clients and agents that pay for a request over an x402-shaped envelope (headers + PaymentRequirement) into the same settlement core as transfer().

Buyer · playmos.x402.pay (≤15 lines)

pay({ payTo, amount }) wraps POST /v1/x402/challenges then /settle. USD decimal in the SDK; wire amount is atomic ("0.10" → "100000"). Status word: settled (not IAP confirmed).

import { Playmos } from "@playmos/sdk";

// x402 V1: Base Sepolia + sk_test_ only (not pk_test_, not mainnet).
const playmos = new Playmos({
  apiKey: process.env.PLAYMOS_SK!, // sk_test_…
  network: "base-sepolia",
});

// pay() = POST /v1/x402/challenges → settle (server-signer in sandbox).
// Fee terms are server-authoritative at mint — do not "trust" client fee fields.
const result = await playmos.x402.pay({
  payTo: "0x2222222222222222222222222222222222222222",
  amount: "0.10", // USD decimal — wire maxAmountRequired is atomic "100000"
  feeBps: 0,
});

result.status; // "settled"  (not IAP "confirmed")
result.txHash; // 0x… — sepolia.basescan.org/tx/{txHash}

Seller · 402 response helper (no x402.verify in V1)

There is no playmos.x402.verify(req). Settle only after a server-minted challenge (playmos.x402.challenge / pay). Local createX402Challenge is response-shape only — fulfill of that local requirement always 400s.

import { createPaymentRequirement, createX402Challenge } from "@playmos/sdk";

// Build a Playmos requirement, then a 402 body + PAYMENT-REQUIRED header.
const requirement = createPaymentRequirement({
  payTo: "0x2222222222222222222222222222222222222222",
  amount: "0.10",
  network: "base-sepolia",
});
const challenge = createX402Challenge(requirement, { feeBps: 0 });

// Express-shaped example:
// res.status(challenge.status).set(challenge.headers).json(challenge.body);
// This LOCAL challenge is response-shape only. To settle on Playmos rails, mint a SERVER
// challenge first: playmos.x402.challenge({ payTo, amount }) → then
// playmos.x402.fulfill(result.requirement, { mode }). (playmos.x402.pay does both.)
void challenge.status;  // 402
void challenge.headers; // { "PAYMENT-REQUIRED": "(base64)", "Content-Type": "application/json" }
void challenge.body.paymentRequired.maxAmountRequired; // "100000" atomic USDC

Core · Verify a payment, then grant

Shared by every path — an IAP pay(), a skill-game enterRound(), or any confirmation you act on. Reads the on-chain settlement so it’s the source of truth. Canonical snippet: Start here · step 3.

import { Playmos } from "@playmos/sdk";

// Your server — the secret key lives here, never in a client bundle.
const server = new Playmos({ apiKey: process.env.PLAYMOS_SECRET! }); // sk_test_…

const result = await server.verify(payment.id); // on-chain read — idempotent, safe to retry

// Terminal success is exactly "confirmed" (IAP + entries) — not "settled" / "succeeded".
if (result.status === "confirmed") {
  grantItem(result.playerId, result.sku);
}

Core · Webhooks

Let Playmos push you the truth instead of polling. Verify the signature, then act. Signature verification is server-only — import from @playmos/sdk/server (uses Node crypto; not in the browser entry).

import express from "express";
import { verifyWebhook } from "@playmos/sdk/server"; // server-only — uses Node crypto

const app = express();

// express.raw is required: the signature is HMAC'd over the exact raw bytes.
app.post("/playmos/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyWebhook(               // throws if the signature is bad
    req.body,
    req.headers["x-playmos-signature"],
    process.env.PLAYMOS_WEBHOOK_SECRET,
  );

  if (event.type === "payment.confirmed") {
    grantItem(event.data.playerId, event.data.sku);
  }
  res.sendStatus(200);
});

At-least-once delivery, up to 5 exponential-backoff retries. Events are idempotent by data.id — dedup so a retry never grants twice.

Core · Gas & player experience

// you sponsor gas (recommended)
new Playmos({
  apiKey: "pk_live_xxx",
  gas: { mode: "sponsored", paymasterUrl: PAYMASTER_URL }
});

// or the player pays gas — with a pre-check
new Playmos({ apiKey: "pk_live_xxx", gas: { mode: "player" } });

Core · Test mode & testnet

Your key picks the environment — pk_test → Base Sepolia + the Playmos test service, available today. pk_live → Base mainnet is the intended promotion path (swap the key, no code change) but is coming soon, not live yet: nothing is deployed on mainnet, and production is gated on an audit + legal/compliance + a hardening pass. Build on testnet now; don't route real user funds. For offline CI, new Playmos({ apiKey, mock: true }) returns instant deterministic results with no network (clearly labeled — never confuse it with test mode, which is real).

# Circle faucet → https://faucet.circle.com
# select "Base Sepolia" (the dropdown resets each visit — reselect it),
# paste your address → 20 test USDC / 2h. Grab a little test ETH for gas too.

Mock mode — validate your integration instantly

new Playmos({ apiKey, mock: true }) lets you validate your integration wiring instantly — no wallet, no network, no crypto. Calls return deterministic results synchronously, so you can prove your code path end-to-end (in a unit test or on first run) before you ever touch the chain. Results carry mock: true / onchain: false and use the real status union, so your handling code exercises the exact shape production returns. Always check mock === true / onchain: false so a mock success is never mistaken for real USDC moving. (npm installs ship built dist. If you develop against a private monorepo checkout, rebuild sdk after source changes.)

const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox", mock: true });

const payment = await playmos.pay({
  gameId: "game_sandbox_iap", sku: "gems_100", amount: "0.99", playerId: "player_abc"
});
// instant, deterministic — payment.status === "confirmed", payment.mock === true

Core · Getting paid — your choice at onboarding

When you onboard, you make one choice: how do you want your revenue? No wrong answer, and you can change it anytime with one setting.

// Option 1 — pay me in stablecoin, to my wallet (default)
await playmos.payouts.setMode("usdc");

// Option 2 — pay me in dollars, to my bank
const { url } = await playmos.payouts.createOnboardingLink();
// send the studio owner to `url` to complete KYC with Bridge
await playmos.payouts.setMode("fiat");

Core · Errors

Every error is typed and actionable, thrown as early as the SDK can tell.

The other nine all extend PlaymosError, so catch (e) { if (e instanceof PlaymosError) … } catches every SDK-thrown error — and nothing else.

Core · REST API & other languages

Everything the SDK does is REST. Here’s the one call every backend makes — verify a payment — in five languages.

curl https://api.sandbox.playmos.io/v1/payments/$ID \
  -H "Authorization: Bearer $PLAYMOS_SECRET"
# → { "status":"confirmed", "amount":"0.99", "fee":"0.01", "net":"0.98", "txHash":"0x…" }

// Prefer SDK (npm i @playmos/sdk@0.3.10) — raw fetch also fine
import { Playmos } from "@playmos/sdk";
const playmos = new Playmos({ apiKey: process.env.PLAYMOS_SECRET }); // sk_test_… server only
const p = await playmos.verify(id);
if (p.status === "confirmed") grantItem(p.playerId, p.sku);

import os, requests
r = requests.get(
    f"https://api.sandbox.playmos.io/v1/payments/{payment_id}",
    headers={"Authorization": f"Bearer {os.environ['PLAYMOS_SECRET']}"},
)
p = r.json()
if p["status"] == "confirmed": grant_item(p["playerId"], p["sku"])

req, _ := http.NewRequest("GET", "https://api.sandbox.playmos.io/v1/payments/"+id, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("PLAYMOS_SECRET"))
resp, _ := http.DefaultClient.Do(req)
var p Payment
json.NewDecoder(resp.Body).Decode(&p)
if p.Status == "confirmed" { grantItem(p.PlayerID, p.SKU) }

// Playmos.Sdk 0.1.1-preview — SERVER only (secrets stay here)
// dotnet add package Playmos.Sdk --version 0.1.1-preview
using Playmos;

var playmos = new PlaymosClient(new PlaymosClientOptions {
  ApiKey = Environment.GetEnvironmentVariable("PLAYMOS_SECRET") // sk_test_…
});
var p = await playmos.VerifyAsync(id);
// Terminal success is exactly "confirmed"
if (p.IsConfirmed) GrantItem(p.PlayerId, p.Sku);

Unity & C# — ship a paid item in your WebGL game in 3 steps

Pay → verify → grant. One golden path for Unity / .NET. No wallet ceremony in the happy path. Testnet only (Base Sepolia).

Install

Third-party path does not require Unity package samples. Host page loads npm @playmos/sdk; Unity only needs a bridge to the host (your own thin glue). Unity 2022.3 LTS recommended when you do embed WebGL.

Three steps

// GameObject name must be "PlaymosBridge"
using Playmos.Unity;

public void OnBuyClicked() =>
    GetComponent<PlaymosBridge>().Pay("0.99", "gems_500");

// SendMessage: GameObject "PlaymosBridge" · method "OnPlaymosPayment"
// PaymentDto = flat strings { id, status } only — JsonUtility-safe
public void OnPlaymosPayment(string json) {
  var p = JsonUtility.FromJson<PaymentDto>(json);
  if (!string.IsNullOrEmpty(p.id)) RequestServerGrant(p.id);
}

using Playmos;

var playmos = new PlaymosClient(new PlaymosClientOptions {
  ApiKey = Environment.GetEnvironmentVariable("PLAYMOS_SECRET")
});
var payment = await playmos.VerifyAsync(paymentId);
if (payment.IsConfirmed) GrantItem(payment.PlayerId, payment.Sku);

Sequence

Player → Unity → host JS → Playmos API → Base Sepolia → callback → your server verifies → grant.

Security

IAP grant vs contest withdraw

Endpoints

Surfaces — honest install matrix (Base Sepolia)

Every surface below is testnet-only. Registry “live” only when a stranger can install it. Public for third parties today: npm @playmos/sdk, NuGet Playmos.Sdk, PyPI playmos. Unity/Godot/Unreal/Go source installs are private monorepo (not offered on the stranger path) — use the JS host + server-grant pattern instead. Unreal ≠ WebGL.

JS / Node @playmos/sdk — L2 + browser (npm live)

The reference implementation. Live on npm as 0.3.10. Browser player sheet · Node game server · host page for Unity/Godot · pay page for Unreal. Same security and caps as every other surface.

import { Playmos } from "@playmos/sdk";

// Public sandbox key — client-safe, like Stripe's pk_test_.
// No wallet needed: Playmos server-settles the test payment for you.
const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });

const payment = await playmos.pay({
  gameId: "game_sandbox_iap", // public sandbox IAP game — include it (this key spans IAP + skill)
  amount: "0.99",             // USD string — sandbox server-settle cap $1.00/request
  sku: "gems_500",            // your product id
  playerId: "player_abc",     // your opaque user id
});

payment.id;     // "pay_…"     — real, server-issued (ULID)
payment.status; // "confirmed" — real, on Base Sepolia
payment.txHash; // 0x…         — open on sepolia.basescan.org/tx/{txHash}

import { Playmos } from "@playmos/sdk";

// Your server — the secret key lives here, never in a client bundle.
const server = new Playmos({ apiKey: process.env.PLAYMOS_SECRET! }); // sk_test_…

const result = await server.verify(payment.id); // on-chain read — idempotent, safe to retry

// Terminal success is exactly "confirmed" (IAP + entries) — not "settled" / "succeeded".
if (result.status === "confirmed") {
  grantItem(result.playerId, result.sku);
}

Full reference for pay / verify / webhooks / agents is Path A–C above. This card is the surface entry point that matches the C# / Python / Go cards.

C# Playmos.Sdk — L2 server REST

Live on NuGet as 0.1.1-preview. Server only for secrets. Pairs with Unity WebGL client above.

dotnet add package Playmos.Sdk --version 0.1.1-preview

using Playmos;
var playmos = new PlaymosClient(new PlaymosClientOptions {
  ApiKey = Environment.GetEnvironmentVariable("PLAYMOS_SECRET") // sk_test_…
});
var p = await playmos.VerifyAsync(paymentId);
if (p.IsConfirmed) GrantItem(p.PlayerId, p.Sku);

Server-settle pay uses pk_test_ only (PlaymosClient.ForSandboxPublicKey().PayAsync(...)). Use NuGet package Playmos.Sdk (public). Monorepo path is private-source only.

Godot HTML5 — L3 host bridge

0.1.0-preview · engine addon is private monorepo only (not a public registry). Third-party path: Godot 4.2+ Web export + host page with public npm @playmos/sdk + server grant.

Playmos.pay("0.99", "gems_500")
# → request_server_grant(payment_id) — never grant in the client

Unreal — system browser + server-mediated grant

0.1.0-preview · Unreal plugin is private monorepo only (not Fab). This is not a WebGL shell. Third-party path: open the system browser to a host that uses public npm @playmos/sdk; the game server verifies and grants.

Pay->Configure(Cfg);  // PayPageBaseUrl + GameServerBaseUrl (URLs must resolve)
Pay->StartIap(TEXT("0.99"), TEXT("gems_500"), TEXT("player_1"));
// Deep link returnUrl is optional sugar — never the sole grant channel
// WebView (CEF) = follow-up, not MVP

Python playmos — L2 server REST (live on PyPI)

0.1.0a1 is live on PyPI (Trusted Publishing; install-proven). Primary install: pip install playmos==0.1.0a1. Optional monorepo dev: cd python && pip install -e ".[dev]".

pip install playmos==0.1.0a1

from playmos import PlaymosClient
client = PlaymosClient(api_key=os.environ["PLAYMOS_SECRET"])
p = client.verify(payment_id)
if p.is_confirmed: grant_item(p.player_id, p.sku)

Go playmos — L2 server REST

0.1.0-alpha.1 · not a public Go module for third parties yet. Prefer npm @playmos/sdk for public integrations.

// Go import path requires private monorepo access — prefer @playmos/sdk (npm) publicly
import "playmos"

c, _ := playmos.New(playmos.Options{APIKey: os.Getenv("PLAYMOS_SECRET")})
p, _ := c.Verify(ctx, paymentID)
if p.IsConfirmed() { grantItem(p.PlayerID, p.SKU) }

Stdlib only — no go-ethereum. Pay rejects secret keys at runtime (use pk_test_ for server-settle).