@playmos/sdk 0.3.0 → 0.3.2

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).

package/dist/{chunk-B7SHFZYY.js → chunk-TMBBEGIF.js}

@@ -56,7 +56,16 @@ var ConfigError = class extends PlaymosError {
     super("config", message, detail);
   }
 };
+var NothingToWithdrawError = class extends PlaymosError {
+  constructor(detail) {
+    super(
+      "nothing_to_withdraw",
+      "Nothing to withdraw \u2014 this wallet has no credited prize balance on this PrizePool (round not settled for them, or already claimed).",
+      detail
+    );
+  }
+};
 
-export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, PaymentFailedError, PlaymosError, WalletConnectionError };
-//# sourceMappingURL=chunk-B7SHFZYY.js.map
-//# sourceMappingURL=chunk-B7SHFZYY.js.map
+export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError };
+//# sourceMappingURL=chunk-TMBBEGIF.js.map
+//# sourceMappingURL=chunk-TMBBEGIF.js.map

package/dist/chunk-TMBBEGIF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";AAmBO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAKtC,WAAA,CAAY,IAAA,EAAwB,OAAA,EAAiB,MAAA,EAAkC;AACrF,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,OAAO,GAAA,CAAA,MAAA,CAAW,IAAA;AACvB,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAEd,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,GAAA,CAAA,MAAA,CAAW,SAAS,CAAA;AAAA,EAClD;AACF;AAGO,IAAM,kBAAA,GAAN,cAAiC,YAAA,CAAa;AAAA,EACnD,YAAY,MAAA,EAAiB;AAC3B,IAAA,KAAA;AAAA,MACE,gBAAA;AAAA,MACA,CAAA,gBAAA,EAAmB,IAAA,CAAK,SAAA,CAAU,MAAM,CAAC,CAAA,6EAAA,CAAA;AAAA,MACzC,EAAE,MAAA;AAAO,KACX;AAAA,EACF;AACF;AAGO,IAAM,iBAAA,GAAN,cAAgC,YAAA,CAAa;AAAA,EAClD,YAAY,KAAA,EAAe;AACzB,IAAA,KAAA,CAAM,iBAAiB,CAAA,yBAAA,EAA4B,KAAK,CAAA,EAAA,CAAA,EAAM,EAAE,OAAO,CAAA;AAAA,EACzE;AACF;AAGO,IAAM,oBAAA,GAAN,cAAmC,YAAA,CAAa;AAAA,EACrD,YAAY,MAAA,EAAkC;AAC5C,IAAA,KAAA;AAAA,MACE,kBAAA;AAAA,MACA,CAAA,oHAAA,CAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AACF;AAGO,IAAM,qBAAA,GAAN,cAAoC,YAAA,CAAa;AAAA,EACtD,WAAA,CAAY,OAAA,GAAU,wCAAA,EAA0C,MAAA,EAAkC;AAChG,IAAA,KAAA,CAAM,mBAAA,EAAqB,SAAS,MAAM,CAAA;AAAA,EAC5C;AACF;AAGO,IAAM,kBAAA,GAAN,cAAiC,YAAA,CAAa;AAAA,EACnD,WAAA,CAAY,OAAA,GAAU,wCAAA,EAA0C,MAAA,EAAkC;AAChG,IAAA,KAAA,CAAM,gBAAA,EAAkB,SAAS,MAAM,CAAA;AAAA,EACzC;AACF;AAGO,IAAM,SAAA,GAAN,cAAwB,YAAA,CAAa;AAAA,EAC1C,WAAA,CAAY,OAAA,GAAU,6BAAA,EAA+B,MAAA,EAAkC;AACrF,IAAA,KAAA,CAAM,MAAA,EAAQ,SAAS,MAAM,CAAA;AAAA,EAC/B;AACF;AAGO,IAAM,QAAA,GAAN,cAAuB,YAAA,CAAa;AAAA,EACzC,WAAA,CAAY,SAAiB,MAAA,EAAkC;AAC7D,IAAA,KAAA,CAAM,WAAA,EAAa,SAAS,MAAM,CAAA;AAAA,EACpC;AACF;AAGO,IAAM,WAAA,GAAN,cAA0B,YAAA,CAAa;AAAA,EAC5C,WAAA,CAAY,SAAiB,MAAA,EAAkC;AAC7D,IAAA,KAAA,CAAM,QAAA,EAAU,SAAS,MAAM,CAAA;AAAA,EACjC;AACF;AAMO,IAAM,sBAAA,GAAN,cAAqC,YAAA,CAAa;AAAA,EACvD,YAAY,MAAA,EAAkC;AAC5C,IAAA,KAAA;AAAA,MACE,qBAAA;AAAA,MACA,0IAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AACF","file":"chunk-TMBBEGIF.js","sourcesContent":["/**\n * Typed, actionable errors — the Stripe bar (spec §11).\n *\n * Every error carries a stable machine-readable `code` and is thrown at the\n * EARLIEST possible layer: input errors fire client-side before any network or\n * chain call, so a studio never pays gas to discover a typo.\n */\n\nexport type PlaymosErrorCode =\n  | \"invalid_amount\"\n  | \"missing_field\"\n  | \"insufficient_gas\"\n  | \"wallet_connection\"\n  | \"payment_failed\"\n  | \"auth\"\n  | \"api_error\"\n  | \"config\"\n  | \"nothing_to_withdraw\";\n\nexport class PlaymosError extends Error {\n  readonly code: PlaymosErrorCode;\n  /** Optional machine context (e.g. the offending field, the http status). */\n  readonly detail?: Record<string, unknown>;\n\n  constructor(code: PlaymosErrorCode, message: string, detail?: Record<string, unknown>) {\n    super(message);\n    this.name = new.target.name;\n    this.code = code;\n    this.detail = detail;\n    // Restore prototype chain for `instanceof` across transpile targets.\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** amount ≤ 0, non-numeric, empty, or more than 2 decimal places. */\nexport class InvalidAmountError extends PlaymosError {\n  constructor(amount: unknown) {\n    super(\n      \"invalid_amount\",\n      `Invalid amount: ${JSON.stringify(amount)}. Provide a positive USD decimal string with at most 2 decimals, e.g. \"4.99\".`,\n      { amount },\n    );\n  }\n}\n\n/** A required field (sku, playerId, gameId, roundId, agentId…) was empty. */\nexport class MissingFieldError extends PlaymosError {\n  constructor(field: string) {\n    super(\"missing_field\", `Missing required field: \"${field}\".`, { field });\n  }\n}\n\n/** gas mode \"player\" and the player's ETH is too low to cover gas (pre-check, §7). */\nexport class InsufficientGasError extends PlaymosError {\n  constructor(detail?: Record<string, unknown>) {\n    super(\n      \"insufficient_gas\",\n      \"The player's wallet has too little ETH to pay gas. Ask them to add a little ETH, or switch to gas.mode: \\\"sponsored\\\".\",\n      detail,\n    );\n  }\n}\n\n/** The player closed or failed the wallet sheet, or no provider is available. */\nexport class WalletConnectionError extends PlaymosError {\n  constructor(message = \"Could not connect the player's wallet.\", detail?: Record<string, unknown>) {\n    super(\"wallet_connection\", message, detail);\n  }\n}\n\n/** The on-chain settlement reverted, was cancelled, or timed out. */\nexport class PaymentFailedError extends PlaymosError {\n  constructor(message = \"The on-chain payment did not complete.\", detail?: Record<string, unknown>) {\n    super(\"payment_failed\", message, detail);\n  }\n}\n\n/** Bad, missing, or wrong-environment API key (e.g. a pk_test_ key on a live route). */\nexport class AuthError extends PlaymosError {\n  constructor(message = \"Invalid or missing API key.\", detail?: Record<string, unknown>) {\n    super(\"auth\", message, detail);\n  }\n}\n\n/** The Playmos service returned a non-2xx we don't have a more specific error for. */\nexport class ApiError extends PlaymosError {\n  constructor(message: string, detail?: Record<string, unknown>) {\n    super(\"api_error\", message, detail);\n  }\n}\n\n/** SDK misconfiguration (e.g. a missing contract address for on-chain mode). */\nexport class ConfigError extends PlaymosError {\n  constructor(message: string, detail?: Record<string, unknown>) {\n    super(\"config\", message, detail);\n  }\n}\n\n/**\n * PrizePool.withdraw() would transfer 0 (NothingToWithdraw) — pre-check or on-chain.\n * Issue #41: typed surface so studios never show a raw contract revert to winners.\n */\nexport class NothingToWithdrawError extends PlaymosError {\n  constructor(detail?: Record<string, unknown>) {\n    super(\n      \"nothing_to_withdraw\",\n      \"Nothing to withdraw — this wallet has no credited prize balance on this PrizePool (round not settled for them, or already claimed).\",\n      detail,\n    );\n  }\n}\n"]}

