@playmos/sdk 0.2.0 → 0.3.0

package/README.md

@@ -62,8 +62,8 @@ 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 walkthrough: docs/examples/playmos-town-sdk.mjs
-// Confirm: status === "settled" && txHash, or poll playmos.transfers.get(id) if settling.
+// Full agent/Town walkthrough: see "Agent 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
   // (Phase 1a's only payer), so you don't need to know that address to run this example.
@@ -109,6 +109,65 @@ 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
+
+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%).
+
+**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`.
+
+```ts
+import { Playmos } from "@playmos/sdk";
+
+// Server-side only — an sk_test_ secret key, never shipped to the browser.
+const playmos = new Playmos({ apiKey: process.env.PLAYMOS_SK_TEST });
+const feeSink = process.env.PLAYMOS_FEE_SINK; // 0x treasury / shop wallet
+
+// 1) Assign a wallet to an NPC your game already owns (idempotent — safe to re-call).
+const miner = await playmos.agents.createWallet({ agentId: "npc_pico_miner" });
+miner.address; // 0x… — the NPC's USDC wallet on Base Sepolia
+
+// 2) Fund it from your treasury (sandbox faucet, per-NPC lifetime cap).
+const funded = await playmos.agents.fund({ agentId: "npc_pico_miner", amount: "0.20" });
+funded.funding.status; // "settled" | "settling"
+
+// 3a) P2P trade — 5% fee to the treasury (feeBps: 500). NPC `from` ⇒ gasless (NPC signs, Playmos relays + pays gas).
+const p2p = await playmos.transfer({
+  from:    "npc_pico_miner",
+  to:      "npc_bruna_blacksmith",
+  amount:  "0.10",
+  feeBps:  500,       // 5% P2P
+  feeSink,            // required when feeBps > 0
+});
+
+// Confirm with the new ergonomics (#54): wait for a terminal state — no hand-rolled poll loop.
+const settled = await playmos.transfers.wait(p2p.id);
+settled.status; // "settled" — txHash on sepolia.basescan.org
+
+// 3b) Monster-bounty payout — 0% untaxed reward from the treasury signer (omit `from`, no feeSink).
+await playmos.transfer({ to: "npc_wynn_ranger", amount: "0.05", feeBps: 0 });
+
+// 3c) First-party shop sale — 100% to the shop (feeBps: 10000).
+await playmos.transfer({ from: "npc_kane_knight", to: feeSink, amount: "0.05", feeBps: 10_000, feeSink });
+```
+
+**Prefer one call? Confirm inline.** Pass `{ confirm: true }` and `transfer` blocks until the transfer is terminal before it resolves — identical to calling `transfers.wait(id)` yourself (#54):
+
+```ts
+const t = await playmos.transfer(
+  { from: "npc_pico_miner", to: "npc_bruna_blacksmith", amount: "0.10", feeBps: 500, feeSink },
+  { confirm: true },
+);
+t.status; // "settled" (or "failed") — already terminal, no follow-up call
+```
+
+The sandbox throttles (5 req/min per key), so back-to-back legs can `429`. **Retries are automatic** — the SDK backs off and retries a `429` up to twice by default, and every write carries an idempotency key so a retry never double-broadcasts (tune with `new Playmos({ apiKey, retry: { maxRetries } })`, or `retry: false` to opt out).
+
+The full 5-NPC walkthrough — create → fund → P2P / shop / bounty, each confirmed on-chain — is [`docs/examples/playmos-town-sdk.mjs`](https://github.com/playmos-labs/playmos-sdk/blob/main/docs/examples/playmos-town-sdk.mjs):
+
+```bash
+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.

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

