@playmos/sdk 0.3.3 → 0.3.5

package/dist/index.js

@@ -1,5 +1,5 @@
-import { InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, ApiError, WalletConnectionError, InsufficientGasError, AuthError } from './chunk-TMBBEGIF.js';
-export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError } from './chunk-TMBBEGIF.js';
+import { AuthError, InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, ApiError, WalletConnectionError, InsufficientGasError } from './chunk-VYR6BBHF.js';
+export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError } from './chunk-VYR6BBHF.js';
 import { encodeFunctionData, decodeFunctionResult, numberToHex, keccak256, toBytes } from 'viem';
 
 // src/config.ts
@@ -15,9 +15,26 @@ var DEFAULT_API_BASE_URL = {
   base: "https://api.playmos.io/v1",
   "base-sepolia": "https://api.sandbox.playmos.io/v1"
 };
+function clientRuntimeSignals(g = globalThis) {
+  const any = g;
+  const signals = [];
+  if (typeof any.window !== "undefined") signals.push("window");
+  if (typeof any.document !== "undefined") signals.push("document");
+  const likelyCfWorker = typeof any.Cloudflare !== "undefined" || typeof any.WebSocketPair !== "undefined" && typeof any.window === "undefined";
+  if (typeof any.importScripts === "function" && !likelyCfWorker) {
+    signals.push("importScripts");
+  }
+  if (any.navigator?.product === "ReactNative") signals.push("ReactNative");
+  return signals;
+}
+function isClientRuntime(g = globalThis) {
+  return clientRuntimeSignals(g).length > 0;
+}
 function resolveEnv(apiKey, networkOverride, apiBaseUrlOverride) {
   if (typeof apiKey !== "string" || apiKey.trim() === "") {
-    throw new AuthError("Missing apiKey. Pass a pk_test_\u2026 or pk_live_\u2026 key.");
+    throw new AuthError(
+      'Missing apiKey. Expected a "pk_test_", "pk_live_", "sk_test_", or "sk_live_" prefix.'
+    );
   }
   const isTest = apiKey.startsWith("pk_test_") || apiKey.startsWith("sk_test_");
   const isLive = apiKey.startsWith("pk_live_") || apiKey.startsWith("sk_live_");
@@ -27,12 +44,14 @@ function resolveEnv(apiKey, networkOverride, apiBaseUrlOverride) {
       { keyPreview: apiKey.slice(0, 8) }
     );
   }
+  const isSecret = apiKey.startsWith("sk_");
   const network = networkOverride ?? (isTest ? "base-sepolia" : "base");
   return {
     network,
     chainId: CHAIN_ID[network],
     apiBaseUrl: apiBaseUrlOverride ?? DEFAULT_API_BASE_URL[network],
-    isTest
+    isTest,
+    isSecret
   };
 }
 
@@ -340,13 +359,6 @@ var erc20Abi = [
       { name: "amount", type: "uint256" }
     ],
     outputs: [{ type: "bool" }]
-  },
-  {
-    type: "function",
-    name: "balanceOf",
-    stateMutability: "view",
-    inputs: [{ name: "account", type: "address" }],
-    outputs: [{ type: "uint256" }]
   }
 ];
 var playmosPayAbi = [
@@ -363,17 +375,6 @@ var playmosPayAbi = [
   }
 ];
 var prizePoolAbi = [
-  {
-    type: "function",
-    name: "openRound",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "roundId", type: "bytes32" },
-      { name: "series", type: "bytes32" },
-      { name: "entry", type: "uint256" }
-    ],
-    outputs: []
-  },
   {
     type: "function",
     name: "enter",
@@ -384,50 +385,6 @@ var prizePoolAbi = [
     ],
     outputs: []
   },
