@playmos/sdk 0.3.13 → 0.3.14

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to `@playmos/sdk`. This project adheres to [Semantic Version
 
 ## Unreleased
 
+## [0.3.14] — 2026-09-11
+
+### Added
+- **`settle: "server"`** on `new Playmos({ ... })` — explicit sandbox no-wallet path. `pay()` / `enterRound()` server-settle even when MetaMask is installed. Live keys throw. Default without the ask is unchanged (wallet present → player signs).
+
 ## [0.3.13] — 2026-09-11
 
 ### Docs

package/README.md

@@ -23,7 +23,7 @@ The sandbox API also sends CORS headers so browser `pay()` / `enterRound()` work
 
 ## Quickstart — the no-wallet sandbox
 
-The public sandbox key `pk_test_playmos_sandbox` runs against a real Playmos test service on Base Sepolia. **You don't need a wallet:** on a `pk_test` key with no `wallet` configured, the SDK routes to a server-settle path where Playmos signs and submits the on-chain transaction for you. You still get a real, confirmed `txHash` — just signed by the service. No wallet, no gas, no crypto.
+The public sandbox key `pk_test_playmos_sandbox` runs against a real Playmos test service on Base Sepolia. **You don't need a wallet:** set `settle: "server"` (the quickstart does). The SDK then server-settles even if MetaMask is installed. You still get a real, confirmed `txHash` — signed by the service. No wallet, no gas, no crypto. Omit `settle` only when you want the player to sign.
 
 The public key is wired to `game_sandbox_iap`. Skill entry (`game_sandbox_skill`) is an optional later path — not the first-hour default.
 
@@ -35,7 +35,7 @@ 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 playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox", settle: "server" });
 
 const payment = await playmos.pay({
   gameId: "game_sandbox_iap", // required for the public sandbox key
@@ -90,7 +90,7 @@ const entry = await playmos.enterRound({
 
 ### Your own contest pool — `epochs.preparePool` (you sign)
 
-`@playmos/sdk` **0.3.13** ships `epochs.preparePool` with `bytecode` / `unsignedTx` on the typed response. It calls the live API. Playmos sets `broadcast: false` and does **not** send the transaction.
+`@playmos/sdk` **0.3.14** ships `epochs.preparePool` with `bytecode` / `unsignedTx` on the typed response. It calls the live API. Playmos sets `broadcast: false` and does **not** send the transaction.
 
 1. Fund your studio wallet on Base Sepolia (ETH + test USDC). Playmos has no faucet — use [Coinbase's faucet docs](https://docs.cdp.coinbase.com/faucets/introduction/welcome).
 2. Call `epochs.preparePool({ studioWallet })` or `POST /v1/epochs/pools/prepare`. Use `feeSink` from that response (`0xD84c190085aa59c48a9B478Ea333D50B8DF4aD42`).

package/dist/{errors-CYKgt2VU.d.cts → errors-WcDNfb4q.d.cts}

@@ -76,6 +76,13 @@ interface PlaymosConfig {
      * even mock results use the REAL status union (never a synthetic "mocked").
      */
     mock?: boolean;
+    /**
+     * Explicit sandbox no-wallet path. On a test key, `pay()` / `enterRound()`
+     * server-settle even if MetaMask (or another injected wallet) is installed.
+     * Live keys (`pk_live_` / `sk_live_`) throw — never server-settle real money.
+     * Omit to keep today's default: server-settle only when no wallet is present.
+     */
+    settle?: "server";
     /**
      * Automatic backoff/retry on HTTP 429 (throttling). Default ON (up to 2 retries,
      * honoring a `Retry-After` header). Retries are safe — reads are idempotent and

package/dist/{errors-CYKgt2VU.d.ts → errors-WcDNfb4q.d.ts}

@@ -76,6 +76,13 @@ interface PlaymosConfig {
      * even mock results use the REAL status union (never a synthetic "mocked").
      */
     mock?: boolean;
+    /**
+     * Explicit sandbox no-wallet path. On a test key, `pay()` / `enterRound()`
+     * server-settle even if MetaMask (or another injected wallet) is installed.
+     * Live keys (`pk_live_` / `sk_live_`) throw — never server-settle real money.
+     * Omit to keep today's default: server-settle only when no wallet is present.
+     */
+    settle?: "server";
     /**
      * Automatic backoff/retry on HTTP 429 (throttling). Default ON (up to 2 retries,
      * honoring a `Retry-After` header). Retries are safe — reads are idempotent and

package/dist/index.cjs

@@ -2262,7 +2262,7 @@ var Playmos = class {
       },
       walletAddress: async () => getAccount(this.walletProvider()),
       readView: async (to, data) => {
-        if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+        if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
           const provider = this.walletProvider();
           return await provider.request({
             method: "eth_call",
@@ -3363,8 +3363,14 @@ var Playmos = class {
         );
       }
     }
+    if (config.settle === "server" && !this.env.isTest) {
+      throw new ConfigError(
+        'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+        { field: "settle" }
+      );
+    }
     this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
-    if (!config.mock) {
+    if (!config.mock && config.settle !== "server") {
       try {
         resolveProvider(config.wallet, this.walletTimeoutPolicy());
       } catch {
@@ -3434,6 +3440,23 @@ var Playmos = class {
       return 0n;
     }
   }
+  /**
+   * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+   * a test key has no wallet. Never calls walletAvailable if the ask is set —
+   * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+   */
+  async shouldServerSettle() {
+    if (this.config.settle === "server") {
+      if (!this.env.isTest) {
+        throw new ConfigError(
+          'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+          { field: "settle" }
+        );
+      }
+      return true;
+    }
+    return this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+  }
   /**
    * Wallet timeout policy (#462 / PR #463 residual).
    * - connectTimeoutMs → eth_requestAccounts only
@@ -3561,7 +3584,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+    if (await this.shouldServerSettle()) {
       const res = await this.http.post(
         "/payments",
         {
@@ -3666,7 +3689,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+    const serverSettleNoWallet = await this.shouldServerSettle();
     if (!serverSettleNoWallet) {
       const pinned = typeof input.identity === "string" ? input.identity.trim() : "";
       if (!pinned) {
@@ -3996,7 +4019,7 @@ var Playmos = class {
     });
     let raw;
     try {
-      if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+      if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
         const provider = this.walletProvider();
         raw = await provider.request({
           method: "eth_call",

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-CYKgt2VU.cjs';
-export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-CYKgt2VU.cjs';
+import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-WcDNfb4q.cjs';
+export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-WcDNfb4q.cjs';
 
 /**
  * Thin REST client for the Playmos service. Every SDK method that touches the
@@ -1323,6 +1323,12 @@ declare class Playmos {
      */
     private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
+    /**
+     * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+     * a test key has no wallet. Never calls walletAvailable if the ask is set —
+     * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+     */
+    private shouldServerSettle;
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
      * - connectTimeoutMs → eth_requestAccounts only

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-CYKgt2VU.js';
-export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-CYKgt2VU.js';
+import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-WcDNfb4q.js';
+export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-WcDNfb4q.js';
 
 /**
  * Thin REST client for the Playmos service. Every SDK method that touches the
@@ -1323,6 +1323,12 @@ declare class Playmos {
      */
     private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
+    /**
+     * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+     * a test key has no wallet. Never calls walletAvailable if the ask is set —
+     * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+     */
+    private shouldServerSettle;
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
      * - connectTimeoutMs → eth_requestAccounts only

package/dist/index.js

@@ -1818,7 +1818,7 @@ var Playmos = class {
       },
       walletAddress: async () => getAccount(this.walletProvider()),
       readView: async (to, data) => {
-        if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+        if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
           const provider = this.walletProvider();
           return await provider.request({
             method: "eth_call",
@@ -2919,8 +2919,14 @@ var Playmos = class {
         );
       }
     }
+    if (config.settle === "server" && !this.env.isTest) {
+      throw new ConfigError(
+        'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+        { field: "settle" }
+      );
+    }
     this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
-    if (!config.mock) {
+    if (!config.mock && config.settle !== "server") {
       try {
         resolveProvider(config.wallet, this.walletTimeoutPolicy());
       } catch {
@@ -2990,6 +2996,23 @@ var Playmos = class {
       return 0n;
     }
   }
+  /**
+   * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+   * a test key has no wallet. Never calls walletAvailable if the ask is set —
+   * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+   */
+  async shouldServerSettle() {
+    if (this.config.settle === "server") {
+      if (!this.env.isTest) {
+        throw new ConfigError(
+          'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+          { field: "settle" }
+        );
+      }
+      return true;
+    }
+    return this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+  }
   /**
    * Wallet timeout policy (#462 / PR #463 residual).
    * - connectTimeoutMs → eth_requestAccounts only
@@ -3117,7 +3140,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+    if (await this.shouldServerSettle()) {
       const res = await this.http.post(
         "/payments",
         {
@@ -3222,7 +3245,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+    const serverSettleNoWallet = await this.shouldServerSettle();
     if (!serverSettleNoWallet) {
       const pinned = typeof input.identity === "string" ? input.identity.trim() : "";
       if (!pinned) {
@@ -3552,7 +3575,7 @@ var Playmos = class {
     });
     let raw;
     try {
-      if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+      if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
         const provider = this.walletProvider();
         raw = await provider.request({
           method: "eth_call",

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { a2 as PlaymosError, W as WebhookEvent } from './errors-CYKgt2VU.cjs';
-export { ad as enterPathToBytes32 } from './errors-CYKgt2VU.cjs';
+import { a2 as PlaymosError, W as WebhookEvent } from './errors-WcDNfb4q.cjs';
+export { ad as enterPathToBytes32 } from './errors-WcDNfb4q.cjs';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { a2 as PlaymosError, W as WebhookEvent } from './errors-CYKgt2VU.js';
-export { ad as enterPathToBytes32 } from './errors-CYKgt2VU.js';
+import { a2 as PlaymosError, W as WebhookEvent } from './errors-WcDNfb4q.js';
+export { ad as enterPathToBytes32 } from './errors-WcDNfb4q.js';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playmos/sdk",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "Playmos SDK — stablecoin payments for games on Base. IAP and skill contests are flat 1%. USD in, USDC on-chain, no crypto UX for players.",
   "license": "MIT",
   "private": false,