@shroud-fi/x402 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShroudFi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @shroud-fi/x402
+
+> Stealth-addressed HTTP 402 payments for AI agents. EIP-3009 settlement into one-time addresses.
+
+[![npm](https://img.shields.io/npm/v/@shroud-fi/x402.svg)](https://www.npmjs.com/package/@shroud-fi/x402)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+```bash
+npm i @shroud-fi/x402 viem
+```
+
+## What it does
+
+`@shroud-fi/x402` wraps the HTTP 402 protocol with ShroudFi's stealth-address layer. Any endpoint can issue a 402 challenge, and any agent can pay it — but the USDC settlement lands at a **fresh, one-time stealth address** derived from the seller's meta-address.
+
+Call the same `/pay/signal` URL ten times — get ten unlinkable USDC destinations. The customer graph never forms on-chain.
+
+## Why it matters
+
+A naive agent-to-agent payment exposes the buyer's main wallet, the seller's main wallet, and a verifiable on-chain link between them. After enough calls, the entire customer graph of an agentic service is publicly reconstructable. Stealth-addressed x402 closes that.
+
+## Quick start (client)
+
+```ts
+import { payX402 } from '@shroud-fi/x402';
+
+const signal = await payX402({
+  agent,                                            // a ShroudAgent from @shroud-fi/agent-runtime
+  url: 'https://api.alpha.xyz/signal',
+  maxPriceUsdcAtomic: 10_000n,                      // 0.01 USDC
+});
+
+console.log(signal); // unlocked response body
+```
+
+## Quick start (server)
+
+```ts
+import { createX402Server } from '@shroud-fi/x402';
+
+const x402 = createX402Server({
+  resource: 'https://api.alpha.xyz/signal',
+  priceUsdcAtomic: 10_000n,
+  recipientMeta: 'st:base:0x024fa9bb…',
+});
+
+// In your Fastify / Express handler:
+const payment = req.headers['x-payment'];
+if (!payment) {
+  return reply.code(402).send(await x402.challenge());
+}
+const verified = await x402.verify(payment);
+if (!verified.ok) return reply.code(402).send({ error: verified.reason });
+// payment OK — settle + serve content
+```
+
+## Exports
+
+| Symbol | Purpose |
+|---|---|
+| `payX402(args)` | One-shot client. Calls a URL, signs USDC if a 402 lands, retries with `X-PAYMENT`, returns the unlocked body. |
+| `createX402Server(cfg)` | Server-side primitives. Mint a 402 challenge or verify a payment payload. |
+| `buildX402Payment(args)` | Lower-level sign-only flow for custom HTTP machinery. |
+
+Full API reference: [shroudfi.live/sdk#x402](https://shroudfi.live/sdk#x402)
+
+## Standards used
+
+- **HTTP 402 Payment Required** + **`x402` extension** ([x402.org](https://x402.org/))
+- **EIP-3009** `transferWithAuthorization` for USDC settlement
+- **EIP-5564 / 6538** for stealth-address derivation
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Part of the [ShroudFi](https://shroudfi.live) privacy SDK for AI agents on Base.

package/dist/cjs/client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * x402 client — fetch wrapper that auto-handles 402 challenges.
+ *
+ * Flow:
+ *   1. Issue initial fetch.
+ *   2. If status !== 402, return as-is.
+ *   3. Parse X-PAYMENT-REQUIRED, validate scheme + asset + safety cap.
+ *   4. Sign EIP-3009 TransferWithAuthorization for USDC.
+ *   5. Re-issue request with `X-PAYMENT: base64(JSON(payload))`.
+ *   6. On 2xx, surface `x402Settlement` on the returned Response if the
+ *      server attached X-PAYMENT-RESPONSE.
+ *
+ * Privacy invariants:
+ *   - The signed payload is constructed in memory and forwarded directly to
+ *     the server. We never log or serialize the signature, nonce, or value.
+ *   - The client wallet address is unavoidably visible (it IS the `from`).
+ *     This is the agent's stealth-payer EOA, not a persistent identity if
+ *     used by ShroudAgent.
+ *   - Errors carry no amount, no signature, no nonce bytes.
+ */
+import type { X402ClientConfig, X402PaymentResult } from './types.js';
+/**
+ * The augmented Response surface. We can't subclass `Response` in a portable
+ * way, so we attach `x402Settlement` as a non-standard own-property.
+ */
+export interface X402Response extends Response {
+    x402Settlement?: X402PaymentResult;
+}
+export interface X402Client {
+    /**
+     * Wrap `fetch` with 402 auto-pay. The returned Response is augmented with
+     * `x402Settlement` when a payment was made.
+     *
+     * @param maxPriceAtomic — safety cap. If the server demands more, the
+     *   client throws X402AmountMismatchError without signing anything.
+     */
+    fetch(input: string | URL | Request, init?: RequestInit & {
+        maxPriceAtomic?: bigint;
+    }): Promise<X402Response>;
+}
+export declare function createX402Client(config: X402ClientConfig): X402Client;
+export type { X402ClientConfig, X402PaymentResult } from './types.js';
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAkBH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAMtE;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC7B,IAAI,CAAC,EAAE,WAAW,GAAG;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAyED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA6HrE;AAED,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/cjs/client.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * x402 client — fetch wrapper that auto-handles 402 challenges.
+ *
+ * Flow:
+ *   1. Issue initial fetch.
+ *   2. If status !== 402, return as-is.
+ *   3. Parse X-PAYMENT-REQUIRED, validate scheme + asset + safety cap.
+ *   4. Sign EIP-3009 TransferWithAuthorization for USDC.
+ *   5. Re-issue request with `X-PAYMENT: base64(JSON(payload))`.
+ *   6. On 2xx, surface `x402Settlement` on the returned Response if the
+ *      server attached X-PAYMENT-RESPONSE.
+ *
+ * Privacy invariants:
+ *   - The signed payload is constructed in memory and forwarded directly to
+ *     the server. We never log or serialize the signature, nonce, or value.
+ *   - The client wallet address is unavoidably visible (it IS the `from`).
+ *     This is the agent's stealth-payer EOA, not a persistent identity if
+ *     used by ShroudAgent.
+ *   - Errors carry no amount, no signature, no nonce bytes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createX402Client = createX402Client;
+const transport_1 = require("@shroud-fi/transport");
+const protocol_js_1 = require("./protocol.js");
+const constants_js_1 = require("./constants.js");
+const errors_js_1 = require("./errors.js");
+const signing_js_1 = require("./signing.js");
+/** Decode a 402 challenge body from the response. Tries header, then body. */
+async function readChallenge(res) {
+    // Header path (spec-canonical) first.
+    const header = res.headers.get(protocol_js_1.X402_PAYMENT_REQUIRED_HEADER);
+    if (header !== null && header.length > 0) {
+        try {
+            const parsed = JSON.parse(header);
+            if (Array.isArray(parsed.accepts) && parsed.accepts.length > 0) {
+                return parsed;
+            }
+        }
+        catch {
+            // fall through to body parse
+        }
+    }
+    // Body fallback — some servers put the envelope in the body only.
+    try {
+        const text = await res.clone().text();
+        const parsed = JSON.parse(text);
+        if (Array.isArray(parsed.accepts) && parsed.accepts.length > 0) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through
+    }
+    throw new errors_js_1.X402InvalidChallengeError();
+}
+/** Decode the X-PAYMENT-RESPONSE header into a settlement record. */
+function readSettlement(res) {
+    const header = res.headers.get(protocol_js_1.X402_PAYMENT_RESPONSE_HEADER);
+    if (header === null || header.length === 0)
+        return undefined;
+    try {
+        // Header is base64-encoded JSON per the spec.
+        const decoded = Buffer.from(header, 'base64').toString('utf-8');
+        const parsed = JSON.parse(decoded);
+        const txHash = (parsed.transaction ?? parsed.txHash);
+        if (txHash === undefined)
+            return undefined;
+        return {
+            txHash,
+            settledAt: typeof parsed.settledAt === 'number'
+                ? parsed.settledAt
+                : Math.floor(Date.now() / 1000),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Convert a value into a bigint safely. */
+function safeBigInt(v) {
+    try {
+        if (typeof v === 'bigint')
+            return v;
+        if (typeof v === 'string' || typeof v === 'number')
+            return BigInt(v);
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function createX402Client(config) {
+    const transport = config.transport;
+    const walletClient = transport.walletClient;
+    if (walletClient === undefined || walletClient.account === undefined) {
+        // We deliberately throw at construction time so a misconfigured client
+        // can't ship to production without a wallet.
+        throw new errors_js_1.X402AssetNotSupportedError();
+    }
+    const account = walletClient.account;
+    const chain = transport.chain;
+    return {
+        async fetch(input, init) {
+            const fetchImpl = globalThis.fetch;
+            const maxPriceAtomic = init?.maxPriceAtomic;
+            // Strip our non-standard option before passing init to fetch.
+            const passThroughInit = { ...(init ?? {}) };
+            delete passThroughInit.maxPriceAtomic;
+            // 1. First attempt.
+            const first = (await fetchImpl(input, passThroughInit));
+            if (first.status !== 402) {
+                return first;
+            }
+            // 2. Decode challenge.
+            const challenge = await readChallenge(first);
+            const requirements = challenge.accepts[0];
+            if (requirements === undefined) {
+                throw new errors_js_1.X402InvalidChallengeError();
+            }
+            // 3. Scheme + network + asset checks.
+            if (requirements.scheme !== protocol_js_1.X402_SCHEME_EXACT) {
+                throw new errors_js_1.X402InvalidChallengeError();
+            }
+            const canonicalUsdc = (0, transport_1.getUSDC)(chain.id);
+            if (canonicalUsdc === undefined) {
+                throw new errors_js_1.X402AssetNotSupportedError();
+            }
+            if (requirements.asset.toLowerCase() !==
+                canonicalUsdc.toLowerCase()) {
+                throw new errors_js_1.X402AssetNotSupportedError();
+            }
+            const expectedNetwork = `eip155:${chain.id}`;
+            if (requirements.network !== expectedNetwork) {
+                throw new errors_js_1.X402AssetNotSupportedError();
+            }
+            // 4. Safety cap.
+            const required = safeBigInt(requirements.maxAmountRequired);
+            if (required === null) {
+                throw new errors_js_1.X402InvalidChallengeError();
+            }
+            if (maxPriceAtomic !== undefined && required > maxPriceAtomic) {
+                throw new errors_js_1.X402AmountMismatchError();
+            }
+            // 5. Build authorization. validAfter=0n, validBefore=now+ttl.
+            const nowSecs = BigInt(Math.floor(Date.now() / 1000));
+            const ttl = BigInt(Math.min(requirements.maxTimeoutSeconds || constants_js_1.DEFAULT_AUTHORIZATION_TTL_SECS, constants_js_1.DEFAULT_AUTHORIZATION_TTL_SECS));
+            const validBefore = nowSecs + ttl;
+            const nonce = (0, signing_js_1.generateAuthorizationNonce)();
+            const signed = await (0, signing_js_1.signTransferWithAuthorization)({
+                account,
+                chain,
+                verifyingContract: requirements.asset,
+                input: {
+                    from: account.address,
+                    to: requirements.payTo,
+                    value: required,
+                    validAfter: 0n,
+                    validBefore,
+                    nonce,
+                },
+            });
+            // 6. Build the PaymentPayload + base64 the header.
+            const payload = {
+                x402Version: constants_js_1.X402_VERSION,
+                scheme: protocol_js_1.X402_SCHEME_EXACT,
+                network: requirements.network,
+                payload: {
+                    signature: signed.signature,
+                    authorization: {
+                        from: signed.from,
+                        to: signed.to,
+                        value: signed.value.toString(),
+                        validAfter: signed.validAfter.toString(),
+                        validBefore: signed.validBefore.toString(),
+                        nonce: signed.nonce,
+                    },
+                },
+            };
+            const encoded = Buffer.from(JSON.stringify(payload), 'utf-8').toString('base64');
+            // 7. Re-issue. Mutating the headers via a new object so the caller's
+            // original init stays untouched.
+            const retryHeaders = new Headers(passThroughInit.headers ?? undefined);
+            retryHeaders.set(protocol_js_1.X402_PAYMENT_SIGNATURE_HEADER, encoded);
+            const retryInit = {
+                ...passThroughInit,
+                headers: retryHeaders,
+            };
+            const second = (await fetchImpl(input, retryInit));
+            const settlement = readSettlement(second);
+            if (settlement !== undefined) {
+                // Attach as a non-standard own-property.
+                second.x402Settlement = settlement;
+            }
+            return second;
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

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

package/dist/cjs/constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Defaults for the @shroud-fi/x402 package.
+ *
+ * Tight defaults reduce blast radius if a signed payload leaks:
+ *   - 5-minute validity window matches Coinbase CDP recommendation and the
+ *     PayAI free tier facilitator's default maxTimeoutSeconds (300).
+ *   - x402Version pinned to 2 (current shipping spec). We deliberately do NOT
+ *     implement v1 backward-compat per LOCKED-DECISIONS (whitepaper field
+ *     names are deprecated).
+ */
+export declare const X402_VERSION: 2;
+/** Default EIP-3009 authorization validity window (seconds). */
+export declare const DEFAULT_AUTHORIZATION_TTL_SECS = 300;
+/** Default facilitator `maxTimeoutSeconds` echoed back in PaymentRequired. */
+export declare const DEFAULT_MAX_TIMEOUT_SECS = 300;
+//# sourceMappingURL=constants.d.ts.map

package/dist/cjs/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,YAAY,EAAG,CAAU,CAAC;AAEvC,gEAAgE;AAChE,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,MAAM,CAAC"}

package/dist/cjs/constants.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Defaults for the @shroud-fi/x402 package.
+ *
+ * Tight defaults reduce blast radius if a signed payload leaks:
+ *   - 5-minute validity window matches Coinbase CDP recommendation and the
+ *     PayAI free tier facilitator's default maxTimeoutSeconds (300).
+ *   - x402Version pinned to 2 (current shipping spec). We deliberately do NOT
+ *     implement v1 backward-compat per LOCKED-DECISIONS (whitepaper field
+ *     names are deprecated).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_TIMEOUT_SECS = exports.DEFAULT_AUTHORIZATION_TTL_SECS = exports.X402_VERSION = void 0;
+exports.X402_VERSION = 2;
+/** Default EIP-3009 authorization validity window (seconds). */
+exports.DEFAULT_AUTHORIZATION_TTL_SECS = 300;
+/** Default facilitator `maxTimeoutSeconds` echoed back in PaymentRequired. */
+exports.DEFAULT_MAX_TIMEOUT_SECS = 300;
+//# sourceMappingURL=constants.js.map

package/dist/cjs/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEU,QAAA,YAAY,GAAG,CAAU,CAAC;AAEvC,gEAAgE;AACnD,QAAA,8BAA8B,GAAG,GAAG,CAAC;AAElD,8EAA8E;AACjE,QAAA,wBAAwB,GAAG,GAAG,CAAC"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * x402 error hierarchy.
+ *
+ * Privacy invariants:
+ *   - No amount, value, or balance numbers in any .message string.
+ *   - No private keys, signature bytes, or nonce bytes in any .message string.
+ *   - No recipient main wallet addresses in any .message string (stealth
+ *     addresses are derivable on-chain so leaking them post-payment is fine,
+ *     but the registrant wallet is identity-bearing — never include it).
+ *   - All errors extend the same base class so callers can `instanceof X402Error`
+ *     once at the boundary.
+ */
+export declare class X402Error extends Error {
+    readonly name: string;
+    constructor(message: string);
+}
+/**
+ * The 402 challenge body (or its header) could not be parsed / is malformed.
+ * Catch-all for "we received something the spec disallows".
+ */
+export declare class X402InvalidChallengeError extends X402Error {
+    readonly name: string;
+    constructor();
+}
+/**
+ * The signed `PAYMENT-SIGNATURE` payload submitted by the client could not be
+ * verified against the challenge (signer mismatch, malformed JSON, expired
+ * authorization, etc).
+ */
+export declare class X402SignatureVerificationError extends X402Error {
+    readonly name: string;
+    constructor();
+}
+/**
+ * Facilitator HTTP call (verify or settle) failed. Tag identifies the
+ * facilitator stage but never carries response body, token amount, or signed
+ * payload.
+ */
+export declare class X402FacilitatorError extends X402Error {
+    readonly name: string;
+    constructor(stage: 'verify' | 'settle' | 'network');
+}
+/**
+ * The server's configured asset is not the canonical USDC on the configured
+ * chain (or USDC is not deployed on the chain). Hard-fail to avoid signing
+ * authorizations against the wrong token.
+ */
+export declare class X402AssetNotSupportedError extends X402Error {
+    readonly name: string;
+    constructor();
+}
+/**
+ * The server's quoted price exceeded the client's `maxPriceAtomic` safety cap,
+ * or the verified payload's value did not equal the challenge requirement.
+ * The error carries no amount bytes — caller can read inputs separately.
+ */
+export declare class X402AmountMismatchError extends X402Error {
+    readonly name: string;
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,EAAE,MAAM,CAAe;gBACjC,OAAO,EAAE,MAAM;CAG5B;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACtD,SAAkB,IAAI,EAAE,MAAM,CAA+B;;CAI9D;AAED;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,SAAS;IAC3D,SAAkB,IAAI,EAAE,MAAM,CAAoC;;CAInE;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IACjD,SAAkB,IAAI,EAAE,MAAM,CAA0B;gBAC5C,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS;CAGnD;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;IACvD,SAAkB,IAAI,EAAE,MAAM,CAAgC;;CAI/D;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACpD,SAAkB,IAAI,EAAE,MAAM,CAA6B;;CAI5D"}

package/dist/cjs/errors.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * x402 error hierarchy.
+ *
+ * Privacy invariants:
+ *   - No amount, value, or balance numbers in any .message string.
+ *   - No private keys, signature bytes, or nonce bytes in any .message string.
+ *   - No recipient main wallet addresses in any .message string (stealth
+ *     addresses are derivable on-chain so leaking them post-payment is fine,
+ *     but the registrant wallet is identity-bearing — never include it).
+ *   - All errors extend the same base class so callers can `instanceof X402Error`
+ *     once at the boundary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402AmountMismatchError = exports.X402AssetNotSupportedError = exports.X402FacilitatorError = exports.X402SignatureVerificationError = exports.X402InvalidChallengeError = exports.X402Error = void 0;
+class X402Error extends Error {
+    name = 'X402Error';
+    constructor(message) {
+        super(message);
+    }
+}
+exports.X402Error = X402Error;
+/**
+ * The 402 challenge body (or its header) could not be parsed / is malformed.
+ * Catch-all for "we received something the spec disallows".
+ */
+class X402InvalidChallengeError extends X402Error {
+    name = 'X402InvalidChallengeError';
+    constructor() {
+        super('Invalid x402 challenge payload');
+    }
+}
+exports.X402InvalidChallengeError = X402InvalidChallengeError;
+/**
+ * The signed `PAYMENT-SIGNATURE` payload submitted by the client could not be
+ * verified against the challenge (signer mismatch, malformed JSON, expired
+ * authorization, etc).
+ */
+class X402SignatureVerificationError extends X402Error {
+    name = 'X402SignatureVerificationError';
+    constructor() {
+        super('x402 signed payment payload failed verification');
+    }
+}
+exports.X402SignatureVerificationError = X402SignatureVerificationError;
+/**
+ * Facilitator HTTP call (verify or settle) failed. Tag identifies the
+ * facilitator stage but never carries response body, token amount, or signed
+ * payload.
+ */
+class X402FacilitatorError extends X402Error {
+    name = 'X402FacilitatorError';
+    constructor(stage) {
+        super(`x402 facilitator request failed (stage=${stage})`);
+    }
+}
+exports.X402FacilitatorError = X402FacilitatorError;
+/**
+ * The server's configured asset is not the canonical USDC on the configured
+ * chain (or USDC is not deployed on the chain). Hard-fail to avoid signing
+ * authorizations against the wrong token.
+ */
+class X402AssetNotSupportedError extends X402Error {
+    name = 'X402AssetNotSupportedError';
+    constructor() {
+        super('x402: requested asset is not supported on the configured chain');
+    }
+}
+exports.X402AssetNotSupportedError = X402AssetNotSupportedError;
+/**
+ * The server's quoted price exceeded the client's `maxPriceAtomic` safety cap,
+ * or the verified payload's value did not equal the challenge requirement.
+ * The error carries no amount bytes — caller can read inputs separately.
+ */
+class X402AmountMismatchError extends X402Error {
+    name = 'X402AmountMismatchError';
+    constructor() {
+        super('x402: payment amount exceeds caller cap or does not match challenge');
+    }
+}
+exports.X402AmountMismatchError = X402AmountMismatchError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAEH,MAAa,SAAU,SAAQ,KAAK;IAChB,IAAI,GAAW,WAAW,CAAC;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AALD,8BAKC;AAED;;;GAGG;AACH,MAAa,yBAA0B,SAAQ,SAAS;IACpC,IAAI,GAAW,2BAA2B,CAAC;IAC7D;QACE,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAC1C,CAAC;CACF;AALD,8DAKC;AAED;;;;GAIG;AACH,MAAa,8BAA+B,SAAQ,SAAS;IACzC,IAAI,GAAW,gCAAgC,CAAC;IAClE;QACE,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC3D,CAAC;CACF;AALD,wEAKC;AAED;;;;GAIG;AACH,MAAa,oBAAqB,SAAQ,SAAS;IAC/B,IAAI,GAAW,sBAAsB,CAAC;IACxD,YAAY,KAAsC;QAChD,KAAK,CAAC,0CAA0C,KAAK,GAAG,CAAC,CAAC;IAC5D,CAAC;CACF;AALD,oDAKC;AAED;;;;GAIG;AACH,MAAa,0BAA2B,SAAQ,SAAS;IACrC,IAAI,GAAW,4BAA4B,CAAC;IAC9D;QACE,KAAK,CAAC,gEAAgE,CAAC,CAAC;IAC1E,CAAC;CACF;AALD,gEAKC;AAED;;;;GAIG;AACH,MAAa,uBAAwB,SAAQ,SAAS;IAClC,IAAI,GAAW,yBAAyB,CAAC;IAC3D;QACE,KAAK,CAAC,qEAAqE,CAAC,CAAC;IAC/E,CAAC;CACF;AALD,0DAKC"}

package/dist/cjs/facilitator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Facilitator HTTP client.
+ *
+ * Two endpoints per the x402 spec:
+ *   - POST /verify  — facilitator validates signature + balance + simulation.
+ *   - POST /settle  — facilitator broadcasts the on-chain settlement tx.
+ *
+ * Privacy invariants:
+ *   - We forward only the signed PaymentPayload + the PaymentRequirements. The
+ *     facilitator never receives the recipient's main wallet — only the
+ *     freshly derived stealth address (the `payTo` field of the requirements).
+ *   - We never log request/response bodies. Tags are short strings only.
+ *   - Auth token (if any) is attached as a Bearer header. We never log the
+ *     full token; tests verify the header is set but redaction is the
+ *     operator's responsibility upstream.
+ */
+import type { Hex } from 'viem';
+import { type X402FacilitatorConfig } from './protocol.js';
+export interface FacilitatorVerifyResult {
+    readonly isValid: boolean;
+    readonly invalidReason?: string;
+    readonly payer?: string;
+}
+export interface FacilitatorSettleResult {
+    readonly success: boolean;
+    readonly txHash?: Hex;
+    readonly errorReason?: string;
+    readonly payer?: string;
+    readonly network?: string;
+}
+/** Resolve the facilitator config, defaulting to PayAI free tier. */
+export declare function resolveFacilitator(config: X402FacilitatorConfig | undefined): X402FacilitatorConfig;
+/**
+ * Build standard headers for a facilitator request. When an Ed25519 auth
+ * token is configured, attach `Authorization: Bearer <token>`. Otherwise
+ * the request hits the PayAI free-tier endpoint (no auth required).
+ */
+export declare function buildFacilitatorHeaders(config: X402FacilitatorConfig): Record<string, string>;
+/**
+ * Call the facilitator's `/verify` endpoint. Returns the parsed verification
+ * result. Re-wraps every failure path as a tagged X402FacilitatorError so
+ * no upstream response body leaks through.
+ */
+export declare function facilitatorVerify(config: X402FacilitatorConfig, body: unknown, fetchImpl?: typeof fetch): Promise<FacilitatorVerifyResult>;
+/**
+ * Call the facilitator's `/settle` endpoint. Returns the parsed settle
+ * result (including the on-chain tx hash on success).
+ */
+export declare function facilitatorSettle(config: X402FacilitatorConfig, body: unknown, fetchImpl?: typeof fetch): Promise<FacilitatorSettleResult>;
+//# sourceMappingURL=facilitator.d.ts.map

package/dist/cjs/facilitator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../src/facilitator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAChC,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGlF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GACxC,qBAAqB,CAKvB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,qBAAqB,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,OAAO,EACb,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAsBlC;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,OAAO,EACb,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAsBlC"}