@dexterai/x402 1.7.1 → 1.8.0

package/dist/server/index.d.cts

@@ -1,5 +1,5 @@
-import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, c as PayToProvider, d as PaymentRequired } from '../types-C6ty4U6C.cjs';
-export { g as AccessPassClaims, A as AccessPassClientConfig, b as AccessPassInfo, a as AccessPassTier, B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, e as PayToContext, f as PayToProviderDefaults, h as SOLANA_MAINNET_NETWORK, i as USDC_BASE, U as USDC_MINT } from '../types-C6ty4U6C.cjs';
+import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, c as PayToProvider, d as PaymentRequired } from '../types-DYLi7SuF.cjs';
+export { g as AccessPassClaims, A as AccessPassClientConfig, b as AccessPassInfo, a as AccessPassTier, B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, e as PayToContext, f as PayToProviderDefaults, h as SOLANA_MAINNET_NETWORK, i as USDC_BASE, U as USDC_MINT } from '../types-DYLi7SuF.cjs';
 import { Request, RequestHandler } from 'express';
 
 /**
@@ -10,6 +10,7 @@ import { Request, RequestHandler } from 'express';
  * - /verify - Verify a payment signature before processing
  * - /settle - Submit the payment for execution
  *
+ * Includes retry with exponential backoff and request timeouts.
  * Works with any x402 v2 facilitator (Dexter or others).
  */
 
@@ -33,6 +34,19 @@ interface SupportedKind {
  */
 interface SupportedResponse {
     kinds: SupportedKind[];
+    extensions?: string[];
+    signers?: Record<string, string[]>;
+}
+/**
+ * Configuration for retry and timeout behavior
+ */
+interface FacilitatorClientConfig {
+    /** Request timeout in milliseconds @default 10000 */
+    timeoutMs?: number;
+    /** Maximum retry attempts for verify/settle @default 3 */
+    maxRetries?: number;
+    /** Base delay between retries in milliseconds (doubles each attempt) @default 500 */
+    retryBaseMs?: number;
 }
 /**
  * Client for communicating with an x402 v2 facilitator
@@ -42,40 +56,33 @@ declare class FacilitatorClient {
     private cachedSupported;
     private cacheTime;
     private readonly CACHE_TTL_MS;
-    constructor(facilitatorUrl?: string);
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    constructor(facilitatorUrl?: string, config?: FacilitatorClientConfig);
+    private fetchWithTimeout;
+    private fetchWithRetry;
     /**
-     * Get supported payment kinds from the facilitator
-     * Results are cached for 1 minute to reduce network calls
+     * Get supported payment kinds from the facilitator.
+     * Results are cached for 1 minute to reduce network calls.
      */
     getSupported(): Promise<SupportedResponse>;
     /**
      * Get the fee payer address for a specific network
-     *
-     * @param network - CAIP-2 network identifier
-     * @returns Fee payer address
      */
     getFeePayer(network: string): Promise<string>;
     /**
      * Get extra data for a network (feePayer, decimals, EIP-712 data, etc.)
-     *
-     * @param network - CAIP-2 network identifier
-     * @returns Extra data from /supported
      */
     getNetworkExtra(network: string): Promise<SupportedKind['extra']>;
     /**
-     * Verify a payment with the facilitator
-     *
-     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
-     * @param requirements - The payment requirements that were sent to the client
-     * @returns Verification response
+     * Verify a payment with the facilitator.
+     * Retries on 5xx and network errors with exponential backoff.
      */
     verifyPayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<VerifyResponse>;
     /**
-     * Settle a payment with the facilitator
-     *
-     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
-     * @param requirements - The payment requirements that were sent to the client
-     * @returns Settlement response with transaction signature on success
+     * Settle a payment with the facilitator.
+     * Retries on 5xx and network errors with exponential backoff.
      */
     settlePayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<SettleResponse>;
 }
