@playmos/sdk 0.3.0 → 0.3.1

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 };

package/dist/index.cjs

@@ -2,6 +2,8 @@
 
 var viem = require('viem');
 
+// src/client.ts
+
 // src/errors.ts
 var PlaymosError = class extends Error {
   constructor(code, message, detail) {
@@ -60,6 +62,15 @@ 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
+    );
+  }
+};
 
 // src/config.ts
 var CHAIN_ID = {
@@ -462,6 +473,13 @@ var prizePoolAbi = [
     ],
     outputs: [{ type: "bool" }]
   },
+  {
+    type: "function",
+    name: "withdrawable",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ type: "uint256" }]
+  },
   {
     type: "function",
     name: "withdraw",
@@ -549,6 +567,14 @@ function buildEntryCalls(args) {
     { to: args.prizePool, data: enterData }
   ];
 }
+function buildWithdrawCall(prizePool) {
+  const data = viem.encodeFunctionData({
+    abi: prizePoolAbi,
+    functionName: "withdraw",
+    args: []
+  });
+  return { to: prizePool, data };
+}
 
 // src/mock.ts
 var MOCK_TX = "0x000000000000000000000000000000000000000000000000000000000000mock";
@@ -593,6 +619,9 @@ function mockEntryPayment(args) {
     },
     gameId: args.gameId,
     roundId: args.roundId,
+    roundKey: args.roundId,
+    // Deterministic mock pool address so claim-flow unit tests can assert shape (#41).
+    prizePoolAddress: "0x0000000000000000000000000000000000000001",
     playerId: args.playerId,
     txHash: MOCK_TX,
     chain: args.chain,
@@ -705,6 +734,112 @@ var Playmos = class {
           `/rounds/${encodeURIComponent(input.roundId)}`
         );
         return round;
