@playmos/sdk 0.1.6 → 0.3.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { InvalidAmountError, ConfigError, MissingFieldError, AuthError, WalletConnectionError, InsufficientGasError, PaymentFailedError, ApiError } from './chunk-B7SHFZYY.js';
+import { InvalidAmountError, ConfigError, ApiError, MissingFieldError, AuthError, WalletConnectionError, InsufficientGasError, PaymentFailedError } from './chunk-B7SHFZYY.js';
 export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, PaymentFailedError, PlaymosError, WalletConnectionError } from './chunk-B7SHFZYY.js';
 import { encodeFunctionData, numberToHex, keccak256, toBytes } from 'viem';
 
@@ -163,8 +163,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);
@@ -176,6 +205,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 {
@@ -208,11 +245,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}` }
       });
@@ -301,6 +338,17 @@ 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",
@@ -311,6 +359,40 @@ 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",
@@ -320,6 +402,13 @@ var prizePoolAbi = [
       { name: "identity", type: "bytes32" }
     ],
     outputs: [{ type: "bool" }]
+  },
+  {
+    type: "function",
+    name: "withdraw",
+    stateMutability: "nonpayable",
+    inputs: [],
+    outputs: [{ name: "amount", type: "uint256" }]
   }
 ];
 async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
@@ -455,17 +544,42 @@ function mockEntryPayment(args) {
 }
 
 // src/client.ts
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+function requireAddressField(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new MissingFieldError(field);
+  }
+  if (!ADDRESS_RE.test(value)) {
+    throw new ConfigError(
+      `${field} must be a 0x-prefixed 20-byte wallet address (Phase 1a transfers settle server-held wallets), got: ${JSON.stringify(value)}`,
+      { field, value }
+    );
+  }
+  return value.toLowerCase();
+}
+function partyRef(value, field) {
+  if (typeof value !== "string" || value.trim() === "") throw new MissingFieldError(field);
+  if (value.startsWith("0x")) return requireAddressField(value, field);
+  return value;
+}
 var IAP_FEE_BPS = 100;
 var POOL_BPS = 6e3;
 var SEED_BPS = 3e3;
 var RAKE_BPS = 1e3;
 var Playmos = class {
   constructor(config) {
+    /**
+     * Webhook helpers. Signature verification is **server-only** (Node `crypto`) and
+     * lives on `@playmos/sdk/server` so browser bundlers never see `node:crypto` (#9).
+     *
+     *   import { verifyWebhook } from "@playmos/sdk/server";
+     *   const event = verifyWebhook(rawBody, req.headers["x-playmos-signature"], secret);
+     */
     this.webhooks = {
       /**
-       * Webhook verification is server-only (it uses node:crypto) and no longer
-       * ships in the browser entry (issue #9). On a backend, import it directly:
-       *   import { verifyWebhook } from "@playmos/sdk/server";
+       * @deprecated Use `import { verifyWebhook } from "@playmos/sdk/server"` instead.
+       * Throws if called — kept as a discoverable pointer so call sites fail loudly
+       * with a fix instruction rather than a silent missing method.
        */
       verify: (_rawBody, _signatureHeader, _secret) => {
         throw new ConfigError(
@@ -480,23 +594,278 @@ var Playmos = class {
       /** Create a Bridge KYC onboarding link (fiat payout). */
       createOnboardingLink: () => this.http.post("/payouts/onboarding_link", {})
     };
+    /**
+     * Skill/contest **round lifecycle** (issue #13) — closes the enterRound loop.
+     *
+     * Scores never leave the studio. Flow:
+     *   rounds.open → players enterRound → studio scores → rounds.lock →
+     *   rounds.settle({ ranking }) → contract pays winners.
+     *
+     * Operator txs are signed by the Playmos service (OPERATOR_ROLE key).
+     */
+    this.rounds = {
+      open: async (input) => {
+        requireField(input?.gameId, "gameId");
+        requireField(input?.roundId, "roundId");
+        requireField(input?.entryAmount, "entryAmount");
+        if (!input?.payout || typeof input.payout !== "object") {
+          throw new ConfigError("payout rule is required (winner-take-all | top-n | custom)");
+        }
+        validateAmount(input.entryAmount);
+        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;
+      },
+      lock: async (input) => {
+        requireField(input?.roundId, "roundId");
+        const { round } = await this.http.post(
+          `/rounds/${encodeURIComponent(input.roundId)}/lock`,
+          { gameId: input.gameId }
+        );
+        return round;
+      },
+      settle: async (input) => {
+        requireField(input?.roundId, "roundId");
+        if (!input?.results) throw new ConfigError("results are required (ranking or winners)");
+        const { settle } = await this.http.post(
+          `/rounds/${encodeURIComponent(input.roundId)}/settle`,
+          { gameId: input.gameId, results: input.results }
+        );
+        return settle;
+      },
+      get: async (input) => {
+        requireField(input?.roundId, "roundId");
+        const { round } = await this.http.get(
+          `/rounds/${encodeURIComponent(input.roundId)}`
+        );
+        return round;
+      }
+    };
+    /**
+     * `agents` — assign wallets to the NPCs YOUR game already owns, so they can transact USDC in your economy.
+     * The game creates the NPCs; the SDK only creates the WALLET for a game-supplied id. Engine-agnostic
+     * (Unity/Unreal/Godot/web all call the same REST). Requires a secret test key (`sk_test_`) on the sandbox.
+     */
     this.agents = {
-      /** Assign a wallet to any identity (incl. an AI NPC). Idempotent by agentId. */
-      createWallet: (input) => {
+      /** Assign (or return) the wallet for a game NPC id. Idempotent — safe to call wherever your NPCs spawn. */
+      createWallet: async (input) => {
+        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) => {
+        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 () => {
+        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) => {
         requireField(input?.agentId, "agentId");
-        return this.http.post("/agents/wallets", { agentId: input.agentId });
+        validateAmount(input.amount);
+        const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+        return this.http.post(
+          `/agents/wallets/${encodeURIComponent(input.agentId)}/fund`,
+          { amount: input.amount, idempotencyKey },
+          { idempotencyKey }
+        );
       },
-      /** Agent↔agent USDC transfer; the configured taxBps is skimmed to Playmos. */
+      /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
       pay: (input) => {
         requireField(input?.from, "from");
         requireField(input?.to, "to");
-        validateAmount(input?.amount);
-        return this.http.post("/agents/pay", input);
+        return this.transfer({ from: input.from, to: input.to, amount: input.amount, feeBps: input.feeBps, feeSink: input.feeSink });
+      }
+    };
+    /**
+     * `escrow` — the fair-exchange primitive (Phase 2): lock the payer's USDC on-chain the instant a deal
+     * opens (`hold`), then move it exactly once — `release` (→ payee, fee skimmed) XOR `refund` (→ payer,
+     * 100%). The contract holds the funds trustlessly; YOUR game decides the rule (who resolves, and when).
+     * A `deadline` auto-refund guarantees funds never get stuck. Pass the `hold` result's `id` to the rest.
+     */
+    this.escrow = {
+      /** Open a deal: lock `amount` of the payer's USDC into the on-chain escrow. Retries are idempotent.
+       *  `async` so client-side validation surfaces as a rejected promise, not a synchronous throw. */
+      hold: async (input) => {
+        const amountMicro = validateAmount(input.amount);
+        const payer = input.payer === void 0 ? void 0 : requireAddressField(input.payer, "payer");
+        const payee = requireAddressField(input.payee, "payee");
+        const feeBps = input.feeBps ?? 0;
+        if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+          throw new ConfigError(
+            `feeBps must be an integer in [0, 10000] (fee is taken at release only; refunds are 100%), got: ${JSON.stringify(input.feeBps)}`,
+            { feeBps: input.feeBps }
+          );
+        }
+        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;
+        const { escrow } = await this.http.post(
+          "/escrows",
+          {
+            payer,
+            payee,
+            amount: input.amount,
+            feeBps,
+            feeSink,
+            resolver,
+            expiresIn: input.expiresIn,
+            deadline: input.deadline,
+            memo: input.memo,
+            idempotencyKey
+          },
+          { idempotencyKey }
+        );
+        return {
+          ...escrow,
+          payee: escrow.payee ?? payee,
+          amount: escrow.amount ?? formatMicroToUsd(amountMicro),
+          feeBps: escrow.feeBps ?? feeBps,
+          feeSink: escrow.feeSink ?? feeSink ?? null,
+          resolver: escrow.resolver ?? resolver ?? null,
+          feeAtRelease: escrow.feeAtRelease ?? formatMicroToUsd(feeMicro),
+          netAtRelease: escrow.netAtRelease ?? formatMicroToUsd(amountMicro - feeMicro),
+          idempotentReplay: Boolean(escrow.idempotentReplay)
+        };
+      },
+      /** Release a held deal to the payee (fee skimmed). `escrowId` is the `hold` result's `id`. */
+      release: async (input) => {
+        requireField(input?.escrowId, "escrowId");
+        const { escrow } = await this.http.post(`/escrows/${encodeURIComponent(input.escrowId)}/release`, {});
+        return escrow;
+      },
+      /** Refund a held deal to the payer (100%, untaxed). `escrowId` is the `hold` result's `id`. */
+      refund: async (input) => {
+        requireField(input?.escrowId, "escrowId");
+        const { escrow } = await this.http.post(`/escrows/${encodeURIComponent(input.escrowId)}/refund`, {});
+        return escrow;
+      },
+      /** Verify a deal's on-chain state (reconciles a `settling` hold wedged by a crash). */
+      get: async (escrowId) => {
+        requireField(escrowId, "escrowId");
+        const { escrow } = await this.http.get(`/escrows/${encodeURIComponent(escrowId)}`);
+        return escrow;
+      }
+    };
+    /**
+     * `marketplace` — list an item, and the seller is paid ONLY when it's bought (Phase 3a, off-chain items).
+     * Built on `escrow`: `buy` locks the buyer's USDC on-chain, `confirm` (after your game server delivers the
+     * item) pays the seller, and a no-delivery/timeout `refund`s the buyer. `deliver: true` on `buy` collapses
+     * lock+pay into one call when your server delivers synchronously. On-chain items are Phase 3b.
+     */
+    this.marketplace = {
+      /** List an off-chain item for sale. No money moves. Idempotent on `idempotencyKey`. */
+      list: async (input) => {
+        if (!input?.item || input.item.kind !== "offchain") {
+          throw new ConfigError('marketplace.list requires item = { kind: "offchain", sku: "<your-item-id>" } (on-chain items are Phase 3b)', { item: input?.item });
+        }
+        validateAmount(input.price);
+        const seller = requireAddressField(input.seller, "seller");
+        const feeBps = input.feeBps;
+        if (feeBps !== void 0 && (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4)) {
+          throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+        }
+        const feeSink = input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
+        const { listing } = await this.http.post("/listings", {
+          seller,
+          item: input.item,
+          price: input.price,
+          feeBps,
+          feeSink,
+          deliveryWindow: input.deliveryWindow,
+          expiresIn: input.expiresIn,
+          gameId: input.gameId,
+          idempotencyKey: input.idempotencyKey
+        });
+        return listing;
+      },
+      /** Buy a listing: lock the buyer's USDC in escrow. Pass `deliver: true` to also pay the seller in one call. */
+      buy: async (input) => {
+        requireField(input?.listingId, "listingId");
+        const buyer = input.buyer === void 0 ? void 0 : requireAddressField(input.buyer, "buyer");
+        return this.http.post(`/listings/${encodeURIComponent(input.listingId)}/buy`, { buyer, deliver: input.deliver === true });
+      },
+      /** Confirm delivery → the seller is paid (release), fee skimmed. */
+      confirm: async (input) => {
+        requireField(input?.listingId, "listingId");
+        return this.http.post(`/listings/${encodeURIComponent(input.listingId)}/confirm`, {});
+      },
+      /** Refund the buyer 100% (seller couldn't deliver / dispute / timeout). */
+      refund: async (input) => {
+        requireField(input?.listingId, "listingId");
+        return this.http.post(`/listings/${encodeURIComponent(input.listingId)}/refund`, {});
+      },
+      /** Delist an unsold listing (pure DB, no tx). */
+      cancel: async (input) => {
+        requireField(input?.listingId, "listingId");
+        const { listing } = await this.http.post(`/listings/${encodeURIComponent(input.listingId)}/cancel`, {});
+        return listing;
+      },
+      /** Fetch a listing + its on-chain-verified sale status. */
+      get: async (listingId) => {
+        requireField(listingId, "listingId");
+        return this.http.get(`/listings/${encodeURIComponent(listingId)}`);
+      }
+    };
+    /**
+     * `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)}`
+        );
+        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() {
@@ -568,9 +937,11 @@ var Playmos = class {
     const playmosPay = intent.clientParams?.contractAddress ?? this.config.contracts?.playmosPay;
     const studio = intent.clientParams?.studio ?? input.studio;
     if (!playmosPay) throw new ConfigError("No PlaymosPay contract address (service intent + config.contracts both empty).");
-    if (!studio) throw new ConfigError("No studio payout address for this payment.");
+    if (!studio) throw new ConfigError("No studio payout address for this payment (service must return clientParams.studio).");
+    if (!intent.clientParams?.studio && input.studio) ;
     const amountUnits = this.resolveUnits(intent, amountMicro);
-    const calls = buildIapCalls({ usdc, playmosPay, paymentId: intent.payment.id, studio, amountUnits });
+    const paymentId = intent.clientParams?.paymentId ?? intent.payment.id;
+    const calls = buildIapCalls({ usdc, playmosPay, paymentId, studio, amountUnits });
     const { id: callsId } = await sendCalls(provider, from, this.env.chainId, calls, this.sponsorUrl(intent));
     const { txHash } = await waitForCalls(provider, callsId);
     return this.settle(intent.payment.id, txHash);
@@ -622,8 +993,9 @@ var Playmos = class {
     const usdc = intent.clientParams?.usdc ?? this.config.contracts?.usdc ?? USDC_ADDRESS[this.env.network];
     const prizePool = intent.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
     if (!prizePool) throw new ConfigError("No PrizePool contract address for this game (service intent + config.contracts both empty).");
-    const roundKey = input.roundKey ?? intent.clientParams?.roundKey ?? intent.clientParams?.roundId ?? `${input.gameId}:${input.roundId}`;
-    const identity = input.identity ?? intent.clientParams?.identity ?? `${from}#${idempotencyKey}`;
+    const roundKey = intent.clientParams?.roundKey ?? intent.clientParams?.roundId ?? input.roundKey ?? intent.payment.roundId ?? input.roundId;
+    if (!roundKey) throw new ConfigError("No roundKey/roundId for enterRound (service clientParams missing).");
+    const identity = intent.clientParams?.identity ?? input.identity ?? intent.payment.identity ?? `${from}#${idempotencyKey}`;
     const amountUnits = this.resolveUnits(intent, amountMicro);
     const calls = buildEntryCalls({ usdc, prizePool, roundKey, identity, amountUnits });
     const { id: callsId } = await sendCalls(provider, from, this.env.chainId, calls, this.sponsorUrl(intent));
