@playmos/sdk 0.3.1 → 0.3.3

package/README.md

@@ -2,7 +2,7 @@
 
 **🧪 Beta — Playmos SDK.** Runs on Base Sepolia **testnet**. The value-movement primitives (escrow / marketplace / transfer) are proven on-chain but **not yet production-hardened**, and nothing is on mainnet. Build and integrate freely against the sandbox; don't route real user funds yet.
 
-Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-game prize-pool entries (10%, 60/30/10), and agent economies. USD in, USDC on-chain — no crypto UX for your players.
+Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-game prize-pool entries (10%, 60/30/10), and **in-game economies** (player · NPC · agent commerce via `transfer()`). USD in, USDC on-chain — no crypto UX for your players.
 
 ## Install
 
@@ -27,21 +27,43 @@ The key comes wired to two demo games: `game_sandbox_iap` (IAP) and `game_sandbo
 
 ### In-app purchase — `pay()`
 
+<!-- snippet:pay -->
 ```ts
 import { Playmos } from "@playmos/sdk";
 
-// No wallet in the sandbox — Playmos signs the test payment for you.
+// 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", // the public sandbox IAP game
-  amount: "4.99",             // USD, as a string
+  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 user 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
+payment.txHash; // 0x…         — open on sepolia.basescan.org/tx/{txHash}
+```
+
+### Verify before you grant
+
+Grant items on a verified confirmation — never on the client `pay()` return alone.
+
+<!-- snippet:verify -->
+```ts
+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);
+}
 ```
 
 ### Skill-game entry — `enterRound()`
@@ -62,7 +84,7 @@ The base value-movement primitive: move USDC from one wallet to another with a c
 
 ```ts
 // NPC→NPC with a 5% fee (Playmos Town P2P). Requires sk_test_ + agents.createWallet first.
-// Full agent/Town walkthrough: see "Agent economies — the Playmos Town golden path" below.
+// Full walkthrough: see "In-game economies — the Playmos Town golden path" below.
 // Confirm: status === "settled" && txHash, or await playmos.transfers.wait(id) if settling.
 const t = await playmos.transfer({
   // `from` is OPTIONAL in the sandbox — omit it and the service uses its server-held signer wallet
@@ -109,9 +131,9 @@ Fields match the table above (`from` optional → defaults to the signer; `feeBp
 
 > Sandbox only (Phase 1a): `transfer` settles server-held NPC/agent wallets on Base Sepolia. The player-signed (EIP-3009) non-custodial path is Phase 1b.
 
-### Agent economies — the Playmos Town golden path
+### In-game economies — the Playmos Town golden path
 
-The NPCs in your game can hold and move USDC. This is the loop the [Playmos Town example](https://github.com/playmos-labs/playmos-sdk/blob/main/docs/examples/playmos-town-sdk.mjs) runs end to end: give each NPC a wallet, fund it, then move value with a per-call fee — P2P (5%), a monster bounty (0%), a shop sale (100%).
+**In-game economies** = commerce between **players, NPCs, and agents** (AI or scripted). The money primitive is **`transfer()`** (entity-agnostic); NPC/agent wallets use **`agents.*`** (API names unchanged). This is the loop the [Playmos Town example](https://github.com/playmos-labs/playmos-sdk/blob/main/docs/examples/playmos-town-sdk.mjs) runs end to end: give each NPC a wallet, fund it, then move value with a per-call fee — P2P (5%), a monster bounty (0%), a shop sale (100%). Proven on **Base Sepolia** (transfer layer) — not a claim that a full MMO product is shipped.
 
 **Agents need a SECRET test key — `sk_test_`, not `pk_test_`.** Assigning NPC wallets and transferring *from* an NPC are privileged, server-side actions, so they require an `sk_test_` key kept on **your backend** — not the public `pk_test_playmos_sandbox`. `pk_test_` runs the no-wallet `pay()` / `enterRound()` demos above; `sk_test_` unlocks `agents.*` and NPC-funded `transfer`.
 
@@ -168,15 +190,6 @@ The full 5-NPC walkthrough — create → fund → P2P / shop / bounty, each con
 PLAYMOS_SK_TEST=sk_test_… PLAYMOS_FEE_SINK=0x… node docs/examples/playmos-town-sdk.mjs
 ```
 
-### Verify before you grant
-
-Grant items on a verified confirmation — never on the client `pay()` return alone.
-
-```ts
-const result = await playmos.verify(payment.id); // on-chain read
-if (result.status === "confirmed") grantItem(result.playerId, result.sku);
-```
-
 ## Mock mode — offline, deterministic
 
 For CI and wiring checks, `mock: true` returns instant, deterministic results with **no network and no chain**. Results carry `mock: true` and use the real status union, so your handling code sees the exact production shape.
@@ -184,7 +197,7 @@ For CI and wiring checks, `mock: true` returns instant, deterministic results wi
 ```ts
 const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox", mock: true });
 const payment = await playmos.pay({
-  gameId: "game_sandbox_iap", sku: "gems_100", amount: "4.99", playerId: "player_abc",
+  gameId: "game_sandbox_iap", sku: "gems_100", amount: "0.99", playerId: "player_abc",
 });
 // instant — payment.status === "confirmed", payment.mock === true
 ```
@@ -229,4 +242,4 @@ The escrow/marketplace resolve endpoints (release/refund/confirm) return a deter
 
 ## Docs
 
-Full documentation — skill games, webhooks, gas, payouts, agent economies, and the REST API — at [playmos.io](https://playmos.io).
+Full documentation — skill games, webhooks, gas, payouts, in-game economies, and the REST API — at [playmos.io](https://playmos.io).