@@ -65,6 +65,54 @@ interface PlaymosConfig {
      * even mock results use the REAL status union (never a synthetic "mocked").
      */
     mock?: boolean;
+    /**
+     * 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
+     * writes carry an idempotency key, so a retry never double-broadcasts.
+     *   retry: false          → opt out entirely
+     *   retry: { maxRetries }  → tune attempts / backoff (0 also opts out)
+     */
+    retry?: boolean | RetryOptions;
+}
+/** Tuning for the automatic 429 retry (all optional; sane defaults). */
+interface RetryOptions {
+    /** Max automatic retries on HTTP 429. `0` disables retrying entirely. Default 2. */
+    maxRetries?: number;
+    /** Base backoff in ms; the wait grows exponentially per attempt (2^n). Default 500. */
+    baseDelayMs?: number;
+    /** Ceiling for any single backoff wait, including a server `Retry-After`. Default 20000. */
+    maxDelayMs?: number;
+}
+/**
+ * The on-chain-reconciled view of a `transfer`, as `playmos.transfers.get(id)` /
+ * `playmos.transfers.wait(id)` resolve it. `status` is the settlement lifecycle:
+ * "settled" (confirmed) · "settling" (reserved, confirmation pending) · "failed"
+ * (mined revert) · "pending" · "unknown". Terminal states are `settled`/`failed`.
+ */
+interface TransferReconcile {
+    id: string;
+    status: string;
+    txHash: string | null;
+    to: string;
+    amount: string;
+    verifiedVia: "chain" | "cache" | "degraded";
+}
+/** Options for `playmos.transfers.wait(id, opts?)` — how long / how often to poll. */
+interface WaitOptions {
+    /** Poll interval in ms between `transfers.get` calls. Default 1000. */
+    intervalMs?: number;
+    /** Max total time to wait before throwing a timeout. Default 30000. */
+    timeoutMs?: number;
+    /** Belt-and-suspenders cap on poll attempts (alongside `timeoutMs`). Default 40. */
+    maxAttempts?: number;
+}
+/** Options for the confirm-inline form of `transfer(input, opts?)`. */
+interface TransferConfirmOptions extends WaitOptions {
+    /**
+     * When true and the POST comes back `settling`, block until the transfer reaches
+     * a terminal state (settled/failed) before resolving — no hand-rolled poll loop.
+     */
+    confirm?: boolean;
 }
 interface PayInput {
     /** USD decimal string ("4.99"). Rejected: ≤ 0, non-numeric, > 2 dp. */
@@ -150,6 +198,7 @@ interface AgentWallet {
 interface AgentFundResult {
     agent: AgentWallet;
     funding: {
+        id: string;
         amount: string;
         status: string;
         txHash: string | null;
@@ -420,9 +469,10 @@ interface RoundState {
     roundKey: string;
     status: RoundStatus;
     entryAmount: string;
-    /** Payable pool in USD (from chain after lock); may be "0.00" while open. */
-    pool: string;
-    entrants: number;
+    /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). */
+    pool: string | null;
+    /** Entrant count from chain after reconcile; **`null` until reconciled**. */
+    entrants: number | null;
     payout: PayoutRule;
     closeAt?: string;
     openTxHash?: `0x${string}`;
@@ -499,4 +549,4 @@ declare class ConfigError extends PlaymosError {
     constructor(message: string, detail?: Record<string, unknown>);
 }
 
-export { type AgentWallet as A, type PlaymosErrorCode as B, ConfigError as C, type RoundStatus as D, type EscrowHoldInput as E, type WalletConfig as F, type GasConfig as G, WalletConnectionError as H, InsufficientGasError as I, type WalletConnector as J, type WebhookEventType as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type PlaymosConfig as P, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type VerifyResult as V, type WebhookEvent as W, 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 TransferInput as k, type AgentEconomyConfig as l, ApiError as m, AuthError as n, type ContractConfig as o, type Eip1193Provider as p, type GasMode as q, InvalidAmountError as r, type ListingStatus as s, type MarketplaceItem as t, type MarketplaceSale as u, MissingFieldError as v, PaymentFailedError as w, type PaymentStatus as x, type PayoutRule as y, PlaymosError as z };
+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 };

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

@@ -65,6 +65,54 @@ interface PlaymosConfig {
      * even mock results use the REAL status union (never a synthetic "mocked").
      */
     mock?: boolean;
+    /**
+     * 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
+     * writes carry an idempotency key, so a retry never double-broadcasts.
+     *   retry: false          → opt out entirely
+     *   retry: { maxRetries }  → tune attempts / backoff (0 also opts out)
+     */
+    retry?: boolean | RetryOptions;
+}
+/** Tuning for the automatic 429 retry (all optional; sane defaults). */
+interface RetryOptions {
+    /** Max automatic retries on HTTP 429. `0` disables retrying entirely. Default 2. */
+    maxRetries?: number;
+    /** Base backoff in ms; the wait grows exponentially per attempt (2^n). Default 500. */
+    baseDelayMs?: number;
+    /** Ceiling for any single backoff wait, including a server `Retry-After`. Default 20000. */
+    maxDelayMs?: number;
+}
+/**
+ * The on-chain-reconciled view of a `transfer`, as `playmos.transfers.get(id)` /
+ * `playmos.transfers.wait(id)` resolve it. `status` is the settlement lifecycle:
+ * "settled" (confirmed) · "settling" (reserved, confirmation pending) · "failed"
+ * (mined revert) · "pending" · "unknown". Terminal states are `settled`/`failed`.
+ */
+interface TransferReconcile {
+    id: string;
+    status: string;
+    txHash: string | null;
+    to: string;
+    amount: string;
+    verifiedVia: "chain" | "cache" | "degraded";
+}
+/** Options for `playmos.transfers.wait(id, opts?)` — how long / how often to poll. */
+interface WaitOptions {
+    /** Poll interval in ms between `transfers.get` calls. Default 1000. */
+    intervalMs?: number;
+    /** Max total time to wait before throwing a timeout. Default 30000. */
+    timeoutMs?: number;
+    /** Belt-and-suspenders cap on poll attempts (alongside `timeoutMs`). Default 40. */
+    maxAttempts?: number;
+}
+/** Options for the confirm-inline form of `transfer(input, opts?)`. */
+interface TransferConfirmOptions extends WaitOptions {
+    /**
+     * When true and the POST comes back `settling`, block until the transfer reaches
+     * a terminal state (settled/failed) before resolving — no hand-rolled poll loop.
+     */
+    confirm?: boolean;
 }
 interface PayInput {
     /** USD decimal string ("4.99"). Rejected: ≤ 0, non-numeric, > 2 dp. */
@@ -150,6 +198,7 @@ interface AgentWallet {
 interface AgentFundResult {
     agent: AgentWallet;
     funding: {
+        id: string;
         amount: string;
         status: string;
         txHash: string | null;
@@ -420,9 +469,10 @@ interface RoundState {
     roundKey: string;
     status: RoundStatus;
     entryAmount: string;
-    /** Payable pool in USD (from chain after lock); may be "0.00" while open. */
-    pool: string;
-    entrants: number;
+    /** Payable pool in USD from chain after reconcile; **`null` until reconciled** (never a fabricated "0.00"). */
+    pool: string | null;
+    /** Entrant count from chain after reconcile; **`null` until reconciled**. */
+    entrants: number | null;
     payout: PayoutRule;
     closeAt?: string;
     openTxHash?: `0x${string}`;
@@ -499,4 +549,4 @@ declare class ConfigError extends PlaymosError {
     constructor(message: string, detail?: Record<string, unknown>);
 }
 
-export { type AgentWallet as A, type PlaymosErrorCode as B, ConfigError as C, type RoundStatus as D, type EscrowHoldInput as E, type WalletConfig as F, type GasConfig as G, WalletConnectionError as H, InsufficientGasError as I, type WalletConnector as J, type WebhookEventType as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type PlaymosConfig as P, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, type VerifyResult as V, type WebhookEvent as W, 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 TransferInput as k, type AgentEconomyConfig as l, ApiError as m, AuthError as n, type ContractConfig as o, type Eip1193Provider as p, type GasMode as q, InvalidAmountError as r, type ListingStatus as s, type MarketplaceItem as t, type MarketplaceSale as u, MissingFieldError as v, PaymentFailedError as w, type PaymentStatus as x, type PayoutRule as y, PlaymosError as z };
+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 };

package/dist/index.cjs

@@ -222,8 +222,37 @@ function validateMetadata(metadata) {
 }
 
 // src/http.ts
-function createHttpClient(baseUrl, apiKey) {
+function resolveRetry(retry) {
+  const off = { maxRetries: 0, baseDelayMs: 500, maxDelayMs: 2e4 };
+  if (retry === false) return off;
+  const r = retry === true || retry === void 0 ? {} : retry;
+  return {
+    maxRetries: r.maxRetries ?? 2,
+    baseDelayMs: r.baseDelayMs ?? 500,
+    maxDelayMs: r.maxDelayMs ?? 2e4
+  };
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function backoffMs(res, attempt, cfg) {
+  const header = res.headers.get("retry-after");
+  if (header) {
+    const secs = Number(header);
+    let ms;
+    if (Number.isFinite(secs)) {
+      ms = secs * 1e3;
+    } else {
+      const at = Date.parse(header);
+      ms = Number.isNaN(at) ? NaN : at - Date.now();
+    }
+    if (Number.isFinite(ms) && ms >= 0) return Math.min(ms, cfg.maxDelayMs);
+  }
+  const expo = cfg.baseDelayMs * 2 ** attempt;
+  const jitter = Math.random() * cfg.baseDelayMs;
+  return Math.min(expo + jitter, cfg.maxDelayMs);
+}
+function createHttpClient(baseUrl, apiKey, retry) {
   const base = baseUrl.replace(/\/+$/, "");
+  const cfg = resolveRetry(retry);
   async function send(url, init) {
     try {
       return await fetch(url, init);
@@ -235,6 +264,14 @@ function createHttpClient(baseUrl, apiKey) {
       );
     }
   }
+  async function sendWithRetry(url, init) {
+    let res = await send(url, init);
+    for (let attempt = 0; res.status === 429 && attempt < cfg.maxRetries; attempt++) {
+      await sleep(backoffMs(res, attempt, cfg));
+      res = await send(url, init);
+    }
+    return res;
+  }
   async function handle(res) {
     let text;
     try {
@@ -267,11 +304,11 @@ function createHttpClient(baseUrl, apiKey) {
         authorization: `Bearer ${apiKey}`
       };
       if (opts?.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
-      const res = await send(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
+      const res = await sendWithRetry(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
       return handle(res);
     },
     async get(path) {
-      const res = await send(`${base}${path}`, {
+      const res = await sendWithRetry(`${base}${path}`, {
         method: "GET",
         headers: { authorization: `Bearer ${apiKey}` }
       });
@@ -697,7 +734,12 @@ var Playmos = class {
       fund: (input) => {
         requireField(input?.agentId, "agentId");
         validateAmount(input.amount);
-        return this.http.post(`/agents/wallets/${encodeURIComponent(input.agentId)}/fund`, { amount: input.amount });
+        const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+        return this.http.post(
+          `/agents/wallets/${encodeURIComponent(input.agentId)}/fund`,
+          { amount: input.amount, idempotencyKey },
+          { idempotencyKey }
+        );
       },
       /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
       pay: (input) => {
@@ -726,7 +768,7 @@ var Playmos = class {
             { feeBps: input.feeBps }
           );
         }
-        const feeSink = feeBps > 0 ? requireAddressField(input.feeSink, "feeSink") : input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
+        const feeSink = input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
         const resolver = input.resolver === void 0 ? void 0 : requireAddressField(input.resolver, "resolver");
         const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
         const feeMicro = amountMicro * BigInt(feeBps) / 10000n;
@@ -838,19 +880,51 @@ var Playmos = class {
       }
     };
     /**
-     * `transfers` — read-back / confirmation for a prior `transfer()` (issue #27).
-     * Poll when POST returned `status: "settling"`; reconciles against chain (incl. gasless agent path).
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
+     * `get` reconciles once against chain truth; `wait` polls it to a terminal state
+     * for you (no hand-rolled loop). Both cover the gasless agent path.
      */
     this.transfers = {
+      /** One-shot reconcile of a transfer against chain truth. */
       get: async (transferId) => {
         requireField(transferId, "transferId");
-        const res = await this.http.get(`/transfers/${encodeURIComponent(transferId)}`);
+        const res = await this.http.get(
+          `/transfers/${encodeURIComponent(transferId)}`
+        );
         return res.transfer;
+      },
+      /**
+       * Block until a transfer reaches a terminal state — `settled` or `failed` —
+       * instead of hand-rolling a poll loop (#47). Polls `transfers.get(id)` every
+       * `intervalMs` (default 1000) until terminal, then RESOLVES with the final
+       * reconcile. Throws a typed `ApiError` (`detail.timeout`) if neither
+       * `timeoutMs` (default 30000) nor `maxAttempts` (default 40) is reached first.
+       *
+       * A `failed` transfer is a legitimate outcome, so it RESOLVES (status
+       * "failed") — inspect `result.status`; it does not throw.
+       */
+      wait: async (transferId, opts) => {
+        requireField(transferId, "transferId");
+        const intervalMs = opts?.intervalMs ?? 1e3;
+        const timeoutMs = opts?.timeoutMs ?? 3e4;
+        const maxAttempts = opts?.maxAttempts ?? 40;
+        const deadline = Date.now() + timeoutMs;
+        let last;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+          last = await this.transfers.get(transferId);
+          if (last.status === "settled" || last.status === "failed") return last;
+          if (Date.now() + intervalMs > deadline) break;
+          await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        throw new ApiError(
+          `Timed out waiting for transfer ${transferId} to settle (last status: ${last?.status ?? "unknown"}). It may still settle \u2014 re-check with playmos.transfers.get("${transferId}").`,
+          { transferId, timeout: true, lastStatus: last?.status ?? "unknown" }
+        );
       }
     };
     this.config = config;
     this.env = resolveEnv(config.apiKey, config.network, config.apiBaseUrl);
-    this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey);
+    this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
   }
   /** Connect the player's wallet and return their address. */
   async connect() {
@@ -1000,12 +1074,13 @@ var Playmos = class {
    * Retries are safe: pass the same `idempotencyKey` and a re-call NEVER broadcasts a second tx —
    * it returns the cached result (`idempotentReplay: true`).
    *
-   * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, call
-   * `playmos.transfers.get(id)` until settled/failed. BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
+   * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, either call
+   * `playmos.transfers.wait(id)`, or pass `{ confirm: true }` here to block until terminal in one
+   * call (#47). BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
    *
    * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
    */
-  async transfer(input) {
+  async transfer(input, opts) {
     const amountMicro = validateAmount(input.amount);
     const from = input.from === void 0 ? void 0 : partyRef(input.from, "from");
     const to = partyRef(input.to, "to");
@@ -1016,12 +1091,7 @@ var Playmos = class {
         { feeBps: input.feeBps }
       );
     }
-    let feeSink;
-    if (feeBps > 0) {
-      feeSink = requireAddressField(input.feeSink, "feeSink");
-    } else if (input.feeSink !== void 0) {
-      feeSink = requireAddressField(input.feeSink, "feeSink");
-    }
+    const feeSink = input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
     const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
     const res = await this.http.post(
       "/transfers",
@@ -1030,7 +1100,7 @@ var Playmos = class {
     );
     const t = res.transfer;
     const feeMicro = amountMicro * BigInt(feeBps) / 10000n;
-    return {
+    const out = {
       id: t.id,
       status: t.status,
       txHash: t.txHash,
@@ -1046,6 +1116,12 @@ var Playmos = class {
       memo: t.memo ?? input.memo ?? null,
       idempotentReplay: Boolean(t.idempotentReplay)
     };
+    if (opts?.confirm && out.status === "settling") {
+      const final = await this.transfers.wait(out.id, opts);
+      out.status = final.status;
+      out.txHash = final.txHash ?? out.txHash;
+    }
+    return out;
   }
   /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
   async verify(paymentId) {