package/dist/{errors-BVESr920.d.cts → errors-DMtMpbR6.d.cts}

@@ -398,6 +398,16 @@ interface Payment {
      * server's `hasEntered`.
      */
     identity?: string;
+    /**
+     * Prize-pool entries only (issue #41): the PrizePool contract this entry hit.
+     * Keep it — winners need it later to read claimable balance and call `withdraw()`.
+     */
+    prizePoolAddress?: `0x${string}`;
+    /**
+     * Prize-pool entries only (issue #41): the exact on-chain round key string used
+     * at enter (may equal `roundId`). Surface it so claim flow doesn't re-derive.
+     */
+    roundKey?: string;
     /** True only when produced by the labeled `mock: true` helper. */
     mock?: boolean;
 }
@@ -469,15 +479,42 @@ interface RoundState {
     roundKey: string;
     status: RoundStatus;
     entryAmount: string;
-    /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). */
+    /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). Issue #42. */
     pool: string | null;
-    /** Entrant count from chain after reconcile; **`null` until reconciled**. */
+    /** Entrant count from chain after reconcile; **`null` until reconciled**. Issue #42. */
     entrants: number | null;
     payout: PayoutRule;
     closeAt?: string;
     openTxHash?: `0x${string}`;
     lockTxHash?: `0x${string}`;
     settleTxHash?: `0x${string}`;