@@ -225,32 +232,48 @@ declare function createX402Server(config: X402ServerConfig): X402Server;
  */
 interface X402MiddlewareConfig {
     /**
-     * Address to receive payments, or a dynamic provider function.
+     * Address to receive payments, or a dynamic provider function, or
+     * a map of network-specific addresses for multi-chain support.
      *
      * - **Static address**: Pass a Solana pubkey or EVM address string.
-     * - **Stripe**: Use `stripePayTo(process.env.STRIPE_SECRET_KEY)` to generate
-     *   per-request deposit addresses. Payments land in your Stripe Dashboard.
+     * - **Stripe**: Use `stripePayTo(process.env.STRIPE_SECRET_KEY)` for Base.
+     * - **Multi-chain map**: Keys are CAIP-2 networks or globs (`eip155:*`, `*`).
      *
      * @example
      * ```typescript
-     * // Static address
+     * // Single address (works on one network)
      * payTo: '0xYourAddress...'
      *
-     * // Stripe machine payments
-     * payTo: stripePayTo(process.env.STRIPE_SECRET_KEY)
+     * // Stripe on Base, direct wallet on other chains
+     * payTo: { 'eip155:8453': stripePayTo(key), '*': '0xYourAddress...' }
+     *
+     * // Solana + EVM
+     * payTo: { 'solana:*': 'SolAddr', 'eip155:*': '0xEvmAddr' }
      * ```
      */
-    payTo: string | PayToProvider;
+    payTo: string | PayToProvider | Record<string, string | PayToProvider>;
     /**
      * Payment amount in USD (e.g., '0.01' for 1 cent)
      * Will be converted to atomic units automatically.
      */
     amount: string;
     /**
-     * CAIP-2 network identifier
+     * CAIP-2 network identifier(s).
+     * Pass an array to accept payments on multiple chains simultaneously.
+     * The client picks whichever chain it has a wallet for.
+     *
      * @default 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' (Solana mainnet)
+     *
+     * @example
+     * ```typescript
+     * // Single network
+     * network: 'eip155:8453'
+     *
+     * // Multiple EVM chains (same payTo address works for all)
+     * network: ['eip155:8453', 'eip155:137', 'eip155:42161']
+     * ```
      */
-    network?: string;
+    network?: string | string[];
     /**
      * Asset to accept
      * @default USDC on the specified network
@@ -261,7 +284,7 @@ interface X402MiddlewareConfig {
     };
     /**
      * x402 facilitator URL
-     * @default 'https://x402-facilitator.dexter.cash'
+     * @default 'https://x402.dexter.cash'
      */
     facilitatorUrl?: string;
     /**
@@ -300,6 +323,39 @@ interface X402MiddlewareConfig {
      * Custom function to get description from request
      */
     getDescription?: (req: Request) => string;
+    /**
+     * Enable sponsored-access recommendation delivery.
+     *
+     * When true, the middleware reads `extensions["sponsored-access"]` from the
+     * facilitator's SettlementResponse and injects the recommendations into the
+     * JSON response body as a `_x402_sponsored` field. This is the only way
+     * recommendations reach the agent's LLM (headers and receipt metadata are
+     * not visible to LLMs).
+     *
+     * Pass `true` for default injection, or an object with a custom `inject`
+     * function for full control over how recommendations appear in the response.
+     *
+     * @default false (off, no injection)
+     *
+     * @example Default injection
+     * ```typescript
+     * x402Middleware({ payTo: '...', amount: '0.05', sponsoredAccess: true })
+     * // Agent receives: { _x402_sponsored: [...], ...originalResponse }
+     * ```
+     *
+     * @example Custom injection
+     * ```typescript
+     * x402Middleware({
+     *   payTo: '...', amount: '0.05',
+     *   sponsoredAccess: {
+     *     inject: (body, recs) => ({ ...body, related_tools: recs })
+     *   }
+     * })
+     * ```
+     */
+    sponsoredAccess?: boolean | {
+        inject?: (body: unknown, recommendations: unknown[]) => unknown;
+    };
 }
 /**
  * Extended request with payment info
@@ -317,12 +373,6 @@ interface X402Request extends Request {
         network: string;
     };
 }
-/**
- * Create x402 middleware for Express
- *
- * @param config - Middleware configuration
- * @returns Express middleware function
- */
 declare function x402Middleware(config: X402MiddlewareConfig): RequestHandler;
 
 /**
@@ -422,7 +472,7 @@ interface X402AccessPassConfig {
     payTo: string;
     /** CAIP-2 network identifier @default 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' */
     network?: string;