-  {
-    type: "function",
-    name: "lockRound",
-    stateMutability: "nonpayable",
-    inputs: [{ name: "roundId", type: "bytes32" }],
-    outputs: []
-  },
-  {
-    type: "function",
-    name: "settle",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "roundId", type: "bytes32" },
-      { name: "winners", type: "address[]" },
-      { name: "amounts", type: "uint256[]" }
-    ],
-    outputs: []
-  },
-  {
-    type: "function",
-    name: "getRound",
-    stateMutability: "view",
-    inputs: [{ name: "roundId", type: "bytes32" }],
-    outputs: [
-      { name: "state", type: "uint8" },
-      { name: "series", type: "bytes32" },
-      { name: "entry", type: "uint256" },
-      { name: "pot", type: "uint256" },
-      { name: "entrantCount", type: "uint256" },
-      { name: "payable_", type: "uint256" },
-      { name: "inheritedSeed", type: "uint256" },
-      { name: "lockedAt", type: "uint256" }
-    ]
-  },
-  {
-    type: "function",
-    name: "hasEntered",
-    stateMutability: "view",
-    inputs: [
-      { name: "roundId", type: "bytes32" },
-      { name: "identity", type: "bytes32" }
-    ],
-    outputs: [{ type: "bool" }]
-  },
   {
     type: "function",
     name: "withdrawable",
@@ -551,7 +508,7 @@ function buildWithdrawCall(prizePool) {
 }
 
 // src/mock.ts
-var MOCK_TX = "0x000000000000000000000000000000000000000000000000000000000000mock";
+var MOCK_TX = `0x${"0".repeat(56)}deadbeef`;
 function mockIapPayment(args) {
   const { feeMicro, netMicro } = computeIapSplit(args.amountMicro, args.feeBps);
   return {
@@ -799,10 +756,16 @@ var Playmos = class {
       }
     };
     this.payouts = {
-      /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). */
-      setMode: (mode) => this.http.post("/payouts/mode", { mode }),
-      /** Create a Bridge KYC onboarding link (fiat payout). */
-      createOnboardingLink: () => this.http.post("/payouts/onboarding_link", {})
+      /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). Secret key only (#264). */
+      setMode: async (mode) => {
+        this.assertSecretKey("playmos.payouts.setMode");
+        return this.http.post("/payouts/mode", { mode });
+      },
+      /** Create a Bridge KYC onboarding link (fiat payout). Secret key only (#264). */
+      createOnboardingLink: async () => {
+        this.assertSecretKey("playmos.payouts.createOnboardingLink");
+        return this.http.post("/payouts/onboarding_link", {});
+      }
     };
     /**
      * `x402` — Phase 4 HTTP 402 / x402-shaped adapter (#153).
@@ -852,6 +815,10 @@ var Playmos = class {
        * Settle a previously minted challenge with an `x402-payload` authorization.
        * Defaults mode to `server-signer` when omitted (explicit on the wire — fail-closed
        * materialize still requires mode; the route also defaults for this path).
+       *
+       * #259/#269: settle uses `idempotency-key = requirement.id` and auto-retries gateway 504.
+       * A 504 replay may return **without throwing** with `success: false`, `status: "settling"`,
+       * `txHash: null` (in-flight). Treat as non-final — re-call or verify later; do not new-key.
        */
       fulfill: async (requirement, authorization) => {
         this.assertX402Allowed();
@@ -885,10 +852,19 @@ var Playmos = class {
         }
         if (payload.scheme === void 0) payload.scheme = "exact";
         if (payload.requirementId === void 0) payload.requirementId = requirement.id;
-        const res = await this.http.post("/x402/settle", {
-          requirement,
-          authorization: { kind: "x402-payload", payload }
-        });
+        const res = await this.http.post(
+          "/x402/settle",
+          {
+            requirement,
+            authorization: { kind: "x402-payload", payload }
+          },
+          // Settlement idempotency anchor = requirement.id (settlement.ts: "Settlement
+          // idempotency key + x402 challenge id"). Without this header the settle POST is
+          // excluded from the safe gateway-504 auto-retry (isRetryable), and the SDK's own
+          // 504 message ("retry with the same idempotency key (safe)") would be a lie —
+          // a 504 is exactly when the on-chain settle may have already landed (#259).
+          { idempotencyKey: requirement.id }
+        );
         const s = res.settlement;
         return {
           requirementId: s.requirementId,
@@ -931,8 +907,11 @@ var Playmos = class {
      */
     /** Offline mock store for rounds.open/lock/settle/get when `mock: true` (3-game dogfood). */
     this.mockRounds = /* @__PURE__ */ new Map();
+    /** Mock withdrawable credits after settle — key `${roundId}:${walletLower}` (#240 offline prize). */
+    this.mockWithdrawable = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
+        this.assertSecretKey("playmos.rounds.open");
         requireField(input?.gameId, "gameId");
         requireField(input?.roundId, "roundId");
         requireField(input?.entryAmount, "entryAmount");
@@ -952,34 +931,41 @@ var Playmos = class {
               code: "conflict"
             });
           }
-          const round2 = {
+          const round = {
             roundId: input.roundId,
             gameId: input.gameId,
             roundKey,
+            // #351 — must persist seriesKey so activeForSeries mock is authoritative
+            seriesKey: input.seriesKey ?? input.gameId,
             status: "open",
             entryAmount: input.entryAmount,
             pool: null,
             entrants: 0,
             payout: input.payout,
             closeAt: input.closeAt,
-            openTxHash: "0x000000000000000000000000000000000000000000000000000000000000mock",
+            openTxHash: MOCK_TX,
             prizePoolAddress: this.config.contracts?.prizePool ?? "0x0000000000000000000000000000000000000002"
           };
-          this.mockRounds.set(input.roundId, round2);
-          return round2;
+          this.mockRounds.set(input.roundId, round);
+          return round;
         }
-        const { round } = await this.http.post("/rounds", {
-          gameId: input.gameId,
-          roundId: input.roundId,
-          entryAmount: input.entryAmount,
-          payout: input.payout,
-          closeAt: input.closeAt,
-          seriesKey: input.seriesKey,
-          roundKey: input.roundKey
-        });
-        return round;
+        const body = await this.http.post(
+          "/rounds",
+          {
+            gameId: input.gameId,
+            roundId: input.roundId,
+            entryAmount: input.entryAmount,
+            payout: input.payout,
+            closeAt: input.closeAt,
+            seriesKey: input.seriesKey,
+            roundKey: input.roundKey
+          },
+          { acceptStatuses: [202] }
+        );
+        return body.round;
       },
       lock: async (input) => {
+        this.assertSecretKey("playmos.rounds.lock");
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
           const existing = this.mockRounds.get(input.roundId);
@@ -999,7 +985,7 @@ var Playmos = class {
             // Mock payable pool ≈ 60% of entry × max(1, entrants) for shape only — not money truth.
             pool: existing.pool ?? existing.entryAmount,
             entrants: existing.entrants ?? 0,
-            lockTxHash: "0x000000000000000000000000000000000000000000000000000000000000loc1"
+            lockTxHash: MOCK_TX
           };
           this.mockRounds.set(input.roundId, locked);
           return locked;
@@ -1011,6 +997,7 @@ var Playmos = class {
         return round;
       },
       settle: async (input) => {
+        this.assertSecretKey("playmos.rounds.settle");
         requireField(input?.roundId, "roundId");
         if (!input?.results) throw new ConfigError("results are required (ranking or winners)");
         if (this.config.mock) {
@@ -1041,7 +1028,7 @@ var Playmos = class {
             // Winner-take-all mock shape when ranking only.
             amount: i === 0 ? existing.pool ?? existing.entryAmount : "0"
           }));
-          const settleTxHash = "0x000000000000000000000000000000000000000000000000000000000000set1";
+          const settleTxHash = MOCK_TX;
           const poolPaid = existing.pool ?? existing.entryAmount;
           const settled = {
             ...existing,
@@ -1050,6 +1037,19 @@ var Playmos = class {
             pool: poolPaid
           };
           this.mockRounds.set(input.roundId, settled);
+          for (const w of winners) {
+            const wAddr = String(w.wallet).toLowerCase();
+            let micro = 0n;
+            try {
+              micro = validateAmount(String(w.amount ?? "0"));
+            } catch {
+              micro = 0n;
+            }
+            if (micro > 0n) {
+              const k = `${input.roundId}:${wAddr}`;
+              this.mockWithdrawable.set(k, (this.mockWithdrawable.get(k) ?? 0n) + micro);
+            }
+          }
           return {
             roundId: input.roundId,
             txHash: settleTxHash,
@@ -1060,10 +1060,65 @@ var Playmos = class {
         }
         const { settle } = await this.http.post(
           `/rounds/${encodeURIComponent(input.roundId)}/settle`,
-          { gameId: input.gameId, results: input.results }
+          { gameId: input.gameId, results: input.results },
+          { acceptStatuses: [202] }
         );
         return settle;
       },
+      /**
+       * Cancel an open/locked round (operator sk_ only). Refunds entrants' escrowed ~90%
+       * and frees the series latch. May return `status: "cancelling"` (HTTP 202) until
+       * chain Cancelled(4) reconciles — poll `rounds.get` or re-call cancel (#346).
+       */
+      cancel: async (input) => {
+        this.assertSecretKey("playmos.rounds.cancel");
+        requireField(input?.roundId, "roundId");
+        if (this.config.mock) {
+          const existing = this.mockRounds.get(input.roundId);
+          if (!existing) {
+            throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
+          }
+          if (existing.status === "cancelled") {
+            return {
+              roundId: input.roundId,
+              txHash: existing.cancelTxHash ?? MOCK_TX,
+              status: "cancelled",
+              round: existing
+            };
+          }
+          if (existing.status === "settled") {
+            throw new ApiError(`round ${input.roundId} is already settled \u2014 cannot cancel`, {
+              status: 409,
+              code: "conflict"
+            });
+          }
+          const cancelled = {
+            ...existing,
+            status: "cancelled",
+            cancelTxHash: MOCK_TX,
+            pool: null
+          };
+          this.mockRounds.set(input.roundId, cancelled);
+          return {
+            roundId: input.roundId,
+            txHash: MOCK_TX,
+            status: "cancelled",
+            round: cancelled
+          };
+        }
+        const body = await this.http.post(
+          `/rounds/${encodeURIComponent(input.roundId)}/cancel`,
+          { gameId: input.gameId },
+          { acceptStatuses: [202] }
+        );
+        const status = body.status === "cancelling" || body.round?.status === "cancelling" ? "cancelling" : "cancelled";
+        return {
+          roundId: input.roundId,
+          txHash: body.txHash ?? body.round?.cancelTxHash ?? null,
+          status,
+          round: body.round
+        };
+      },
       get: async (input) => {
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
@@ -1078,6 +1133,58 @@ var Playmos = class {
         );
         return round;
       },
+      /**
+       * Authoritative series latch (#351) — `null` means **proven free**.
+       * `GET /v1/series/:seriesKey/active?gameId=…` — not a candidate probe.
+       */
+      activeForSeries: async (input) => {
+        requireField(input?.seriesKey, "seriesKey");
+        requireField(input?.gameId, "gameId");
+        if (this.config.mock) {
+          for (const r of this.mockRounds.values()) {
+            if (r.gameId !== input.gameId) continue;
+            const sk = r.seriesKey ?? r.gameId;
+            if (sk !== input.seriesKey) continue;
+            if (r.status === "open" || r.status === "locked" || r.status === "opening" || r.status === "cancelling") {
+              return {
+                roundId: r.roundId,
+                roundKey: r.roundKey,
+                roundIdHash: "0x" + "m".repeat(64),
+                status: r.status,
+                entrants: r.entrants,
+                pool: r.pool,
+                openTxHash: r.openTxHash ?? null,
+                cancelTxHash: r.cancelTxHash ?? null,
+                prizePoolAddress: r.prizePoolAddress ?? "0x0000000000000000000000000000000000000002"
+              };
+            }
+          }
+          return null;
+        }
+        const body = await this.http.get(
+          `/series/${encodeURIComponent(input.seriesKey)}/active?gameId=${encodeURIComponent(input.gameId)}`
+        );
+        if (body == null || typeof body !== "object") {
+          throw new ApiError("activeForSeries: malformed response (expected object body)", {
+            code: "invalid_response",
+            status: 502
+          });
+        }
+        if (!("active" in body)) {
+          throw new ApiError("activeForSeries: malformed response (missing active field)", {
+            code: "invalid_response",
+            status: 502
+          });
+        }
+        if (body.active === null) return null;
+        if (body.active == null || typeof body.active !== "object") {
+          throw new ApiError("activeForSeries: malformed response (active must be object or null)", {
+            code: "invalid_response",
+            status: 502
+          });
+        }
+        return body.active;
+      },
       /**
        * Read a wallet's **claimable** prize balance for a round (issue #41).
        * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
@@ -1088,6 +1195,21 @@ var Playmos = class {
       prize: async (input) => {
         requireField(input?.roundId, "roundId");
         const wallet = requireAddressField(input?.wallet, "wallet");
+        if (this.config.mock) {
+          const existing = this.mockRounds.get(input.roundId);
+          if (!existing) {
+            throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
+          }
+          const claimableMicro2 = this.mockWithdrawable.get(`${input.roundId}:${wallet.toLowerCase()}`) ?? 0n;
+          const prizePoolAddress2 = input.prizePoolAddress ?? existing.prizePoolAddress ?? "0x0000000000000000000000000000000000000002";
+          return {
+            roundId: input.roundId,
+            prizePoolAddress: prizePoolAddress2,
+            wallet,
+            claimable: formatMicroToUsd(claimableMicro2),
+            claimableMicro: claimableMicro2.toString()
+          };
+        }
         try {
           const res = await this.http.get(
             `/rounds/${encodeURIComponent(input.roundId)}/prize?wallet=${encodeURIComponent(wallet)}`
@@ -1114,11 +1236,24 @@ var Playmos = class {
        */
       withdraw: async (input) => {
         if (this.config.mock) {
+          let amountMicro2 = 0n;
+          let prizePool2 = input.prizePoolAddress ?? "0x0000000000000000000000000000000000000001";
+          if (input.roundId) {
+            const existing = this.mockRounds.get(input.roundId);
+            if (existing?.prizePoolAddress) prizePool2 = existing.prizePoolAddress;
+            for (const [k, v] of this.mockWithdrawable) {
+              if (k.startsWith(`${input.roundId}:`) && v > 0n) {
+                amountMicro2 = v;
+                this.mockWithdrawable.set(k, 0n);
+                break;
+              }
+            }
+          }
           return {
-            prizePoolAddress: input.prizePoolAddress ?? "0x0000000000000000000000000000000000000001",
-            amount: "0.00",
-            amountMicro: "0",
-            txHash: "0x000000000000000000000000000000000000000000000000000000000000mock",
+            prizePoolAddress: prizePool2,
+            amount: formatMicroToUsd(amountMicro2),
+            amountMicro: amountMicro2.toString(),
+            txHash: MOCK_TX,
             status: "confirmed"
           };
         }
@@ -1193,23 +1328,27 @@ var Playmos = class {
     this.agents = {
       /** Assign (or return) the wallet for a game NPC id. Idempotent — safe to call wherever your NPCs spawn. */
       createWallet: async (input) => {
+        this.assertSecretKey("playmos.agents");
         requireField(input?.agentId, "agentId");
         const { agent } = await this.http.post("/agents/wallets", { agentId: input.agentId });
         return agent;
       },
       /** Resolve one NPC's wallet by your id. */
       wallet: async (agentId) => {
+        this.assertSecretKey("playmos.agents");
         requireField(agentId, "agentId");
         const { agent } = await this.http.get(`/agents/wallets/${encodeURIComponent(agentId)}`);
         return agent;
       },
       /** List the NPC wallets you've assigned in this studio. */
       list: async () => {
+        this.assertSecretKey("playmos.agents");
         const { agents } = await this.http.get("/agents/wallets");
         return agents;
       },
       /** Sandbox faucet: fund an NPC with USDC from your treasury (per-NPC lifetime cap). */
-      fund: (input) => {
+      fund: async (input) => {
+        this.assertSecretKey("playmos.agents.fund");
         requireField(input?.agentId, "agentId");
         validateAmount(input.amount);
         const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
@@ -1220,10 +1359,17 @@ var Playmos = class {
         );
       },
       /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
-      pay: (input) => {
+      pay: async (input) => {
+        this.assertSecretKey("playmos.agents.pay");
         requireField(input?.from, "from");
         requireField(input?.to, "to");
-        return this.transfer({ from: input.from, to: input.to, amount: input.amount, feeBps: input.feeBps, feeSink: input.feeSink });
+        return this.transfer({
+          from: input.from,
+          to: input.to,
+          amount: input.amount,
+          feeBps: input.feeBps,
+          feeSink: input.feeSink
+        });
       }
     };
     /**
@@ -1407,6 +1553,15 @@ var Playmos = class {
     };
     this.config = config;
     this.env = resolveEnv(config.apiKey, config.network, config.apiBaseUrl);
+    if (this.env.isSecret) {
+      const signals = clientRuntimeSignals();
+      if (signals.length > 0) {
+        throw new AuthError(
+          "Secret (sk_) key used in a client runtime \u2014 sk_ keys are server-only; use a pk_ key client-side.",
+          { isSecret: true, clientRuntime: true, signals }
+        );
+      }
+    }
     this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
   }
   /** Connect the player's wallet and return their address. */
@@ -1434,9 +1589,10 @@ var Playmos = class {
           roundId: req.roundKey,
           roundKey: req.roundKey,
           identity: req.identity,
-          amount: formatMicroToUsd(req.entryUnits),
-          playerId: req.wallet
+          playerId: req.wallet,
+          amount: formatMicroToUsd(req.entryUnits)
         });
+        this.rememberMock(entry);
         const raw = String(entry.status ?? "pending").toLowerCase();
         const status = raw === "confirmed" ? "confirmed" : raw === "failed" ? "failed" : "pending";
         const onchain = !entry.mock;
@@ -1476,14 +1632,39 @@ var Playmos = class {
     if (this.env.isTest && !await walletAvailable(this.config.wallet)) {
       const res = await this.http.post(
         "/payments",
-        { kind: "iap", amount: input.amount, sku: input.sku, playerId: input.playerId, gameId: input.gameId, studio: input.studio, metadata, settle: "server" },
-        { idempotencyKey }
+        {
+          kind: "iap",
+          amount: input.amount,
+          sku: input.sku,
+          playerId: input.playerId,
+          gameId: input.gameId,
+          studio: input.studio,
+          metadata,
+          settle: "server",
+          idempotencyKey
+          /* MUST be in the BODY — the service reads body.idempotencyKey, not the header (#257 P1b) */
+        },
+        { idempotencyKey, acceptStatuses: [201, 202] }
       );
-      return this.mapServerPayment(res.payment, "iap", amountMicro);
+      let payment = this.mapServerPayment(res.payment, "iap", amountMicro);
+      if (payment.status === "pending" || payment.status === "created") {
+        payment = await this.waitForServerSettle(payment.id, "iap", amountMicro);
+      }
+      return payment;
     }
     const intent = await this.http.post(
       "/payments",
-      { kind: "iap", amount: input.amount, sku: input.sku, playerId: input.playerId, gameId: input.gameId, studio: input.studio, metadata },
+      {
+        kind: "iap",
+        amount: input.amount,
+        sku: input.sku,
+        playerId: input.playerId,
+        gameId: input.gameId,
+        studio: input.studio,
+        metadata,
+        idempotencyKey
+        /* MUST be in the BODY — the service reads body.idempotencyKey, not the header (#257 P1b) */
+      },
       { idempotencyKey }
     );
     const provider = resolveProvider(this.config.wallet);
@@ -1532,23 +1713,48 @@ var Playmos = class {
       );
     }
     if (this.env.isTest && !await walletAvailable(this.config.wallet)) {
+      const pinnedRoundKey = input.roundKey ?? input.roundId;
       const res = await this.http.post(
         "/payments",
-        { kind: "entry", amount: input.amount, gameId: input.gameId, roundId: input.roundKey ?? input.roundId, identity: input.identity, playerId: input.playerId, metadata, settle: "server" },
-        { idempotencyKey }
+        {
+          kind: "entry",
+          amount: input.amount,
+          gameId: input.gameId,
+          roundId: pinnedRoundKey,
+          identity: input.identity,
+          playerId: input.playerId,
+          metadata,
+          settle: "server",
+          idempotencyKey
+          /* MUST be in the BODY — the service reads body.idempotencyKey, not the header (#257 P1b) */
+        },
+        { idempotencyKey, acceptStatuses: [201, 202] }
       );
-      const payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
+      let payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
+      if (payment2.status === "pending" || payment2.status === "created") {
+        payment2 = await this.waitForServerSettle(payment2.id, "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 ?? input.roundKey ?? res.clientParams?.roundId ?? payment2.roundId ?? input.roundId;
+      payment2.roundKey = input.roundKey ?? res.clientParams?.roundKey ?? res.clientParams?.roundId ?? payment2.roundId ?? input.roundId;
       return payment2;
     }
     const intent = await this.http.post(
       "/payments",
       // When the game supplies its own roundKey, that IS the round the service
       // stores + verifies against (so on-chain enter and server hasEntered align).
-      { kind: "entry", amount: input.amount, gameId: input.gameId, roundId: input.roundKey ?? input.roundId, identity: input.identity, playerId: input.playerId, metadata },
+      {
+        kind: "entry",
+        amount: input.amount,
+        gameId: input.gameId,
+        roundId: input.roundKey ?? input.roundId,
+        identity: input.identity,
+        playerId: input.playerId,
+        metadata,
+        idempotencyKey
+        /* MUST be in the BODY — the service reads body.idempotencyKey, not the header (#257 P1b) */
+      },
       { idempotencyKey }
     );
     const provider = resolveProvider(this.config.wallet);
@@ -1591,6 +1797,7 @@ var Playmos = class {
    * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
    */
   async transfer(input, opts) {
+    this.assertSecretKey("playmos.transfer");
     const amountMicro = validateAmount(input.amount);
     const from = input.from === void 0 ? void 0 : partyRef(input.from, "from");
     const to = partyRef(input.to, "to");
@@ -1660,17 +1867,56 @@ var Playmos = class {
   }
   // ---- internals ---------------------------------------------------------
   /**
-   * x402 V1 is Base Sepolia + test keys only (ADR D5). Fail closed before any
-   * network call so mainnet / live keys never silently hit the adapter.
+   * Secret (sk_) surfaces — agents / transfer / x402. Capability tracks key type
+   * in code, not README prose (#260). pk_ keys are client-safe and refuse these.
+   */
+  assertSecretKey(surface) {
+    if (!this.env.isSecret) {
+      throw new AuthError(
+        `${surface} requires a secret (sk_) key \u2014 use sk_test_\u2026 / sk_live_\u2026 on the server. Publishable (pk_) keys are client-safe and cannot call this surface.`,
+        { surface, isSecret: false }
+      );
+    }
+  }
+  /**
+   * x402 V1 is Base Sepolia + secret test keys only (ADR D5 + #260). Fail closed
+   * before any network call so mainnet / live / publishable keys never hit the adapter.
+   * Does not change fulfill/settle body shape (A owns #261 / #259 money path).
    */
   assertX402Allowed() {
+    this.assertSecretKey("playmos.x402");
     if (!this.env.isTest || this.env.network !== "base-sepolia") {
       throw new ConfigError(
-        'playmos.x402 is Base Sepolia / test-key only in V1 (ADR D5). Use apiKey sk_test_\u2026 and network "base-sepolia".',
-        { network: this.env.network, isTest: this.env.isTest }
+        'playmos.x402 is Base Sepolia / sk_test_ only in V1 (ADR D5). Use apiKey sk_test_\u2026 and network "base-sepolia".',
+        { network: this.env.network, isTest: this.env.isTest, isSecret: this.env.isSecret }
       );
     }
   }
+  /**
+   * Poll GET /payments/:id after server-settle until terminal status.
+   * - Entry (#221): service may return 202 pending (openRound+enter > DO edge).
+   * - IAP: service often returns 201 + txHash while status is still "created"
+   *   until chain verify catches PaymentSettled (RPC lag) — poll so pay() matches
+   *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
+   */
+  async waitForServerSettle(paymentId, kind, amountMicro, timeoutMs = 6e4) {
+    const start = Date.now();
+    let delayMs = 400;
+    while (Date.now() - start < timeoutMs) {
+      const raw = await this.http.get(
+        `/payments/${encodeURIComponent(paymentId)}`
+      );
+      if (raw.status === "confirmed" || raw.status === "failed") {
+        return this.mapServerPayment(raw, kind, amountMicro);
+      }
+      await new Promise((r) => setTimeout(r, delayMs));
+      delayMs = Math.min(Math.floor(delayMs * 1.4), 2e3);
+    }
+    throw new ApiError(
+      `Timed out after ${timeoutMs}ms waiting for server-settle of ${paymentId}. Re-check with playmos.verify("${paymentId}").`,
+      { paymentId, timeout: true, asyncSettle: true }
+    );
+  }
   /**
    * Map a server-settled payment (from the `settle: "server"` response) into the
    * SDK's `Payment` shape. The service already signed + confirmed on-chain, so we
@@ -2042,6 +2288,4 @@ function isX402PayloadAuthorization(auth) {
   return auth.kind === "x402-payload";
 }
 
-export { CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PayoutError, Playmos, USDC_ADDRESS, USDC_DECIMALS, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+export { CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PayoutError, Playmos, USDC_ADDRESS, USDC_DECIMALS, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };