@shroud-fi/x402 0.1.0

package/dist/esm/constants.js

@@ -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 const X402_VERSION = 2;
+/** Default EIP-3009 authorization validity window (seconds). */
+export const DEFAULT_AUTHORIZATION_TTL_SECS = 300;
+/** Default facilitator `maxTimeoutSeconds` echoed back in PaymentRequired. */
+export const DEFAULT_MAX_TIMEOUT_SECS = 300;
+//# sourceMappingURL=constants.js.map

package/dist/esm/constants.js.map

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

package/dist/esm/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/esm/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/esm/errors.js

@@ -0,0 +1,73 @@
+/**
+ * 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 class X402Error extends Error {
+    name = 'X402Error';
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * The 402 challenge body (or its header) could not be parsed / is malformed.
+ * Catch-all for "we received something the spec disallows".
+ */
+export class X402InvalidChallengeError extends X402Error {
+    name = 'X402InvalidChallengeError';
+    constructor() {
+        super('Invalid x402 challenge payload');
+    }
+}
+/**
+ * The signed `PAYMENT-SIGNATURE` payload submitted by the client could not be
+ * verified against the challenge (signer mismatch, malformed JSON, expired
+ * authorization, etc).
+ */
+export class X402SignatureVerificationError extends X402Error {
+    name = 'X402SignatureVerificationError';
+    constructor() {
+        super('x402 signed payment payload failed verification');
+    }
+}
+/**
+ * Facilitator HTTP call (verify or settle) failed. Tag identifies the
+ * facilitator stage but never carries response body, token amount, or signed
+ * payload.
+ */
+export class X402FacilitatorError extends X402Error {
+    name = 'X402FacilitatorError';
+    constructor(stage) {
+        super(`x402 facilitator request failed (stage=${stage})`);
+    }
+}
+/**
+ * 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 class X402AssetNotSupportedError extends X402Error {
+    name = 'X402AssetNotSupportedError';
+    constructor() {
+        super('x402: requested asset is not supported on the configured chain');
+    }
+}
+/**
+ * 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 class X402AmountMismatchError extends X402Error {
+    name = 'X402AmountMismatchError';
+    constructor() {
+        super('x402: payment amount exceeds caller cap or does not match challenge');
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

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

package/dist/esm/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/esm/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"}

package/dist/esm/facilitator.js

@@ -0,0 +1,100 @@
+/**
+ * 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 { PAYAI_FACILITATOR_URL } from './protocol.js';
+import { X402FacilitatorError } from './errors.js';
+/** Resolve the facilitator config, defaulting to PayAI free tier. */
+export function resolveFacilitator(config) {
+    if (config === undefined) {
+        return { url: PAYAI_FACILITATOR_URL };
+    }
+    return config;
+}
+/**
+ * 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 function buildFacilitatorHeaders(config) {
+    const headers = {
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    if (config.ed25519AuthToken !== undefined) {
+        headers['authorization'] = `Bearer ${config.ed25519AuthToken}`;
+    }
+    return headers;
+}
+/**
+ * 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 async function facilitatorVerify(config, body, fetchImpl = fetch) {
+    const url = `${config.url.replace(/\/+$/, '')}/verify`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'POST',
+            headers: buildFacilitatorHeaders(config),
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        throw new X402FacilitatorError('network');
+    }
+    if (!res.ok) {
+        throw new X402FacilitatorError('verify');
+    }
+    let parsed;
+    try {
+        parsed = (await res.json());
+    }
+    catch {
+        throw new X402FacilitatorError('verify');
+    }
+    return parsed;
+}
+/**
+ * Call the facilitator's `/settle` endpoint. Returns the parsed settle
+ * result (including the on-chain tx hash on success).
+ */
+export async function facilitatorSettle(config, body, fetchImpl = fetch) {
+    const url = `${config.url.replace(/\/+$/, '')}/settle`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'POST',
+            headers: buildFacilitatorHeaders(config),
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        throw new X402FacilitatorError('network');
+    }
+    if (!res.ok) {
+        throw new X402FacilitatorError('settle');
+    }
+    let parsed;
+    try {
+        parsed = (await res.json());
+    }
+    catch {
+        throw new X402FacilitatorError('settle');
+    }
+    return parsed;
+}
+//# sourceMappingURL=facilitator.js.map

package/dist/esm/facilitator.js.map

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

package/dist/esm/index.d.ts

