@bankofai/x402 0.5.8 → 0.6.0-beta.0

package/README.md

@@ -2,6 +2,12 @@
 
 TypeScript SDK for the x402 payment protocol. Supports TRON and EVM (BSC) networks with automatic HTTP 402 payment handling.
 
+## Compatibility Notes
+
+- The EVM `exact` flow is being aligned to the Coinbase x402 v2 payload shape.
+- Exact transfer authorizations are emitted in `payload.authorization`.
+- Migration fallback support for the legacy `extensions.transferAuthorization` field remains on the server side while compatibility is rolled out.
+
 ## Features
 
 - 🔐 **Automatic Payment Handling** - Transparently handles HTTP 402 Payment Required responses
@@ -40,6 +46,12 @@ const data = await response.json();
 console.log(data);
 ```
 
+## BSC Testnet Example
+
+For a smoke-tested BSC testnet `exact` example that uses a local private key and targets the Coinbase-compatible `exact` route, see [`examples/bsc-testnet-smoke/README.md`](../../../examples/bsc-testnet-smoke/README.md).
+
+The BSC `exact` path in this repository is aligned around ERC-3009. On testnet, the validated asset is `DHLU`, not generic USDT/USDC permit-only flows.
+
 ## Core Concepts
 
 ### Payment Flow
@@ -310,6 +322,8 @@ Allows users to pay using TRC-20 tokens (USDT/USDD) without holding any TRX for
 
 Direct payment scheme using ERC-3009 (`TransferWithAuthorization`) where supported by the token contract (primarily for EVM networks like BSC).
 
+For BSC testnet interoperability, treat token choice as part of the protocol contract. If the endpoint advertises `exact`, the asset must actually implement ERC-3009. The smoke-tested example in this repository uses `DHLU` on `eip155:97`.
+
 ## Security
 
 - **Never commit private keys** - Use environment variables

package/dist/client/x402Client.js

@@ -3,7 +3,7 @@
  *
  * Manages payment mechanism registry and coordinates payment flows.
  */
-import { ExactGasFreeClientMechanism } from '../mechanisms/exactGasfree.js';
+import { ExactGasFreeClientMechanism } from '../mechanisms/tron/exact_gasfree/index.js';
 import { DefaultTokenSelectionStrategy } from './tokenSelection.js';
 import { UnsupportedNetworkError } from '../errors.js';
 /**

package/dist/client/x402Client.js.map

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

package/dist/errors.d.ts

@@ -38,4 +38,12 @@ export declare class PermitValidationError extends ValidationError {
     reason: string;
     constructor(reason: string, message?: string);
 }
+/** Facilitator HTTP / protocol error */
+export declare class FacilitatorError extends X402Error {
+    /** HTTP status code returned by facilitator (0 if request itself failed) */
+    status: number;
+    /** Response body, decoded as text or null if unavailable */
+    body: string | null;
+    constructor(message: string, status: number, body?: string | null);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qCAAqC;AACrC,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,8BAA8B;AAC9B,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,gCAAgC;AAChC,qBAAa,sBAAuB,SAAQ,cAAc;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED,8BAA8B;AAC9B,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,6BAA6B;AAC7B,qBAAa,0BAA2B,SAAQ,cAAc;gBAChD,OAAO,EAAE,MAAM;CAI5B;AAED,kCAAkC;AAClC,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,0BAA0B;AAC1B,qBAAa,uBAAwB,SAAQ,kBAAkB;gBACjD,OAAO,EAAE,MAAM;CAI5B;AAED,+BAA+B;AAC/B,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,+BAA+B;AAC/B,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,MAAM,EAAE,MAAM,CAAC;gBAEH,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK7C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qCAAqC;AACrC,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,8BAA8B;AAC9B,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,gCAAgC;AAChC,qBAAa,sBAAuB,SAAQ,cAAc;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED,8BAA8B;AAC9B,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,6BAA6B;AAC7B,qBAAa,0BAA2B,SAAQ,cAAc;gBAChD,OAAO,EAAE,MAAM;CAI5B;AAED,kCAAkC;AAClC,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,0BAA0B;AAC1B,qBAAa,uBAAwB,SAAQ,kBAAkB;gBACjD,OAAO,EAAE,MAAM;CAI5B;AAED,+BAA+B;AAC/B,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,+BAA+B;AAC/B,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,MAAM,EAAE,MAAM,CAAC;gBAEH,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK7C;AAED,wCAAwC;AACxC,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;gBAER,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,IAAW;CAMxE"}

package/dist/errors.js

@@ -66,4 +66,17 @@ export class PermitValidationError extends ValidationError {
         this.reason = reason;
     }
 }
+/** Facilitator HTTP / protocol error */
+export class FacilitatorError extends X402Error {
+    /** HTTP status code returned by facilitator (0 if request itself failed) */
+    status;
+    /** Response body, decoded as text or null if unavailable */
+    body;
+    constructor(message, status, body = null) {
+        super(message);
+        this.name = 'FacilitatorError';
+        this.status = status;
+        this.body = body;
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qCAAqC;AACrC,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,8BAA8B;AAC9B,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,gCAAgC;AAChC,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,8BAA8B;AAC9B,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,6BAA6B;AAC7B,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,kCAAkC;AAClC,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,0BAA0B;AAC1B,MAAM,OAAO,uBAAwB,SAAQ,kBAAkB;IAC7D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACxD,MAAM,CAAS;IAEf,YAAY,MAAc,EAAE,OAAgB;QAC1C,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qCAAqC;AACrC,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,8BAA8B;AAC9B,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,gCAAgC;AAChC,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IACxD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,8BAA8B;AAC9B,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,6BAA6B;AAC7B,MAAM,OAAO,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,kCAAkC;AAClC,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,0BAA0B;AAC1B,MAAM,OAAO,uBAAwB,SAAQ,kBAAkB;IAC7D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACxD,MAAM,CAAS;IAEf,YAAY,MAAc,EAAE,OAAgB;QAC1C,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,wCAAwC;AACxC,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IAC7C,4EAA4E;IAC5E,MAAM,CAAS;IACf,4DAA4D;IAC5D,IAAI,CAAgB;IAEpB,YAAY,OAAe,EAAE,MAAc,EAAE,OAAsB,IAAI;QACrE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/facilitator/client.d.ts

@@ -0,0 +1,77 @@
+/**
+ * FacilitatorClient — TypeScript port of `bankofai.x402.facilitator.FacilitatorClient`.
+ *
+ * Talks to a remote x402 facilitator via HTTP. Handles `/supported`, `/fee/quote`,
+ * `/verify`, `/settle`. Used by server middleware (Hono / Express / etc.) to verify
+ * payments off-chain and trigger on-chain settlement.
+ */
+import type { FeeQuoteResponse, PaymentPayload, PaymentRequirements, SettleResponse, SupportedResponse, VerifyResponse } from '../types/index.js';
+/** Configuration for {@link FacilitatorClient}. */
+export interface FacilitatorClientConfig {
+    /** Facilitator service base URL (trailing slash optional, will be normalized). */
+    baseUrl: string;
+    /** Optional custom HTTP headers (e.g. `Authorization`). */
+    headers?: Record<string, string>;
+    /** Stable identifier for this facilitator. Defaults to `baseUrl`. */
+    facilitatorId?: string;
+    /** Per-request timeout in milliseconds. Defaults to 120 000 (120 s). */
+    timeoutMs?: number;
+    /** Custom fetch implementation (defaults to global `fetch`). Useful for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Optional payment context forwarded to `/fee/quote`.
+ *
+ * Wire field is `paymentPermitContext` to match the facilitator API; the client
+ * accepts a plain JSON-shaped object and forwards it as-is.
+ */
+export type FeeQuoteContext = Record<string, unknown>;
+/**
+ * HTTP client for an x402 facilitator service.
+ *
+ * Mirrors the Python `FacilitatorClient` interface 1:1 so server middleware on
+ * either runtime sees the same shape.
+ */
+export declare class FacilitatorClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    /** Stable identifier for this facilitator (defaults to `baseUrl`). */
+    readonly facilitatorId: string;
+    constructor(config: FacilitatorClientConfig);
+    /**
+     * Query facilitator's supported (`x402Version`, `scheme`, `network`) tuples.
+     */
+    supported(): Promise<SupportedResponse>;
+    /**
+     * Request fee quotes for a list of payment requirements.
+     *
+     * @param accepts - The same `accepts[]` you would put in `PaymentRequired`.
+     * @param context - Optional `paymentPermitContext`.
+     */
+    feeQuote(accepts: PaymentRequirements[], context?: FeeQuoteContext): Promise<FeeQuoteResponse[]>;
+    /**
+     * Verify a payment payload off-chain (no on-chain transaction).
+     *
+     * Server middleware should call this **before** routing the actual request
+     * handler — only proceed to settlement if {@link VerifyResponse.isValid} is true.
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Execute on-chain settlement for a verified payment.
+     *
+     * Returns a {@link SettleResponse} carrying the transaction hash on success
+     * or an `errorReason` on failure.
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Symmetry with the Python client. The TS implementation uses the global
+     * `fetch` (no persistent connection pool to close); this is a no-op kept for
+     * API parity so callers can write the same teardown logic on both runtimes.
+     */
+    close(): Promise<void>;
+    private requestJson;
+    private safeReadText;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/facilitator/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,mDAAmD;AACnD,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAID;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,uBAAuB;IAQ3C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAI7C;;;;;OAKG;IACG,QAAQ,CACZ,OAAO,EAAE,mBAAmB,EAAE,EAC9B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAQ9B;;;;;OAKG;IACG,MAAM,CACV,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;IAO1B;;;;;OAKG;IACG,MAAM,CACV,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;IAO1B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,WAAW;YA2DX,YAAY;CAO3B"}

package/dist/facilitator/client.js

@@ -0,0 +1,130 @@
+/**
+ * FacilitatorClient — TypeScript port of `bankofai.x402.facilitator.FacilitatorClient`.
+ *
+ * Talks to a remote x402 facilitator via HTTP. Handles `/supported`, `/fee/quote`,
+ * `/verify`, `/settle`. Used by server middleware (Hono / Express / etc.) to verify
+ * payments off-chain and trigger on-chain settlement.
+ */
+import { FacilitatorError } from '../errors.js';
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * HTTP client for an x402 facilitator service.
+ *
+ * Mirrors the Python `FacilitatorClient` interface 1:1 so server middleware on
+ * either runtime sees the same shape.
+ */
+export class FacilitatorClient {
+    baseUrl;
+    headers;
+    timeoutMs;
+    fetchImpl;
+    /** Stable identifier for this facilitator (defaults to `baseUrl`). */
+    facilitatorId;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.headers = { ...(config.headers ?? {}) };
+        this.facilitatorId = config.facilitatorId ?? this.baseUrl;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = config.fetchImpl ?? fetch;
+    }
+    /**
+     * Query facilitator's supported (`x402Version`, `scheme`, `network`) tuples.
+     */
+    async supported() {
+        return this.requestJson('GET', '/supported');
+    }
+    /**
+     * Request fee quotes for a list of payment requirements.
+     *
+     * @param accepts - The same `accepts[]` you would put in `PaymentRequired`.
+     * @param context - Optional `paymentPermitContext`.
+     */
+    async feeQuote(accepts, context) {
+        const body = { accepts };
+        if (context !== undefined) {
+            body.paymentPermitContext = context;
+        }
+        return this.requestJson('POST', '/fee/quote', body);
+    }
+    /**
+     * Verify a payment payload off-chain (no on-chain transaction).
+     *
+     * Server middleware should call this **before** routing the actual request
+     * handler — only proceed to settlement if {@link VerifyResponse.isValid} is true.
+     */
+    async verify(payload, requirements) {
+        return this.requestJson('POST', '/verify', {
+            paymentPayload: payload,
+            paymentRequirements: requirements,
+        });
+    }
+    /**
+     * Execute on-chain settlement for a verified payment.
+     *
+     * Returns a {@link SettleResponse} carrying the transaction hash on success
+     * or an `errorReason` on failure.
+     */
+    async settle(payload, requirements) {
+        return this.requestJson('POST', '/settle', {
+            paymentPayload: payload,
+            paymentRequirements: requirements,
+        });
+    }
+    /**
+     * Symmetry with the Python client. The TS implementation uses the global
+     * `fetch` (no persistent connection pool to close); this is a no-op kept for
+     * API parity so callers can write the same teardown logic on both runtimes.
+     */
+    async close() {
+        // no-op — `fetch` does not require explicit cleanup
+    }
+    async requestJson(method, path, body) {
+        const url = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const init = {
+            method,
+            headers: {
+                Accept: 'application/json',
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                ...this.headers,
+            },
+            signal: controller.signal,
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(url, init);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new FacilitatorError(`Facilitator request to ${path} timed out after ${this.timeoutMs}ms`, 0);
+            }
+            throw new FacilitatorError(`Facilitator request to ${path} failed: ${err.message}`, 0);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const text = await this.safeReadText(response);
+            throw new FacilitatorError(`Facilitator returned HTTP ${response.status} for ${path}`, response.status, text);
+        }
+        try {
+            return (await response.json());
+        }
+        catch (err) {
+            throw new FacilitatorError(`Facilitator response from ${path} was not valid JSON: ${err.message}`, response.status);
+        }
+    }
+    async safeReadText(response) {
+        try {
+            return await response.text();
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/facilitator/client.js.map

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

package/dist/facilitator/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Facilitator surface for the x402 payment protocol.
+ *
+ * - {@link FacilitatorClient} — talks to a remote facilitator (used by server middleware)
+ * - {@link X402Facilitator} — in-process payment processor (the engine of a facilitator service)
+ *
+ * Re-exported via the package root so consumers can `import { FacilitatorClient,
+ * X402Facilitator } from '@bankofai/x402'`.
+ */
+export { FacilitatorClient } from './client.js';
+export type { FacilitatorClientConfig, FeeQuoteContext } from './client.js';
+export { X402Facilitator } from './x402Facilitator.js';
+export type { FacilitatorMechanism, FacilitatorLogger } from './x402Facilitator.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/facilitator/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/facilitator/index.js

@@ -0,0 +1,12 @@
+/**
+ * Facilitator surface for the x402 payment protocol.
+ *
+ * - {@link FacilitatorClient} — talks to a remote facilitator (used by server middleware)
+ * - {@link X402Facilitator} — in-process payment processor (the engine of a facilitator service)
+ *
+ * Re-exported via the package root so consumers can `import { FacilitatorClient,
+ * X402Facilitator } from '@bankofai/x402'`.
+ */
+export { FacilitatorClient } from './client.js';
+export { X402Facilitator } from './x402Facilitator.js';
+//# sourceMappingURL=index.js.map

package/dist/facilitator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/facilitator/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/facilitator/x402Facilitator.d.ts

@@ -0,0 +1,97 @@
+/**
+ * X402Facilitator — TypeScript port of `bankofai.x402.facilitator.X402Facilitator`.
+ *
+ * The core in-process payment processor for an x402 facilitator service.
+ * Manages a registry of {@link FacilitatorMechanism}s keyed by `(network, scheme)`
+ * and routes verify / settle / feeQuote calls to the right implementation.
+ *
+ * This is the *engine* — wrap it with an HTTP server (Hono / Express / Fastify)
+ * to expose `/verify`, `/settle`, `/supported`, `/fee/quote` endpoints.
+ */
+import type { FeeQuoteResponse, PaymentPayload, PaymentRequirements, SettleResponse, SupportedResponse, VerifyResponse } from '../types/index.js';
+/**
+ * Server-side mechanism interface for the facilitator.
+ *
+ * One per `(network, scheme)` pair. Implementations live in the chain-specific
+ * mechanism packages (TRON / EVM / etc.) — this interface keeps the facilitator
+ * core agnostic of any particular chain.
+ */
+export interface FacilitatorMechanism {
+    /** Scheme name this mechanism handles (e.g. `"exact"`, `"exact_permit"`). */
+    scheme(): string;
+    /**
+     * Optional fee quote for a single requirement. Return `null` when this
+     * mechanism cannot quote the requirement (e.g. token not in registry).
+     */
+    feeQuote(accept: PaymentRequirements, context?: Record<string, unknown>): Promise<FeeQuoteResponse | null>;
+    /** Off-chain signature / replay / timing verification. */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /** On-chain settlement. */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+}
+/** Optional logger interface for observability hooks. */
+export interface FacilitatorLogger {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * In-process payment processor. Mirrors the Python `X402Facilitator` 1:1.
+ *
+ * @example
+ * ```ts
+ * const facilitator = new X402Facilitator()
+ *   .register(['tron:nile'], tronExactMechanism)
+ *   .register(['eip155:97'], bscExactPermitMechanism);
+ *
+ * const verifyResult = await facilitator.verify(payload, requirements);
+ * if (verifyResult.isValid) {
+ *   const settleResult = await facilitator.settle(payload, requirements);
+ * }
+ * ```
+ */
+export declare class X402Facilitator {
+    /** network → scheme → mechanism */
+    private readonly mechanisms;
+    private readonly logger;
+    constructor(opts?: {
+        logger?: FacilitatorLogger;
+    });
+    /**
+     * Register a mechanism for a list of networks. Returns `this` for chaining.
+     */
+    register(networks: string[], mechanism: FacilitatorMechanism): this;
+    /** Snapshot of registered `(x402Version, scheme, network)` triples. */
+    supported(): SupportedResponse;
+    /**
+     * Fee quotes for a list of requirements. Unsupported `(network, scheme)` /
+     * mechanisms returning `null` are silently skipped — the result list may be
+     * shorter than the input. Per-mechanism exceptions surface as a thrown
+     * `Error` (caller decides whether to 4xx or 5xx the HTTP request).
+     */
+    feeQuote(accepts: PaymentRequirements[], context?: Record<string, unknown>): Promise<FeeQuoteResponse[]>;
+    /**
+     * Verify a payment payload off-chain. Always returns a {@link VerifyResponse};
+     * mechanism exceptions become `isValid: false` with the message as
+     * `invalidReason` and a logger.error entry.
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Execute on-chain settlement. Always returns a {@link SettleResponse};
+     * exceptions become `success: false` with `errorReason` set.
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    private findMechanism;
+    /**
+     * Strict variant — throws if any EVM address fails checksum. Used in verify /
+     * settle so the failure message ends up in the response.
+     */
+    private normalizeEvmRequirements;
+    /**
+     * Lenient variant for `feeQuote` — invalid-EVM-input requirements are simply
+     * skipped (returning the original so they can be filtered out by mechanism
+     * lookup miss).
+     */
+    private tryNormalizeEvmRequirements;
+    private checksumAddressStrict;
+}
+//# sourceMappingURL=x402Facilitator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"x402Facilitator.d.ts","sourceRoot":"","sources":["../../src/facilitator/x402Facilitator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,MAAM,IAAI,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CACN,MAAM,EAAE,mBAAmB,EAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACpC,0DAA0D;IAC1D,MAAM,CACJ,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,2BAA2B;IAC3B,MAAM,CACJ,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAOD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAe;IAC1B,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwD;IAEnF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;KAAE;IAIjD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,oBAAoB,GAAG,IAAI;IAanE,uEAAuE;IACvE,SAAS,IAAI,iBAAiB;IAU9B;;;;;OAKG;IACG,QAAQ,CACZ,OAAO,EAAE,mBAAmB,EAAE,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAuB9B;;;;OAIG;IACG,MAAM,CACV,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;IA0B1B;;;OAGG;IACG,MAAM,CACV,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;IAmC1B,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAyBhC;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAQnC,OAAO,CAAC,qBAAqB;CAM9B"}