+    /**
+     * PrizePool contract for this round's game (issue #41). Needed to claim winnings.
+     * `null` only if the game has no contract address configured.
+     */
+    prizePoolAddress?: `0x${string}` | null;
+}
+/** What `rounds.prize({ … })` returns — claimable pull-payment balance (issue #41). */
+interface PrizeBalance {
+    roundId: string;
+    prizePoolAddress: `0x${string}`;
+    /** Winner wallet whose claimable balance was read. */
+    wallet: `0x${string}`;
+    /** USD decimal string (full micro precision). */
+    claimable: string;
+    /** Integer micro-USDC. */
+    claimableMicro: string;
+    /** Round status when known from `rounds.get` (optional). */
+    roundStatus?: RoundStatus;
+}
+/** What `rounds.withdraw({ … })` returns after a successful claim (issue #41). */
+interface WithdrawResult {
+    prizePoolAddress: `0x${string}`;
+    /** Amount withdrawn in USD (from pre-check claimable; on-chain transfer matches). */
+    amount: string;
+    amountMicro: string;
+    txHash?: `0x${string}`;
+    status: "confirmed" | "failed" | "pending";
 }
 interface RoundSettleInput {
     roundId: string;
@@ -509,7 +546,7 @@ interface SettleRoundResult {
  * EARLIEST possible layer: input errors fire client-side before any network or
  * chain call, so a studio never pays gas to discover a typo.
  */
-type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config";
+type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config" | "nothing_to_withdraw";
 declare class PlaymosError extends Error {
     readonly code: PlaymosErrorCode;
     /** Optional machine context (e.g. the offending field, the http status). */
@@ -548,5 +585,12 @@ declare class ApiError extends PlaymosError {
 declare class ConfigError extends PlaymosError {
     constructor(message: string, detail?: Record<string, unknown>);
 }
+/**
+ * PrizePool.withdraw() would transfer 0 (NothingToWithdraw) — pre-check or on-chain.
+ * Issue #41: typed surface so studios never show a raw contract revert to winners.
+ */
+declare class NothingToWithdrawError extends PlaymosError {
+    constructor(detail?: Record<string, unknown>);
+}
 
-export { type AgentWallet as A, type PaymentStatus as B, ConfigError as C, type PayoutRule as D, type EscrowHoldInput as E, PlaymosError as F, type GasConfig as G, type PlaymosErrorCode as H, InsufficientGasError as I, type RetryOptions as J, type RoundStatus as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type WalletConfig as O, type PlaymosConfig as P, WalletConnectionError as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type WalletConnector as U, type VerifyResult as V, type WebhookEvent as W, type WebhookEventType as X, type RoundState as a, type RoundSettleInput as b, type AgentFundResult as c, type EscrowHoldResult as d, type EscrowResolveResult as e, type MarketplaceSaleResult as f, type MarketplaceGetResult as g, type PayInput as h, type Payment as i, type EnterRoundInput as j, type TransferReconcile as k, type WaitOptions as l, type TransferInput as m, type TransferConfirmOptions as n, type AgentEconomyConfig as o, ApiError as p, AuthError as q, type ContractConfig as r, type Eip1193Provider as s, type GasMode as t, InvalidAmountError as u, type ListingStatus as v, type MarketplaceItem as w, type MarketplaceSale as x, MissingFieldError as y, PaymentFailedError as z };
+export { type AgentWallet as A, MissingFieldError as B, ConfigError as C, NothingToWithdrawError as D, type EscrowHoldInput as E, PaymentFailedError as F, type GasConfig as G, type PaymentStatus as H, InsufficientGasError as I, type PayoutRule as J, PlaymosError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type PlaymosErrorCode as O, type PlaymosConfig as P, type RetryOptions as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type RoundStatus as U, type VerifyResult as V, type WebhookEvent as W, type WalletConfig as X, WalletConnectionError as Y, type WalletConnector as Z, type WebhookEventType as _, type RoundState as a, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentFundResult as e, type EscrowHoldResult as f, type EscrowResolveResult as g, type MarketplaceSaleResult as h, type MarketplaceGetResult as i, type PayInput as j, type Payment as k, type EnterRoundInput as l, type TransferReconcile as m, type WaitOptions as n, type TransferInput as o, type TransferConfirmOptions as p, type AgentEconomyConfig as q, ApiError as r, AuthError as s, type ContractConfig as t, type Eip1193Provider as u, type GasMode as v, InvalidAmountError as w, type ListingStatus as x, type MarketplaceItem as y, type MarketplaceSale as z };

package/dist/{errors-BVESr920.d.ts → errors-DMtMpbR6.d.ts}

@@ -398,6 +398,16 @@ interface Payment {
      * server's `hasEntered`.
      */
     identity?: string;
+    /**
+     * Prize-pool entries only (issue #41): the PrizePool contract this entry hit.
+     * Keep it — winners need it later to read claimable balance and call `withdraw()`.
+     */
+    prizePoolAddress?: `0x${string}`;
+    /**
+     * Prize-pool entries only (issue #41): the exact on-chain round key string used
+     * at enter (may equal `roundId`). Surface it so claim flow doesn't re-derive.
+     */
+    roundKey?: string;
     /** True only when produced by the labeled `mock: true` helper. */
     mock?: boolean;
 }
@@ -469,15 +479,42 @@ interface RoundState {
     roundKey: string;
     status: RoundStatus;
     entryAmount: string;
-    /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). */
+    /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). Issue #42. */
     pool: string | null;
-    /** Entrant count from chain after reconcile; **`null` until reconciled**. */
+    /** Entrant count from chain after reconcile; **`null` until reconciled**. Issue #42. */
     entrants: number | null;
     payout: PayoutRule;
     closeAt?: string;
     openTxHash?: `0x${string}`;
     lockTxHash?: `0x${string}`;
     settleTxHash?: `0x${string}`;
+    /**
+     * PrizePool contract for this round's game (issue #41). Needed to claim winnings.
+     * `null` only if the game has no contract address configured.
+     */
+    prizePoolAddress?: `0x${string}` | null;
+}
+/** What `rounds.prize({ … })` returns — claimable pull-payment balance (issue #41). */
+interface PrizeBalance {
+    roundId: string;
+    prizePoolAddress: `0x${string}`;
+    /** Winner wallet whose claimable balance was read. */
+    wallet: `0x${string}`;
+    /** USD decimal string (full micro precision). */
+    claimable: string;
+    /** Integer micro-USDC. */
+    claimableMicro: string;
+    /** Round status when known from `rounds.get` (optional). */
+    roundStatus?: RoundStatus;
+}
+/** What `rounds.withdraw({ … })` returns after a successful claim (issue #41). */
+interface WithdrawResult {
+    prizePoolAddress: `0x${string}`;
+    /** Amount withdrawn in USD (from pre-check claimable; on-chain transfer matches). */
+    amount: string;
+    amountMicro: string;
+    txHash?: `0x${string}`;
+    status: "confirmed" | "failed" | "pending";
 }
 interface RoundSettleInput {
     roundId: string;
@@ -509,7 +546,7 @@ interface SettleRoundResult {
  * EARLIEST possible layer: input errors fire client-side before any network or
  * chain call, so a studio never pays gas to discover a typo.
  */
-type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config";
+type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config" | "nothing_to_withdraw";
 declare class PlaymosError extends Error {
     readonly code: PlaymosErrorCode;
     /** Optional machine context (e.g. the offending field, the http status). */
@@ -548,5 +585,12 @@ declare class ApiError extends PlaymosError {
 declare class ConfigError extends PlaymosError {
     constructor(message: string, detail?: Record<string, unknown>);
 }
+/**
+ * PrizePool.withdraw() would transfer 0 (NothingToWithdraw) — pre-check or on-chain.
+ * Issue #41: typed surface so studios never show a raw contract revert to winners.
+ */
+declare class NothingToWithdrawError extends PlaymosError {
+    constructor(detail?: Record<string, unknown>);
+}
 
-export { type AgentWallet as A, type PaymentStatus as B, ConfigError as C, type PayoutRule as D, type EscrowHoldInput as E, PlaymosError as F, type GasConfig as G, type PlaymosErrorCode as H, InsufficientGasError as I, type RetryOptions as J, type RoundStatus as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type WalletConfig as O, type PlaymosConfig as P, WalletConnectionError as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type WalletConnector as U, type VerifyResult as V, type WebhookEvent as W, type WebhookEventType as X, type RoundState as a, type RoundSettleInput as b, type AgentFundResult as c, type EscrowHoldResult as d, type EscrowResolveResult as e, type MarketplaceSaleResult as f, type MarketplaceGetResult as g, type PayInput as h, type Payment as i, type EnterRoundInput as j, type TransferReconcile as k, type WaitOptions as l, type TransferInput as m, type TransferConfirmOptions as n, type AgentEconomyConfig as o, ApiError as p, AuthError as q, type ContractConfig as r, type Eip1193Provider as s, type GasMode as t, InvalidAmountError as u, type ListingStatus as v, type MarketplaceItem as w, type MarketplaceSale as x, MissingFieldError as y, PaymentFailedError as z };
+export { type AgentWallet as A, MissingFieldError as B, ConfigError as C, NothingToWithdrawError as D, type EscrowHoldInput as E, PaymentFailedError as F, type GasConfig as G, type PaymentStatus as H, InsufficientGasError as I, type PayoutRule as J, PlaymosError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type PlaymosErrorCode as O, type PlaymosConfig as P, type RetryOptions as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type RoundStatus as U, type VerifyResult as V, type WebhookEvent as W, type WalletConfig as X, WalletConnectionError as Y, type WalletConnector as Z, type WebhookEventType as _, type RoundState as a, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentFundResult as e, type EscrowHoldResult as f, type EscrowResolveResult as g, type MarketplaceSaleResult as h, type MarketplaceGetResult as i, type PayInput as j, type Payment as k, type EnterRoundInput as l, type TransferReconcile as m, type WaitOptions as n, type TransferInput as o, type TransferConfirmOptions as p, type AgentEconomyConfig as q, ApiError as r, AuthError as s, type ContractConfig as t, type Eip1193Provider as u, type GasMode as v, InvalidAmountError as w, type ListingStatus as x, type MarketplaceItem as y, type MarketplaceSale as z };