-    /** x402 facilitator URL @default 'https://x402-facilitator.dexter.cash' */
+    /** x402 facilitator URL @default 'https://x402.dexter.cash' */
     facilitatorUrl?: string;
     /** Asset config @default USDC on specified network */
     asset?: {

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, c as PayToProvider, d as PaymentRequired } from '../types-C6ty4U6C.js';
-export { g as AccessPassClaims, A as AccessPassClientConfig, b as AccessPassInfo, a as AccessPassTier, B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, e as PayToContext, f as PayToProviderDefaults, h as SOLANA_MAINNET_NETWORK, i as USDC_BASE, U as USDC_MINT } from '../types-C6ty4U6C.js';
+import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, c as PayToProvider, d as PaymentRequired } from '../types-DYLi7SuF.js';
+export { g as AccessPassClaims, A as AccessPassClientConfig, b as AccessPassInfo, a as AccessPassTier, B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, e as PayToContext, f as PayToProviderDefaults, h as SOLANA_MAINNET_NETWORK, i as USDC_BASE, U as USDC_MINT } from '../types-DYLi7SuF.js';
 import { Request, RequestHandler } from 'express';
 
 /**
@@ -10,6 +10,7 @@ import { Request, RequestHandler } from 'express';
  * - /verify - Verify a payment signature before processing
  * - /settle - Submit the payment for execution
  *
+ * Includes retry with exponential backoff and request timeouts.
  * Works with any x402 v2 facilitator (Dexter or others).
  */
 
@@ -33,6 +34,19 @@ interface SupportedKind {
  */
 interface SupportedResponse {
     kinds: SupportedKind[];
+    extensions?: string[];
+    signers?: Record<string, string[]>;
+}
+/**
+ * Configuration for retry and timeout behavior
+ */
+interface FacilitatorClientConfig {
+    /** Request timeout in milliseconds @default 10000 */
+    timeoutMs?: number;
+    /** Maximum retry attempts for verify/settle @default 3 */
+    maxRetries?: number;
+    /** Base delay between retries in milliseconds (doubles each attempt) @default 500 */
+    retryBaseMs?: number;
 }
 /**
  * Client for communicating with an x402 v2 facilitator
@@ -42,40 +56,33 @@ declare class FacilitatorClient {
     private cachedSupported;
     private cacheTime;
     private readonly CACHE_TTL_MS;
-    constructor(facilitatorUrl?: string);
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    constructor(facilitatorUrl?: string, config?: FacilitatorClientConfig);
+    private fetchWithTimeout;
+    private fetchWithRetry;
     /**
-     * Get supported payment kinds from the facilitator
-     * Results are cached for 1 minute to reduce network calls
+     * Get supported payment kinds from the facilitator.
+     * Results are cached for 1 minute to reduce network calls.
      */
     getSupported(): Promise<SupportedResponse>;
     /**
      * Get the fee payer address for a specific network
-     *
-     * @param network - CAIP-2 network identifier
-     * @returns Fee payer address
      */
     getFeePayer(network: string): Promise<string>;
     /**
      * Get extra data for a network (feePayer, decimals, EIP-712 data, etc.)
-     *
-     * @param network - CAIP-2 network identifier
-     * @returns Extra data from /supported
      */
     getNetworkExtra(network: string): Promise<SupportedKind['extra']>;
     /**
-     * Verify a payment with the facilitator
-     *
-     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
-     * @param requirements - The payment requirements that were sent to the client
-     * @returns Verification response
+     * Verify a payment with the facilitator.
+     * Retries on 5xx and network errors with exponential backoff.
      */
     verifyPayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<VerifyResponse>;
     /**
-     * Settle a payment with the facilitator
-     *
-     * @param paymentSignatureHeader - Base64-encoded PAYMENT-SIGNATURE header value
-     * @param requirements - The payment requirements that were sent to the client
-     * @returns Settlement response with transaction signature on success
+     * Settle a payment with the facilitator.
+     * Retries on 5xx and network errors with exponential backoff.
      */
     settlePayment(paymentSignatureHeader: string, requirements: PaymentAccept): Promise<SettleResponse>;
 }