@@ -632,6 +1004,66 @@ var Playmos = class {
     payment.identity = identity;
     return payment;
   }
+  /**
+   * `transfer` — the value-movement base primitive (Phase 1a): move USDC from one wallet to another,
+   * with a per-call fee. The GAME LOGIC is the authority — you already decided the move is valid — so
+   * this is a direct, unconditional push (use `escrow`/`marketplace` when a trust boundary needs fair
+   * exchange). The service settles it through the protocol-agnostic settlement core (idempotent,
+   * reserve-before-broadcast) and the on-chain PlaymosTransfer / PlaymosTransferAuth contracts.
+   *
+   * Fee is per-call: `feeBps` 0–10000 (+ `feeSink`). `feeBps: 0` is an untaxed reward/faucet transfer.
+   * 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`, 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, opts) {
+    const amountMicro = validateAmount(input.amount);
+    const from = input.from === void 0 ? void 0 : partyRef(input.from, "from");
+    const to = partyRef(input.to, "to");
+    const feeBps = input.feeBps ?? 0;
+    if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+      throw new ConfigError(
+        `feeBps must be an integer in [0, 10000] (0 = untaxed reward/faucet; 500 = 5%; 10000 = 100%), got: ${JSON.stringify(input.feeBps)}`,
+        { feeBps: input.feeBps }
+      );
+    }
+    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",
+      { from, to, amount: input.amount, memo: input.memo, feeBps, feeSink, idempotencyKey },
+      { idempotencyKey }
+    );
+    const t = res.transfer;
+    const feeMicro = amountMicro * BigInt(feeBps) / 10000n;
+    const out = {
+      id: t.id,
+      status: t.status,
+      txHash: t.txHash,
+      from: t.from,
+      // the service's resolved payer address (omitted when it's the redacted treasury signer)
+      to: t.to,
+      // the service's resolved payee address
+      amount: t.amount ?? formatMicroToUsd(amountMicro),
+      fee: t.fee ?? formatMicroToUsd(feeMicro),
+      net: t.net ?? formatMicroToUsd(amountMicro - feeMicro),
+      feeBps: t.feeBps ?? feeBps,
+      feeSink: t.feeSink ?? feeSink ?? null,
+      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) {
     requireField(paymentId, "paymentId");
@@ -723,6 +1155,30 @@ function previewIapSplit(amount) {
   const { feeMicro, netMicro } = computeIapSplit(micro, IAP_FEE_BPS);
   return { amount: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(netMicro) };
 }
+function previewTransferSplit(amount, feeBps) {
+  const micro = validateAmount(amount);
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+  }
+  const feeMicro = micro * BigInt(feeBps) / 10000n;
+  return { amount: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(micro - feeMicro), feeBps };
+}
+function previewEscrowFee(amount, feeBps) {
+  const micro = validateAmount(amount);
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+  }
+  const feeMicro = micro * BigInt(feeBps) / 10000n;
+  return { amount: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(micro - feeMicro), feeBps };
+}
+function previewMarketplaceSplit(price, feeBps) {
+  const micro = validateAmount(price);
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+  }
+  const feeMicro = micro * BigInt(feeBps) / 10000n;
+  return { price: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(micro - feeMicro), feeBps };
+}
 function previewPoolSplit(amount) {
   const micro = validateAmount(amount);
   const { poolMicro, seedMicro, rakeMicro } = computePoolSplit(micro, POOL_BPS, SEED_BPS, RAKE_BPS);
@@ -734,6 +1190,205 @@ function previewPoolSplit(amount) {
   };
 }
 
-export { CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, Playmos, USDC_ADDRESS, USDC_DECIMALS, computeIapSplit, computePoolSplit, formatMicroToUsd, parseUsdToMicro, prefixedId, previewIapSplit, previewPoolSplit, ulid };
+// src/payout.ts
+var PayoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "payout_invalid";
+    this.name = "PayoutError";
+  }
+};
+var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var BPS = 10000n;
+function requireAddress(w, i) {
+  if (!ADDRESS_RE2.test(w)) {
+    throw new PayoutError(`ranking[${i}] must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(w)}`);
+  }
+  return w.toLowerCase();
+}
+function parseUsdToMicroLoose(amount) {
+  if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
+    throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
+  }
+  const [wholeRaw, frac = ""] = amount.trim().split(".");
+  const whole = wholeRaw ?? "0";
+  const fracPadded = (frac + "000000").slice(0, 6);
+  const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
+  if (micro <= 0n) throw new PayoutError(`amount must be > 0, got: ${JSON.stringify(amount)}`);
+  return micro;
+}
+function computePayout(pool, ranking, rule) {
+  if (typeof pool !== "bigint" || pool <= 0n) {
+    throw new PayoutError(`pool must be a positive bigint (micro-USDC), got: ${String(pool)}`);
+  }
+  if (!Array.isArray(ranking) || ranking.length === 0) {
+    throw new PayoutError("ranking must be a non-empty array of wallets (best-first)");
+  }
+  const wallets = ranking.map((w, i) => requireAddress(w, i));
+  const seen = /* @__PURE__ */ new Set();
+  for (const w of wallets) {
+    if (seen.has(w)) throw new PayoutError(`duplicate wallet in ranking: ${w}`);
+    seen.add(w);
+  }
+  if (rule.kind === "winner-take-all") {
+    return [{ wallet: wallets[0], amount: pool }];
+  }
+  if (rule.kind === "top-n") {
+    const splits = rule.splitsBps;
+    if (!Array.isArray(splits) || splits.length === 0) {
+      throw new PayoutError("top-n splitsBps must be a non-empty array");
+    }
+    if (splits.length > wallets.length) {
+      throw new PayoutError(
+        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
+      );
+    }
+    let sumBps = 0;
+    for (const b of splits) {
+      if (!Number.isInteger(b) || b <= 0 || b > 1e4) {
+        throw new PayoutError(`each splitsBps entry must be an integer in (0, 10000], got: ${b}`);
+      }
+      sumBps += b;
+    }
+    if (sumBps !== 1e4) {
+      throw new PayoutError(`splitsBps must sum to 10000, got ${sumBps}`);
+    }
+    const out = [];
+    let allocated = 0n;
+    for (let i = 0; i < splits.length; i++) {
+      const amt = pool * BigInt(splits[i]) / BPS;
+      out.push({ wallet: wallets[i], amount: amt });
+      allocated += amt;
+    }
+    const remainder = pool - allocated;
+    if (remainder < 0n) throw new PayoutError("internal: allocated more than pool");
+    out[0] = { wallet: out[0].wallet, amount: out[0].amount + remainder };
+    const filtered = out.filter((x) => x.amount > 0n);
+    if (filtered.length === 0) throw new PayoutError("payout produced no positive amounts");
+    const total = filtered.reduce((s, x) => s + x.amount, 0n);
+    if (total !== pool) throw new PayoutError(`internal: sum ${total} != pool ${pool}`);
+    return filtered;
+  }
+  if (rule.kind === "custom") {
+    const amounts = rule.amounts;
+    if (!Array.isArray(amounts) || amounts.length === 0) {
+      throw new PayoutError("custom amounts must be a non-empty array of USD strings");
+    }
+    if (amounts.length > wallets.length) {
+      throw new PayoutError(
+        `custom amounts has ${amounts.length} entries but ranking only has ${wallets.length}`
+      );
+    }
+    const out = [];
+    let total = 0n;
+    for (let i = 0; i < amounts.length; i++) {
+      const amt = parseUsdToMicroLoose(amounts[i]);
+      out.push({ wallet: wallets[i], amount: amt });
+      total += amt;
+    }
+    if (total !== pool) {
+      throw new PayoutError(
+        `custom amounts sum to ${total} micro-USDC but pool is ${pool} \u2014 must match exactly`
+      );
+    }
+    return out;
+  }
+  throw new PayoutError(`unknown payout rule kind: ${JSON.stringify(rule.kind)}`);
+}
+
+// src/settlement.ts
+var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
+var DEFAULT_TTL_MS = 15 * 60 * 1e3;
+function requireAddress2(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new MissingFieldError(field);
+  }
+  if (!ADDRESS_RE3.test(value)) {
+    throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
+      field,
+      value
+    });
+  }
+  return value;
+}
+function requireNetwork(value) {
+  if (value === "base" || value === "base-sepolia") return value;
+  throw new ConfigError(`Unknown network: ${JSON.stringify(value)}. Expected one of ${Object.keys(CHAIN_ID).join(", ")}.`, {
+    field: "network",
+    value
+  });
+}
+function createPaymentRequirement(input) {
+  const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
+  const payTo = requireAddress2(input.payTo, "payTo");
+  const network = requireNetwork(input.network);
+  const asset = input.asset ?? "USDC";
+  if (asset !== "USDC") {
+    throw new ConfigError(`Unsupported asset: ${JSON.stringify(asset)}. Only "USDC" is supported.`, { asset });
+  }
+  parseUsdToMicro(input.amount);
+  const expiresAt = input.expiresAt ?? new Date(now.getTime() + (input.expiresInMs ?? DEFAULT_TTL_MS)).toISOString();
+  const req = {
+    id: input.id ?? prefixedId("preq"),
+    payTo,
+    amount: input.amount,
+    asset,
+    network,
+    expiresAt
+  };
+  if (input.terms !== void 0) req.terms = input.terms;
+  return req;
+}
+function serializePaymentRequirement(req) {
+  const body = {
+    id: req.id,
+    payTo: req.payTo,
+    amount: req.amount,
+    asset: req.asset,
+    network: req.network,
+    expiresAt: req.expiresAt
+  };
+  if (req.terms !== void 0) body.terms = req.terms;
+  return body;
+}
+function parsePaymentRequirement(input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new ConfigError("PaymentRequirement must be a JSON object.", { input });
+  }
+  const o = input;
+  const id = o.id;
+  if (typeof id !== "string" || id.trim() === "") throw new MissingFieldError("id");
+  if (o.asset !== "USDC") {
+    throw new ConfigError(`PaymentRequirement.asset must be "USDC", got: ${JSON.stringify(o.asset)}.`, {
+      asset: o.asset
+    });
+  }
+  const payTo = requireAddress2(o.payTo, "payTo");
+  const network = requireNetwork(o.network);
+  if (typeof o.amount !== "string") throw new InvalidAmountError(o.amount);
+  parseUsdToMicro(o.amount);
+  if (typeof o.expiresAt !== "string" || o.expiresAt.trim() === "") throw new MissingFieldError("expiresAt");
+  if (o.terms !== void 0 && typeof o.terms !== "string") {
+    throw new ConfigError("PaymentRequirement.terms must be a string when present.", { terms: o.terms });
+  }
+  const req = {
+    id,
+    payTo,
+    amount: o.amount,
+    asset: "USDC",
+    network,
+    expiresAt: o.expiresAt
+  };
+  if (o.terms !== void 0) req.terms = o.terms;
+  return req;
+}
+function isWalletSignatureAuthorization(auth) {
+  return auth.kind === "wallet-signature";
+}
+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, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map