@@ -0,0 +1,8 @@
+export { createX402Server } from './server.js';
+export type { X402Server, X402ServerConfig, X402Challenge, X402PaymentRequirements, X402PaymentVerification, } from './server.js';
+export { createX402Client } from './client.js';
+export type { X402Client, X402ClientConfig, X402PaymentResult, } from './client.js';
+export { X402_PAYMENT_REQUIRED_HEADER, X402_PAYMENT_SIGNATURE_HEADER, X402_PAYMENT_RESPONSE_HEADER, X402_SCHEME_EXACT, PAYAI_FACILITATOR_URL, COINBASE_FACILITATOR_URL, } from './protocol.js';
+export type { X402PaymentPayload, X402SchemeId, X402FacilitatorConfig, } from './protocol.js';
+export { X402Error, X402InvalidChallengeError, X402SignatureVerificationError, X402FacilitatorError, X402AssetNotSupportedError, X402AmountMismatchError, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,SAAS,EACT,yBAAyB,EACzB,8BAA8B,EAC9B,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,12 @@
+// Public surface — @shroud-fi/x402
+// HTTP 402 + stealth-address payment routing for AI agents on Base.
+// See packages/x402/README and docs/research/competitive/x402-spec-and-ecosystem.md.
+// Server side
+export { createX402Server } from './server.js';
+// Client side
+export { createX402Client } from './client.js';
+// Protocol constants + types
+export { X402_PAYMENT_REQUIRED_HEADER, X402_PAYMENT_SIGNATURE_HEADER, X402_PAYMENT_RESPONSE_HEADER, X402_SCHEME_EXACT, PAYAI_FACILITATOR_URL, COINBASE_FACILITATOR_URL, } from './protocol.js';
+// Errors
+export { X402Error, X402InvalidChallengeError, X402SignatureVerificationError, X402FacilitatorError, X402AssetNotSupportedError, X402AmountMismatchError, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,oEAAoE;AACpE,qFAAqF;AAErF,cAAc;AACd,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAS/C,cAAc;AACd,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAO/C,6BAA6B;AAC7B,OAAO,EACL,4BAA4B,EAC5B,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAOvB,SAAS;AACT,OAAO,EACL,SAAS,EACT,yBAAyB,EACzB,8BAA8B,EAC9B,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/esm/protocol.d.ts

@@ -0,0 +1,117 @@
+/**
+ * x402 protocol constants + wire types.
+ *
+ * v2 spec only. See docs/research/competitive/x402-spec-and-ecosystem.md §1
+ * for the canonical field names. v1 (whitepaper, deprecated) names are not
+ * accepted by this package.
+ */
+import type { Address, Hex } from 'viem';
+/** Server → client: 402 challenge envelope (raw JSON, no base64 in v2). */
+export declare const X402_PAYMENT_REQUIRED_HEADER: "X-PAYMENT-REQUIRED";
+/**
+ * Client → server: signed PaymentPayload (base64-encoded JSON).
+ *
+ * Canonical name per the v2 spec is `X-PAYMENT`. Older drafts and some
+ * SDKs use `X-PAYMENT-SIGNATURE`; we use `X-PAYMENT` to stay aligned with
+ * the foundation SDKs (`@x402/fetch`, `@x402/axios`, `@x402/express` all
+ * read `X-PAYMENT`).
+ */
+export declare const X402_PAYMENT_SIGNATURE_HEADER: "X-PAYMENT";
+/** Server → client: settlement confirmation (base64-encoded JSON, on 2xx). */
+export declare const X402_PAYMENT_RESPONSE_HEADER: "X-PAYMENT-RESPONSE";
+/** "Exact" scheme — seller knows price up front. Only scheme we support in v1. */
+export declare const X402_SCHEME_EXACT: "exact";
+export type X402SchemeId = typeof X402_SCHEME_EXACT;
+/**
+ * PayAI Network facilitator — free tier (≤ 10k settlements/mo) requires no
+ * authentication at all. Our default.
+ */
+export declare const PAYAI_FACILITATOR_URL: "https://facilitator.payai.network";
+/**
+ * Coinbase CDP facilitator — secondary. Requires CDP API key for use.
+ * URL verified against research doc §3 (cdp.coinbase.com/platform/v2/x402).
+ */
+export declare const COINBASE_FACILITATOR_URL: "https://api.cdp.coinbase.com/platform/v2/x402";
+/**
+ * The `accepts[N]` entry from a v2 `PaymentRequired` object — the exact shape
+ * a client receives over the wire.
+ *
+ * Field names match the spec verbatim (NOT the v1 whitepaper names — see
+ * research doc §10.1 for the drift table).
+ */
+export interface X402PaymentRequirements {
+    /** Scheme id; only `'exact'` supported in v1. */
+    readonly scheme: X402SchemeId;
+    /** CAIP-2 network id, e.g. `'eip155:8453'`. */
+    readonly network: string;
+    /**
+     * Maximum payment amount in token base units (string-encoded to survive
+     * uint256). For scheme `exact`, this is the exact required amount.
+     *
+     * Spec field name: `maxAmountRequired`. We mirror it verbatim.
+     */
+    readonly maxAmountRequired: string;
+    /** ERC-20 contract address of the asset. */
+    readonly asset: Address;
+    /**
+     * Recipient address. In ShroudFi servers this is ALWAYS a freshly derived
+     * stealth address — never the server's main wallet.
+     */
+    readonly payTo: Address;
+    /** Authorization validity window (seconds). */
+    readonly maxTimeoutSeconds: number;
+    /** Resource being paid for (URL or pseudo-URL). */
+    readonly resource: string;
+    /** Optional human-readable description. */
+    readonly description?: string;
+    /**
+     * Scheme-specific extra data. For `exact` on EVM, contains the EIP-712
+     * domain `name` + `version` for the asset (so the client can rebuild the
+     * domain separator without having to look the token up).
+     */
+    readonly extra: {
+        readonly name: string;
+        readonly version: string;
+        /**
+         * ShroudFi-specific extension: emitted so a ShroudFi-aware client can
+         * relay the Announcement event after settlement. Forward-compatible —
+         * non-ShroudFi clients ignore unknown keys.
+         */
+        readonly shroudfiAnnouncement?: {
+            readonly ephemeralPubKey: Hex;
+            readonly viewTag: number;
+        };
+    };
+}
+/**
+ * The signed payload the client sends back in `X-PAYMENT`. EIP-3009
+ * `transferWithAuthorization` shape.
+ */
+export interface X402PaymentPayload {
+    readonly x402Version: 2;
+    readonly scheme: X402SchemeId;
+    readonly network: string;
+    readonly payload: {
+        readonly signature: Hex;
+        readonly authorization: {
+            readonly from: Address;
+            readonly to: Address;
+            /** uint256 as string. */
+            readonly value: string;
+            readonly validAfter: string;
+            readonly validBefore: string;
+            readonly nonce: Hex;
+        };
+    };
+}
+/**
+ * Optional facilitator config. When unset, the default is PayAI free-tier
+ * (no auth). When `ed25519AuthToken` is provided, the facilitator client
+ * attaches `Authorization: Bearer <token>` to every request — caller is
+ * responsible for minting the JWT per PayAI's spec (research doc §10.5).
+ */
+export interface X402FacilitatorConfig {
+    readonly url: string;
+    readonly ed25519AuthToken?: string;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/esm/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAIzC,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B,EAAG,oBAA6B,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAG,WAAoB,CAAC;AAElE,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,EAAG,oBAA6B,CAAC;AAI1E,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,EAAG,OAAgB,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG,OAAO,iBAAiB,CAAC;AAIpD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAChC,mCAA4C,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EACnC,+CAAwD,CAAC;AAI3D;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB;;;;WAIG;QACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE;YAC9B,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC;YAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;SAC1B,CAAC;KACH,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC;QACxB,QAAQ,CAAC,aAAa,EAAE;YACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;YACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;YACrB,yBAAyB;YACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;YAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;YAC7B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;SACrB,CAAC;KACH,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC"}

package/dist/esm/protocol.js

@@ -0,0 +1,36 @@
+/**
+ * x402 protocol constants + wire types.
+ *
+ * v2 spec only. See docs/research/competitive/x402-spec-and-ecosystem.md §1
+ * for the canonical field names. v1 (whitepaper, deprecated) names are not
+ * accepted by this package.
+ */
+// ─── HTTP header names ───────────────────────────────────────────────────────
+/** Server → client: 402 challenge envelope (raw JSON, no base64 in v2). */
+export const X402_PAYMENT_REQUIRED_HEADER = 'X-PAYMENT-REQUIRED';
+/**
+ * Client → server: signed PaymentPayload (base64-encoded JSON).
+ *
+ * Canonical name per the v2 spec is `X-PAYMENT`. Older drafts and some
+ * SDKs use `X-PAYMENT-SIGNATURE`; we use `X-PAYMENT` to stay aligned with
+ * the foundation SDKs (`@x402/fetch`, `@x402/axios`, `@x402/express` all
+ * read `X-PAYMENT`).
+ */
+export const X402_PAYMENT_SIGNATURE_HEADER = 'X-PAYMENT';
+/** Server → client: settlement confirmation (base64-encoded JSON, on 2xx). */
+export const X402_PAYMENT_RESPONSE_HEADER = 'X-PAYMENT-RESPONSE';
+// ─── Scheme identifiers ──────────────────────────────────────────────────────
+/** "Exact" scheme — seller knows price up front. Only scheme we support in v1. */
+export const X402_SCHEME_EXACT = 'exact';
+// ─── Facilitator URLs ────────────────────────────────────────────────────────
+/**
+ * PayAI Network facilitator — free tier (≤ 10k settlements/mo) requires no
+ * authentication at all. Our default.
+ */
+export const PAYAI_FACILITATOR_URL = 'https://facilitator.payai.network';
+/**
+ * Coinbase CDP facilitator — secondary. Requires CDP API key for use.
+ * URL verified against research doc §3 (cdp.coinbase.com/platform/v2/x402).
+ */
+export const COINBASE_FACILITATOR_URL = 'https://api.cdp.coinbase.com/platform/v2/x402';
+//# sourceMappingURL=protocol.js.map

package/dist/esm/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,gFAAgF;AAEhF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,4BAA4B,GAAG,oBAA6B,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,WAAoB,CAAC;AAElE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,4BAA4B,GAAG,oBAA6B,CAAC;AAE1E,gFAAgF;AAEhF,kFAAkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAgB,CAAC;AAIlD,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAChC,mCAA4C,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,+CAAwD,CAAC"}

package/dist/esm/server.d.ts

@@ -0,0 +1,49 @@
+/**
+ * x402 server — challenge generation + signed-payment verification.
+ *
+ * Privacy invariants enforced here:
+ *   - Every challenge derives a FRESH stealth address from the recipient's
+ *     meta-address. The recipient's main wallet NEVER appears in the
+ *     PaymentRequired body.
+ *   - The facilitator is only ever shown the stealth `payTo` — same property.
+ *   - Error paths never include amount values, signature bytes, or the
+ *     server's spend key.
+ */
+import { type X402PaymentPayload } from './protocol.js';
+import type { X402Challenge, X402PaymentVerification, X402ServerConfig } from './types.js';
+export interface X402Server {
+    /**
+     * Build a 402 challenge for a given resource. Each call derives a fresh
+     * stealth address — calls are deliberately non-idempotent.
+     */
+    challenge(args: {
+        resource: string;
+        description?: string;
+        priceAtomic?: bigint;
+    }): Promise<X402Challenge>;
+    /**
+     * Verify a signed payload submitted by the client. Optionally settles via
+     * the configured facilitator.
+     *
+     * When `skipFacilitator: true` is passed, verify returns `valid: true` after
+     * signature recovery succeeds and does NOT contact the facilitator. The
+     * caller is then responsible for settling the EIP-3009 authorization on-chain
+     * itself (e.g. by calling `USDC.transferWithAuthorization` directly through
+     * its own walletClient). Use this when the operator runs its own settler EOA
+     * and does not want a facilitator in the trust chain — e.g. headless
+     * agent-to-agent demos, anon-stack deployments.
+     */
+    verify(args: {
+        signedPayload: string | X402PaymentPayload;
+        challenge: X402Challenge;
+        skipFacilitator?: boolean;
+    }): Promise<X402PaymentVerification>;
+}
+/**
+ * Build an X402Server bound to a single recipient meta-address + asset.
+ */
+export declare function createX402Server(config: X402ServerConfig): X402Server;
+/** Re-export so consumers don't have to dig into types.ts. */
+export type { X402Challenge, X402PaymentVerification, X402ServerConfig, } from './types.js';
+export type { X402PaymentRequirements } from './protocol.js';
+//# sourceMappingURL=server.d.ts.map

package/dist/esm/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,eAAe,CAAC;AAMvB,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EACvB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAmCpB,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE;QACX,aAAa,EAAE,MAAM,GAAG,kBAAkB,CAAC;QAC3C,SAAS,EAAE,aAAa,CAAC;QACzB,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA2MrE;AAED,8DAA8D;AAC9D,YAAY,EACV,aAAa,EACb,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC"}