+      },
+      /**
+       * Read a wallet's **claimable** prize balance for a round (issue #41).
+       * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
+       * back to a direct eth_call when `prizePoolAddress` is supplied and no wallet
+       * connector is needed for the read path… actually uses service first, then
+       * on-chain via the player's provider if the service is unavailable.
+       */
+      prize: async (input) => {
+        requireField(input?.roundId, "roundId");
+        const wallet = requireAddressField(input?.wallet, "wallet");
+        try {
+          const res = await this.http.get(
+            `/rounds/${encodeURIComponent(input.roundId)}/prize?wallet=${encodeURIComponent(wallet)}`
+          );
+          return res.prize;
+        } catch (e) {
+          if (!input.prizePoolAddress && !(e instanceof ApiError)) throw e;
+          if (!input.prizePoolAddress) throw e;
+        }
+        const prizePoolAddress = requireAddressField(input.prizePoolAddress, "prizePoolAddress");
+        const claimableMicro = await this.readWithdrawable(prizePoolAddress, wallet);
+        return {
+          roundId: input.roundId,
+          prizePoolAddress,
+          wallet,
+          claimable: formatMicroToUsd(claimableMicro),
+          claimableMicro: claimableMicro.toString()
+        };
+      },
+      /**
+       * Winner **claim** — call PrizePool.withdraw() from the player's wallet (issue #41).
+       * Pull-payment: credits from settle live in `withdrawable[msg.sender]`. No approve needed.
+       * Pass either `prizePoolAddress` (from enterRound / rounds.get) or `roundId` (service resolves).
+       */
+      withdraw: async (input) => {
+        if (this.config.mock) {
+          return {
+            prizePoolAddress: input.prizePoolAddress ?? "0x0000000000000000000000000000000000000001",
+            amount: "0.00",
+            amountMicro: "0",
+            txHash: "0x000000000000000000000000000000000000000000000000000000000000mock",
+            status: "confirmed"
+          };
+        }
+        let prizePool = input.prizePoolAddress ? requireAddressField(input.prizePoolAddress, "prizePoolAddress") : void 0;
+        if (!prizePool) {
+          requireField(input?.roundId, "roundId");
+          const round = await this.rounds.get({ roundId: input.roundId });
+          if (!round.prizePoolAddress) {
+            throw new ConfigError(
+              "rounds.get did not return prizePoolAddress \u2014 pass prizePoolAddress from enterRound or configure contracts.prizePool"
+            );
+          }
+          prizePool = round.prizePoolAddress;
+        }
+        const provider = resolveProvider(this.config.wallet);
+        if (this.config.gas?.mode === "player") {
+          const from0 = await getAccount(provider);
+          await assertEnoughGas(provider, from0);
+        }
+        const from = await getAccount(provider);
+        let amountMicro = 0n;
+        if (input.checkBalance !== false) {
+          amountMicro = await this.readWithdrawable(prizePool, from);
+          if (amountMicro === 0n) {
+            throw new NothingToWithdrawError({ prizePoolAddress: prizePool, wallet: from });
+          }
+        }
+        const call = buildWithdrawCall(prizePool);
+        const paymasterUrl = this.config.gas?.mode === "sponsored" ? this.config.gas.paymasterUrl : void 0;
+        let txHash;
+        let status = "pending";
+        try {
+          const { id: callsId } = await sendCalls(
+            provider,
+            from,
+            this.env.chainId,
+            [call],
+            paymasterUrl
+          );
+          const waited = await waitForCalls(provider, callsId);
+          txHash = waited.txHash;
+          status = waited.status === "CONFIRMED" ? "confirmed" : waited.status === "FAILED" ? "failed" : "pending";
+        } catch (e) {
+          const msg = e?.message ?? String(e);
+          if (/NothingToWithdraw|nothing to withdraw/i.test(msg)) {
+            throw new NothingToWithdrawError({ prizePoolAddress: prizePool, wallet: from, cause: msg });
+          }
+          if (e instanceof NothingToWithdrawError || e instanceof PaymentFailedError) throw e;
+          throw new PaymentFailedError("PrizePool.withdraw() failed.", { cause: msg });
+        }
+        if (status === "failed") {
+          throw new PaymentFailedError("PrizePool.withdraw() did not confirm on-chain.", {
+            prizePoolAddress: prizePool,
+            txHash
+          });
+        }
+        if (amountMicro === 0n && input.checkBalance === false) ;
+        return {
+          prizePoolAddress: prizePool,
+          amount: formatMicroToUsd(amountMicro),
+          amountMicro: amountMicro.toString(),
+          txHash,
+          status
+        };
       }
     };
     /**
@@ -1034,6 +1169,9 @@ var Playmos = class {
       );
       const payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
       if (input.identity) payment2.identity = input.identity;
+      const pool = res.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
+      if (pool) payment2.prizePoolAddress = pool.toLowerCase();
+      payment2.roundKey = res.clientParams?.roundKey ?? res.clientParams?.roundId ?? payment2.roundId ?? input.roundId;
       return payment2;
     }
     const intent = await this.http.post(
@@ -1061,6 +1199,8 @@ var Playmos = class {
     const { txHash } = await waitForCalls(provider, callsId);
     const payment = await this.settle(intent.payment.id, txHash);
     payment.identity = identity;
+    payment.prizePoolAddress = prizePool.toLowerCase();
+    payment.roundKey = roundKey;
     return payment;
   }
   /**
@@ -1170,6 +1310,58 @@ var Playmos = class {
     const fromServer = intent.clientParams?.amountUnits ?? intent.clientParams?.amountMicro;
     return fromServer ? BigInt(fromServer) : local;
   }
+  /**
+   * Read PrizePool.withdrawable[wallet] via eth_call (issue #41).
+   * Uses the wallet provider when present; otherwise a public Base Sepolia RPC in test.
+   */
+  async readWithdrawable(prizePool, wallet) {
+    const data = viem.encodeFunctionData({
+      abi: prizePoolAbi,
+      functionName: "withdrawable",
+      args: [wallet]
+    });
+    let raw;
+    try {
+      if (await walletAvailable(this.config.wallet)) {
+        const provider = resolveProvider(this.config.wallet);
+        raw = await provider.request({
+          method: "eth_call",
+          params: [{ to: prizePool, data }, "latest"]
+        });
+      } else {
+        const rpc = this.env.network === "base" ? "https://mainnet.base.org" : "https://sepolia.base.org";
+        const res = await fetch(rpc, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_call",
+            params: [{ to: prizePool, data }, "latest"]
+          })
+        });
+        const json = await res.json();
+        if (!json.result) {
+          throw new ApiError(
+            `eth_call withdrawable failed: ${json.error?.message ?? "no result"}`,
+            { prizePool, wallet }
+          );
+        }
+        raw = json.result;
+      }
+    } catch (e) {
+      if (e instanceof ApiError) throw e;
+      throw new ApiError(`Could not read withdrawable balance: ${e.message}`, {
+        prizePool,
+        wallet
+      });
+    }
+    return viem.decodeFunctionResult({
+      abi: prizePoolAbi,
+      functionName: "withdrawable",
+      data: raw
+    });
+  }
   sponsorUrl(intent) {
     if (this.config.gas?.mode === "player") return void 0;
     return this.config.gas?.paymasterUrl ?? intent.clientParams?.paymasterUrl;
@@ -1457,6 +1649,7 @@ exports.InsufficientGasError = InsufficientGasError;
 exports.InvalidAmountError = InvalidAmountError;
 exports.MICRO_PER_USDC = MICRO_PER_USDC;
 exports.MissingFieldError = MissingFieldError;
+exports.NothingToWithdrawError = NothingToWithdrawError;
 exports.PaymentFailedError = PaymentFailedError;
 exports.PayoutError = PayoutError;
 exports.Playmos = Playmos;