@@ -225,32 +232,48 @@ declare function createX402Server(config: X402ServerConfig): X402Server;
  */
 interface X402MiddlewareConfig {
     /**
-     * Address to receive payments, or a dynamic provider function.
+     * Address to receive payments, or a dynamic provider function, or
+     * a map of network-specific addresses for multi-chain support.
      *
      * - **Static address**: Pass a Solana pubkey or EVM address string.
-     * - **Stripe**: Use `stripePayTo(process.env.STRIPE_SECRET_KEY)` to generate
-     *   per-request deposit addresses. Payments land in your Stripe Dashboard.
+     * - **Stripe**: Use `stripePayTo(process.env.STRIPE_SECRET_KEY)` for Base.
+     * - **Multi-chain map**: Keys are CAIP-2 networks or globs (`eip155:*`, `*`).
      *
      * @example
      * ```typescript
-     * // Static address
+     * // Single address (works on one network)
      * payTo: '0xYourAddress...'
      *
-     * // Stripe machine payments
-     * payTo: stripePayTo(process.env.STRIPE_SECRET_KEY)
+     * // Stripe on Base, direct wallet on other chains
+     * payTo: { 'eip155:8453': stripePayTo(key), '*': '0xYourAddress...' }
+     *
+     * // Solana + EVM
+     * payTo: { 'solana:*': 'SolAddr', 'eip155:*': '0xEvmAddr' }
      * ```
      */
-    payTo: string | PayToProvider;
+    payTo: string | PayToProvider | Record<string, string | PayToProvider>;
     /**
      * Payment amount in USD (e.g., '0.01' for 1 cent)
      * Will be converted to atomic units automatically.
      */
     amount: string;
     /**
-     * CAIP-2 network identifier
+     * CAIP-2 network identifier(s).
+     * Pass an array to accept payments on multiple chains simultaneously.
+     * The client picks whichever chain it has a wallet for.
+     *
      * @default 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' (Solana mainnet)
+     *
+     * @example
+     * ```typescript
+     * // Single network
+     * network: 'eip155:8453'
+     *
+     * // Multiple EVM chains (same payTo address works for all)
+     * network: ['eip155:8453', 'eip155:137', 'eip155:42161']
+     * ```
      */
-    network?: string;
+    network?: string | string[];
     /**
      * Asset to accept
      * @default USDC on the specified network
@@ -261,7 +284,7 @@ interface X402MiddlewareConfig {
     };
     /**
      * x402 facilitator URL
-     * @default 'https://x402-facilitator.dexter.cash'
+     * @default 'https://x402.dexter.cash'
      */
     facilitatorUrl?: string;
     /**
@@ -300,6 +323,39 @@ interface X402MiddlewareConfig {
      * Custom function to get description from request
      */
     getDescription?: (req: Request) => string;
+    /**
+     * Enable sponsored-access recommendation delivery.
+     *
+     * When true, the middleware reads `extensions["sponsored-access"]` from the
+     * facilitator's SettlementResponse and injects the recommendations into the
+     * JSON response body as a `_x402_sponsored` field. This is the only way
+     * recommendations reach the agent's LLM (headers and receipt metadata are
+     * not visible to LLMs).
+     *
+     * Pass `true` for default injection, or an object with a custom `inject`
+     * function for full control over how recommendations appear in the response.
+     *
+     * @default false (off, no injection)
+     *
+     * @example Default injection
+     * ```typescript
+     * x402Middleware({ payTo: '...', amount: '0.05', sponsoredAccess: true })
+     * // Agent receives: { _x402_sponsored: [...], ...originalResponse }
+     * ```
+     *
+     * @example Custom injection
+     * ```typescript
+     * x402Middleware({
+     *   payTo: '...', amount: '0.05',
+     *   sponsoredAccess: {
+     *     inject: (body, recs) => ({ ...body, related_tools: recs })
+     *   }
+     * })
+     * ```
+     */
+    sponsoredAccess?: boolean | {
+        inject?: (body: unknown, recommendations: unknown[]) => unknown;
+    };
 }
 /**
  * Extended request with payment info
@@ -317,12 +373,6 @@ interface X402Request extends Request {
         network: string;
     };
 }
-/**
- * Create x402 middleware for Express
- *
- * @param config - Middleware configuration
- * @returns Express middleware function
- */
 declare function x402Middleware(config: X402MiddlewareConfig): RequestHandler;
 
 /**
@@ -422,7 +472,7 @@ interface X402AccessPassConfig {
     payTo: string;
     /** CAIP-2 network identifier @default 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' */
     network?: string;
-    /** x402 facilitator URL @default 'https://x402-facilitator.dexter.cash' */
+    /** x402 facilitator URL @default 'https://x402.dexter.cash' */
     facilitatorUrl?: string;
     /** Asset config @default USDC on specified network */
     asset?: {