paygate 5.0.0 → 5.3.0

package/README.md

@@ -129,6 +129,26 @@ The agent-side [`payagent`](https://www.npmjs.com/package/payagent) CLI and SDK
 | `facilitatorUrl` | No | Manifest value | Compatibility override. In v3, merchant capabilities are authoritative. |
 | `timeout` | No | `30000` | ArisPay/facilitator call timeout in ms. |
 | `cacheTtlMs` | No | `300000` | Merchant capability cache TTL. |
+| `selfSettle` | No | — | `{ privateKey, rpcUrl? }`. Submit settlements from your own funded key: verification runs against the facilitator (free), then the SDK submits the EIP-3009 `transferWithAuthorization` itself. You pay chain gas (~$0.001/settle on Base) and nobody else — no facilitator fee, no subsidy that ends. The key is any funded EOA; it pays gas only and never receives or holds customer funds. Replay protection is on-chain (the EIP-3009 nonce). Defaults to public Base RPCs; set `rpcUrl` for other networks or your own provider. |
+
+### Self-settle
+
+```ts
+const pw = paygate({
+  merchantId: "m_123",
+  selfSettle: { privateKey: process.env.SETTLE_KEY! }, // funded with a few $ of Base ETH
+});
+```
+
+Requires the optional peer dependency `ethers` (v6): `npm install ethers`. The
+facilitator path never loads it.
+
+Verified end-to-end against Circle's real USDC on Base Sepolia (2026-07-19): a
+signed EIP-3009 authorization settled on-chain via `submitSelfSettle` — 0.01
+USDC transferred, gas paid by the self-settle key — tx
+[`0xe151fe05…dda4cb0`](https://sepolia.basescan.org/tx/0xe151fe058f2e03f74f7a6ec4bea95224515592bf3bee8f689b37caf04dda4cb0)
+(`AuthorizationUsed` + `Transfer` events). This confirms Circle USDC accepts the
+9-arg split-signature `transferWithAuthorization` form the SDK submits.
 
 ### Compatibility mode
 

package/dist/core.d.ts

@@ -13,6 +13,34 @@
 export declare const DEFAULT_FACILITATOR = "https://facilitator.arispay.app";
 export declare const DEFAULT_API_URL = "https://api.arispay.app";
 export declare const CAPABILITY_CACHE_TTL_MS: number;
+export type PaygateCurrency = "USD" | "EUR";
+/**
+ * Build the response headers for an x402 402 challenge in the canonical
+ * wire format observed across Bazaar-listed endpoints.
+ *
+ * - `payment-required: <base64(JSON)>` — primary, what 95.3% of live
+ *   x402 endpoints emit (audited 2026-04-30; see
+ *   docs/x402-wire-format-audit.md). base64 also dodges the Latin1
+ *   `ByteString` constraint on Node response headers, so a description
+ *   containing an em dash or smart quote no longer 500s the response.
+ *
+ * - `X-Payment-Requirements: <raw JSON of {x402Version, accepts}>` —
+ *   paygate's pre-v5.1 header name, kept for one minor cycle as a
+ *   deprecated alias so existing `payagent` consumers (and any other
+ *   client that reads our legacy emit) keep working. Will be removed
+ *   in paygate v6. Strip non-printable-ASCII defensively in case a
+ *   description picks up Unicode in the meantime.
+ *
+ * - `WWW-Authenticate: x402` — RFC 7235 challenge advertisement.
+ *
+ * - `Access-Control-Expose-Headers` — without this, browser-based
+ *   agents (Anthropic MCP-in-browser, Chrome WebMCP, …) can't read
+ *   `payment-required` cross-origin. 80% of live endpoints don't
+ *   bother; we do.
+ *
+ * Exported for tests; consumers should not rely on this signature.
+ */
+export declare function buildChallengeHeaders(challengeBody: Record<string, unknown>, accepts: X402PaymentAccept[]): Record<string, string>;
 /**
  * v3 config.
  *
@@ -37,12 +65,39 @@ export interface PaygateConfig {
      */
     network?: string;
     /**
-     * USDC contract address. Auto-derived from network if omitted.
-     * Ignored in the v3 path (merchant manifest is authoritative).
+     * Settlement currency. Default `"USD"` (USDC). `"EUR"` settles in Circle
+     * EURC; `priceCents` then means integer EUR cents (the cents → 6-decimals
+     * conversion factor is the same 10^4 for both assets).
+     *
+     * v2-shim path: resolves the EURC address for the network (Base mainnet +
+     * Base Sepolia known; other networks need an explicit `asset`).
+     * v3 path: selects the merchant-manifest rail whose `assetName` matches
+     * (`EURC` for EUR); errors clearly if the merchant has no EUR rail.
+     */
+    currency?: PaygateCurrency;
+    /**
+     * Settlement token contract address. Auto-derived from `network` +
+     * `currency` if omitted. Ignored in the v3 path (merchant manifest is
+     * authoritative).
      */
     asset?: string;
     /** Override the default facilitator URL. */
     facilitatorUrl?: string;
+    /**
+     * Self-settle: submit the settlement transaction from your own funded key
+     * instead of the facilitator's relayer. You pay chain gas (~$0.001 per
+     * settle on Base) and nobody else — the never-sponsor / never-charge
+     * policy's direct-payout path. Verification still runs against the
+     * facilitator (free — no chain writes). Replay protection is on-chain:
+     * EIP-3009 consumes the authorization nonce, so a duplicate submit
+     * reverts.
+     */
+    selfSettle?: {
+        /** 0x-hex private key of any funded EOA. Pays gas only; never receives or holds customer funds. */
+        privateKey: string;
+        /** JSON-RPC URL for the settlement network. Defaults to the public Base RPCs for `eip155:8453` / `eip155:84532`. */
+        rpcUrl?: string;
+    };
     /** Override the default apps/api URL (for staging / self-hosted). */
     apiUrl?: string;
     /** Facilitator call timeout in ms. Default 30s. */

package/dist/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/dist/core.js

@@ -11,31 +11,93 @@
  * See docs/paygate-v2.md §7.
  */
 // ── Default facilitator ─────────────────────────────
-export const DEFAULT_FACILITATOR = 'https://facilitator.arispay.app';
-export const DEFAULT_API_URL = 'https://api.arispay.app';
+export const DEFAULT_FACILITATOR = "https://facilitator.arispay.app";
+export const DEFAULT_API_URL = "https://api.arispay.app";
 export const CAPABILITY_CACHE_TTL_MS = 5 * 60 * 1000;
 // ── Known USDC addresses per network ───────────────
+// Canonical source is `@arispay/x402-core` (USDC_BASE_MAINNET, etc.).
+// This duplicate is intentional: `paygate` is a published, standalone npm
+// package with `ethers` as its only runtime dep (see paygate CLAUDE.md). It
+// must NOT take a workspace dep on the private `@arispay/x402-core` package
+// — npm consumers wouldn't resolve it. Keep these four values in sync with
+// packages/x402-core/src/constants.ts by hand. Do not "DRY" by importing —
+// see P2-4 blocker discussion.
 const USDC_ADDRESSES = {
-    'eip155:84532': '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // Base Sepolia
-    'eip155:8453': '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // Base Mainnet
-    'eip155:1': '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // Ethereum
-    'eip155:137': '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359', // Polygon
+    "eip155:84532": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // Base Sepolia
+    "eip155:8453": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base Mainnet
+    "eip155:1": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // Ethereum
+    "eip155:137": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // Polygon
+};
+// Circle EURC — the EUR settlement asset (`currency: "EUR"`). Entries exist
+// only for networks where the address + EIP-712 domain were verified
+// on-chain (eth_call name()/version(), 2026-06-11). Same FiatToken family
+// as USDC → EIP-3009 supported, 6 decimals, domain name "EURC" version "2"
+// on both networks. EUR on other networks requires an explicit `asset`.
+const EURC_ADDRESSES = {
+    "eip155:84532": "0x808456652fdb597867f38412077A9182bf77359F", // Base Sepolia
+    "eip155:8453": "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", // Base Mainnet
 };
 const NETWORK_ALIASES = {
-    'base-sepolia': 'eip155:84532',
-    'base': 'eip155:8453',
-    'ethereum': 'eip155:1',
-    'polygon': 'eip155:137',
+    "base-sepolia": "eip155:84532",
+    base: "eip155:8453",
+    ethereum: "eip155:1",
+    polygon: "eip155:137",
 };
 function normalizeNetwork(network) {
     return NETWORK_ALIASES[network] ?? network;
 }
+/**
+ * Build the response headers for an x402 402 challenge in the canonical
+ * wire format observed across Bazaar-listed endpoints.
+ *
+ * - `payment-required: <base64(JSON)>` — primary, what 95.3% of live
+ *   x402 endpoints emit (audited 2026-04-30; see
+ *   docs/x402-wire-format-audit.md). base64 also dodges the Latin1
+ *   `ByteString` constraint on Node response headers, so a description
+ *   containing an em dash or smart quote no longer 500s the response.
+ *
+ * - `X-Payment-Requirements: <raw JSON of {x402Version, accepts}>` —
+ *   paygate's pre-v5.1 header name, kept for one minor cycle as a
+ *   deprecated alias so existing `payagent` consumers (and any other
+ *   client that reads our legacy emit) keep working. Will be removed
+ *   in paygate v6. Strip non-printable-ASCII defensively in case a
+ *   description picks up Unicode in the meantime.
+ *
+ * - `WWW-Authenticate: x402` — RFC 7235 challenge advertisement.
+ *
+ * - `Access-Control-Expose-Headers` — without this, browser-based
+ *   agents (Anthropic MCP-in-browser, Chrome WebMCP, …) can't read
+ *   `payment-required` cross-origin. 80% of live endpoints don't
+ *   bother; we do.
+ *
+ * Exported for tests; consumers should not rely on this signature.
+ */
+export function buildChallengeHeaders(challengeBody, accepts) {
+    const canonical = Buffer.from(JSON.stringify(challengeBody), "utf8").toString("base64");
+    const legacy = JSON.stringify({ x402Version: 2, accepts })
+        .replace(/[\r\n\0]/g, " ")
+        .replace(/[^\x20-\x7E]/g, "?");
+    return {
+        "payment-required": canonical,
+        "X-Payment-Requirements": legacy,
+        "WWW-Authenticate": "x402",
+        "Access-Control-Expose-Headers": "payment-required, x-payment-response, www-authenticate",
+    };
+}
 const USDC_DOMAIN_NAMES = {
-    'eip155:84532': 'USDC',
-    'eip155:8453': 'USD Coin',
-    'eip155:1': 'USD Coin',
-    'eip155:137': 'USD Coin',
+    "eip155:84532": "USDC",
+    "eip155:8453": "USD Coin",
+    "eip155:1": "USD Coin",
+    "eip155:137": "USD Coin",
 };
+// EURC's EIP-712 domain name is "EURC" on every verified network.
+const EURC_DOMAIN_NAME = "EURC";
+/** EIP-712 domain name for the selected currency's asset on a network. */
+function domainNameFor(currency, network) {
+    if (currency === "EUR")
+        return EURC_DOMAIN_NAME;
+    return USDC_DOMAIN_NAMES[network] ?? "USD Coin";
+}
 const DEFAULT_DISCOVERY_LIMIT = {
     maxProbes: 10,
     windowMs: 60_000,
@@ -63,13 +125,15 @@ function warnV2Shim() {
         return;
     v2ShimWarned = true;
     // eslint-disable-next-line no-console
-    console.warn('[paygate] v2 config detected (`wallet` + `network`). Pass `merchantId` instead; v2 will be removed in v4. See https://paygate.arispay.app/docs#v3-migration');
+    console.warn("[paygate] v2 config detected (`wallet` + `network`). Pass `merchantId` instead; v2 will be removed in v4. See https://paygate.arispay.app/docs#v3-migration");
 }
 async function fetchMerchantConfig(config) {
     if (!config.merchantId) {
-        throw new Error('paygate: merchantId is required for v3 flow');
+        throw new Error("paygate: merchantId is required for v3 flow");
     }
-    const cached = capabilityCache.get(config.merchantId);
+    const currency = config.currency ?? "USD";
+    const cacheKey = `${config.merchantId}:${currency}`;
+    const cached = capabilityCache.get(cacheKey);
     const cacheTtl = config.cacheTtlMs ?? CAPABILITY_CACHE_TTL_MS;
     if (cached && Date.now() - cached.fetchedAt < cacheTtl) {
         return cached;
@@ -90,7 +154,7 @@ async function fetchMerchantConfig(config) {
         throw new Error(`paygate: failed to fetch merchant capabilities: ${err instanceof Error ? err.message : String(err)}`);
     }
     if (res.status === 404) {
-        capabilityCache.delete(config.merchantId);
+        capabilityCache.delete(cacheKey);
         throw new Error(`paygate: merchantId "${config.merchantId}" not found at ${apiUrl}`);
     }
     if (res.status >= 500 && cached) {
@@ -100,20 +164,34 @@ async function fetchMerchantConfig(config) {
         throw new Error(`paygate: capability fetch failed HTTP ${res.status}`);
     }
     const manifest = (await res.json());
-    const rail = manifest.rails?.[0];
+    const wantedAssetName = currency === "EUR" ? "EURC" : "USDC";
+    // Prefer the rail matching the requested currency; USD callers keep the
+    // historical rails[0] fallback so pre-EUR manifests behave identically.
+    const rail = manifest.rails?.find((r) => r.assetName === wantedAssetName) ??
+        (currency === "USD" ? manifest.rails?.[0] : undefined);
     if (!rail) {
-        throw new Error(`paygate: merchant "${config.merchantId}" has no active payout rail — add a PayoutMethod in the dashboard`);
+        throw new Error(currency === "EUR"
+            ? `paygate: merchant "${config.merchantId}" has no EUR (EURC) payout rail — add one in the dashboard or use currency: "USD"`
+            : `paygate: merchant "${config.merchantId}" has no active payout rail — add a PayoutMethod in the dashboard`);
+    }
+    // v3 manifests must specify an HTTPS facilitator per rail. The SDK no longer
+    // silently falls back to the production default, which would hide
+    // misconfiguration and let a rogue facilitator claim successful settlement (L7).
+    const facilitator = rail.facilitator;
+    if (!facilitator || !facilitator.startsWith("https://")) {
+        throw new Error(`paygate: merchant "${config.merchantId}" rail has invalid facilitator URL`);
     }
     const resolved = {
         network: rail.network,
         asset: rail.asset,
+        domainName: domainNameFor(currency, rail.network),
         payTo: rail.payTo,
-        facilitator: rail.facilitator ?? DEFAULT_FACILITATOR,
-        trustMinTier: manifest.trust?.minTier ?? 'any',
+        facilitator,
+        trustMinTier: manifest.trust?.minTier ?? "any",
         slug: manifest.merchant.slug,
         fetchedAt: Date.now(),
     };
-    capabilityCache.set(config.merchantId, resolved);
+    capabilityCache.set(cacheKey, resolved);
     return resolved;
 }
 /**
@@ -124,23 +202,26 @@ async function fetchMerchantConfig(config) {
 function resolveV2Shim(config) {
     warnV2Shim();
     if (!config.wallet) {
-        throw new Error('paygate: wallet is required in v2-shim mode');
+        throw new Error("paygate: wallet is required in v2-shim mode");
     }
     if (!config.network) {
-        throw new Error('paygate: network is required in v2-shim mode');
+        throw new Error("paygate: network is required in v2-shim mode");
     }
+    const currency = config.currency ?? "USD";
     const network = normalizeNetwork(config.network);
-    const asset = config.asset ?? USDC_ADDRESSES[network];
+    const knownAddresses = currency === "EUR" ? EURC_ADDRESSES : USDC_ADDRESSES;
+    const asset = config.asset ?? knownAddresses[network];
     if (!asset) {
-        throw new Error(`paygate: unsupported network ${network} — no known USDC address`);
+        throw new Error(`paygate: unsupported network ${network} — no known ${currency === "EUR" ? "EURC" : "USDC"} address (pass \`asset\` explicitly)`);
     }
     return {
         network,
         asset,
+        domainName: domainNameFor(currency, network),
         payTo: config.wallet,
         facilitator: config.facilitatorUrl ?? DEFAULT_FACILITATOR,
-        trustMinTier: 'any',
-        slug: 'v2-shim',
+        trustMinTier: "any",
+        slug: "v2-shim",
         fetchedAt: Date.now(),
     };
 }
@@ -148,7 +229,7 @@ function resolveV2Shim(config) {
 async function resolvePriceCents(routePrice, request) {
     const v3 = routePrice.priceCents;
     if (v3 !== undefined) {
-        const cents = typeof v3 === 'function' ? await v3(request) : v3;
+        const cents = typeof v3 === "function" ? await v3(request) : v3;
         if (!Number.isInteger(cents) || cents < 1) {
             throw new Error(`paygate: priceCents must be a positive integer. Got ${JSON.stringify(cents)}. If you meant $0.10, use priceCents: 10.`);
         }
@@ -157,17 +238,78 @@ async function resolvePriceCents(routePrice, request) {
     const v2 = routePrice.price;
     if (v2 !== undefined) {
         warnV2Shim();
-        const dollars = typeof v2 === 'function' ? await v2(request) : v2;
-        if (typeof dollars !== 'number' || dollars <= 0) {
-            throw new Error('paygate: price must be a positive number');
+        const dollars = typeof v2 === "function" ? await v2(request) : v2;
+        if (typeof dollars !== "number" || dollars <= 0) {
+            throw new Error("paygate: price must be a positive number");
         }
         return Math.round(dollars * 100);
     }
-    throw new Error('paygate: RoutePrice requires `priceCents` (preferred) or `price` (v2 compat)');
+    throw new Error("paygate: RoutePrice requires `priceCents` (preferred) or `price` (v2 compat)");
+}
+// ── Self-settle (seller-submitted settlement) ──────────────────────────
+// EIP-3009 transferWithAuthorization, split-signature form — present on
+// USDC and EURC, the assets the default facilitator stands behind.
+const EIP3009_ABI = [
+    "function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s)",
+];
+const DEFAULT_RPC_BY_NETWORK = {
+    "eip155:8453": "https://mainnet.base.org",
+    "eip155:84532": "https://sepolia.base.org",
+    base: "https://mainnet.base.org",
+    "base-sepolia": "https://sepolia.base.org",
+};
+async function submitSelfSettle(selfSettle, paymentPayload, accept, timeoutMs) {
+    const rpcUrl = selfSettle.rpcUrl ?? DEFAULT_RPC_BY_NETWORK[accept.network];
+    if (!rpcUrl) {
+        return {
+            success: false,
+            errorReason: "SELF_SETTLE_CONFIG",
+            errorMessage: `paygate: no default RPC for network "${accept.network}" — set selfSettle.rpcUrl`,
+        };
+    }
+    // `ethers` is an optional peer dependency — only self-settle needs it, so
+    // the facilitator path never pulls it. Surface a clear install hint rather
+    // than a raw MODULE_NOT_FOUND if a self-settle merchant hasn't installed it.
+    let ethers;
+    try {
+        ethers = await import("ethers");
+    }
+    catch {
+        return {
+            success: false,
+            errorReason: "SELF_SETTLE_CONFIG",
+            errorMessage: "paygate: self-settle requires the optional peer dependency `ethers` — run `npm install ethers`",
+        };
+    }
+    try {
+        const { JsonRpcProvider, Wallet, Contract, Signature } = ethers;
+        const provider = new JsonRpcProvider(rpcUrl);
+        const wallet = new Wallet(selfSettle.privateKey, provider);
+        const token = new Contract(accept.asset, EIP3009_ABI, wallet);
+        const auth = paymentPayload.payload.authorization;
+        const sig = Signature.from(paymentPayload.payload.signature);
+        const tx = await token.transferWithAuthorization(auth.from, auth.to, auth.value, auth.validAfter, auth.validBefore, auth.nonce, sig.v, sig.r, sig.s);
+        const receipt = await tx.wait(1, timeoutMs);
+        if (!receipt || receipt.status !== 1) {
+            return {
+                success: false,
+                errorReason: "SETTLEMENT_REVERTED",
+                errorMessage: "paygate: self-settle transaction reverted",
+            };
+        }
+        return { success: true, transaction: receipt.hash, payer: auth.from };
+    }
+    catch (err) {
+        return {
+            success: false,
+            errorReason: "SELF_SETTLE_ERROR",
+            errorMessage: err instanceof Error ? err.message : "paygate: self-settle failed",
+        };
+    }
 }
 function decodePaymentHeader(header) {
     try {
-        const decoded = Buffer.from(header, 'base64').toString('utf8');
+        const decoded = Buffer.from(header, "base64").toString("utf8");
         return JSON.parse(decoded);
     }
     catch {
@@ -179,9 +321,7 @@ export async function handlePaywall(config, routePrice, resourceUrl, paymentHead
     // Resolve the merchant: v3 fetch vs v2 shim
     let resolved;
     try {
-        resolved = config.merchantId
-            ? await fetchMerchantConfig(config)
-            : resolveV2Shim(config);
+        resolved = config.merchantId ? await fetchMerchantConfig(config) : resolveV2Shim(config);
     }
     catch (err) {
         return {
@@ -189,8 +329,8 @@ export async function handlePaywall(config, routePrice, resourceUrl, paymentHead
             error: {
                 statusCode: 500,
                 body: {
-                    error: err instanceof Error ? err.message : 'paygate: configuration error',
-                    code: 'PAYGATE_CONFIG',
+                    error: err instanceof Error ? err.message : "paygate: configuration error",
+                    code: "PAYGATE_CONFIG",
                 },
             },
         };
@@ -206,39 +346,38 @@ export async function handlePaywall(config, routePrice, resourceUrl, paymentHead
                     error: {
                         statusCode: 429,
                         body: {
-                            error: 'Too many discovery requests. Try again later.',
-                            code: 'DISCOVERY_RATE_LIMITED',
+                            error: "Too many discovery requests. Try again later.",
+                            code: "DISCOVERY_RATE_LIMITED",
                         },
                     },
                 };
             }
         }
-        const domainName = USDC_DOMAIN_NAMES[resolved.network] ?? 'USD Coin';
         const accepts = [
             {
-                scheme: 'exact',
+                scheme: "exact",
                 network: resolved.network,
                 amount: priceBaseUnits,
                 resource: resourceUrl,
                 asset: resolved.asset,
                 payTo: resolved.payTo,
-                extra: { name: domainName, version: '2' },
+                extra: { name: resolved.domainName, version: "2" },
             },
         ];
-        const requirementsStr = JSON.stringify({ x402Version: 2, accepts }).replace(/[\r\n\0]/g, ' ');
+        const challengeBody = {
+            error: "Payment Required",
+            x402Version: 2,
+            accepts,
+            facilitator: resolved.facilitator,
+            trustMinTier: resolved.trustMinTier,
+            gasSponsored: true,
+        };
         return {
             paid: false,
             challenge: {
                 statusCode: 402,
-                headers: { 'X-Payment-Requirements': requirementsStr },
-                body: {
-                    error: 'Payment Required',
-                    x402Version: 2,
-                    accepts,
-                    facilitator: resolved.facilitator,
-                    trustMinTier: resolved.trustMinTier,
-                    gasSponsored: true,
-                },
+                headers: buildChallengeHeaders(challengeBody, accepts),
+                body: challengeBody,
             },
         };
     }
@@ -252,41 +391,90 @@ export async function handlePaywall(config, routePrice, resourceUrl, paymentHead
             paid: false,
             error: {
                 statusCode: 400,
-                body: { error: 'Invalid X-Payment header', code: 'INVALID_PAYMENT' },
+                body: { error: "Invalid X-Payment header", code: "INVALID_PAYMENT" },
             },
         };
     }
     // Settle via facilitator
-    const domainName = USDC_DOMAIN_NAMES[resolved.network] ?? 'USD Coin';
     const accept = {
-        scheme: 'exact',
+        scheme: "exact",
         network: resolved.network,
         amount: priceBaseUnits,
         resource: resourceUrl,
         asset: resolved.asset,
         payTo: resolved.payTo,
-        extra: { name: domainName, version: '2' },
+        extra: { name: resolved.domainName, version: "2" },
     };
     try {
-        const res = await fetch(`${resolved.facilitator}/settle`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                x402Version: 2,
-                paymentPayload,
-                paymentRequirements: accept,
-            }),
-            signal: AbortSignal.timeout(config.timeout ?? 30_000),
-        });
-        const settlement = (await res.json());
+        let settlement;
+        if (config.selfSettle) {
+            // Verify via the facilitator (free — no chain writes), then submit
+            // the settlement from the seller's own key: gas is the seller's,
+            // per the never-sponsor / never-charge policy.
+            const verifyRes = await fetch(`${resolved.facilitator}/verify`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    x402Version: 2,
+                    paymentPayload,
+                    paymentRequirements: accept,
+                }),
+                signal: AbortSignal.timeout(config.timeout ?? 30_000),
+            });
+            const verdict = (await verifyRes.json());
+            if (!verdict.isValid) {
+                return {
+                    paid: false,
+                    error: {
+                        statusCode: 402,
+                        body: {
+                            error: verdict.invalidReason || "Payment verification failed",
+                            code: verdict.invalidReason || "VERIFICATION_FAILED",
+                        },
+                    },
+                };
+            }
+            settlement = await submitSelfSettle(config.selfSettle, paymentPayload, accept, config.timeout ?? 30_000);
+        }
+        else {
+            const res = await fetch(`${resolved.facilitator}/settle`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    x402Version: 2,
+                    paymentPayload,
+                    paymentRequirements: accept,
+                }),
+                signal: AbortSignal.timeout(config.timeout ?? 30_000),
+            });
+            settlement = (await res.json());
+        }
         if (!settlement.success) {
             return {
                 paid: false,
                 error: {
                     statusCode: 402,
                     body: {
-                        error: settlement.errorMessage || settlement.errorReason || 'Payment settlement failed',
-                        code: settlement.errorReason || 'SETTLEMENT_FAILED',
+                        error: settlement.errorMessage || settlement.errorReason || "Payment settlement failed",
+                        code: settlement.errorReason || "SETTLEMENT_FAILED",
+                    },
+                },
+            };
+        }
+        // Validate the successful settlement before trusting it (L7). Require a
+        // non-empty transaction hash and, when the facilitator reports a payer,
+        // ensure it matches the address that signed the authorization.
+        const expectedPayer = paymentPayload.payload.authorization.from;
+        if (typeof settlement.transaction !== "string" ||
+            settlement.transaction.length === 0 ||
+            (settlement.payer && settlement.payer.toLowerCase() !== expectedPayer.toLowerCase())) {
+            return {
+                paid: false,
+                error: {
+                    statusCode: 502,
+                    body: {
+                        error: "Facilitator returned an invalid settlement",
+                        code: "INVALID_SETTLEMENT",
                     },
                 },
             };
@@ -297,18 +485,18 @@ export async function handlePaywall(config, routePrice, resourceUrl, paymentHead
             receipt: {
                 paid: true,
                 txHash: settlement.transaction,
-                trustTier: 'any', // SDK path has no tier check in v1
+                trustTier: "any", // SDK path has no tier check in v1
                 merchant: resolved.slug,
             },
         };
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : 'Facilitator unreachable';
+        const message = err instanceof Error ? err.message : "Facilitator unreachable";
         return {
             paid: false,
             error: {
                 statusCode: 502,
-                body: { error: `Facilitator error: ${message}`, code: 'FACILITATOR_ERROR' },
+                body: { error: `Facilitator error: ${message}`, code: "FACILITATOR_ERROR" },
             },
         };
     }