@okxweb3/app-x402-core 0.1.2

package/dist/esm/mechanisms-sojpSwWW.d.mts

@@ -0,0 +1,763 @@
+interface FacilitatorConfig {
+    url?: string;
+    createAuthHeaders?: () => Promise<{
+        verify: Record<string, string>;
+        settle: Record<string, string>;
+        supported: Record<string, string>;
+    }>;
+}
+/**
+ * Interface for facilitator clients
+ * Can be implemented for HTTP-based or local facilitators
+ */
+interface FacilitatorClient {
+    /**
+     * Verify a payment with the facilitator
+     *
+     * @param paymentPayload - The payment to verify
+     * @param paymentRequirements - The requirements to verify against
+     * @returns Verification response
+     */
+    verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a payment with the facilitator
+     *
+     * @param paymentPayload - The payment to settle
+     * @param paymentRequirements - The requirements for settlement
+     * @returns Settlement response
+     */
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Get supported payment kinds and extensions from the facilitator
+     *
+     * @returns Supported payment kinds and extensions
+     */
+    getSupported(): Promise<SupportedResponse>;
+    /**
+     * Query on-chain settlement status by transaction hash.
+     * OKX extension: used for timeout recovery polling.
+     *
+     * @param txHash - The transaction hash to query
+     * @returns Settlement status response
+     */
+    getSettleStatus?(txHash: string): Promise<SettleStatusResponse>;
+}
+/**
+ * HTTP-based client for interacting with x402 facilitator services
+ * Handles HTTP communication with facilitator endpoints
+ */
+declare class HTTPFacilitatorClient implements FacilitatorClient {
+    readonly url: string;
+    private readonly _createAuthHeaders?;
+    /**
+     * Creates a new HTTPFacilitatorClient instance.
+     *
+     * @param config - Configuration options for the facilitator client
+     */
+    constructor(config?: FacilitatorConfig);
+    /**
+     * Verify a payment with the facilitator
+     *
+     * @param paymentPayload - The payment to verify
+     * @param paymentRequirements - The requirements to verify against
+     * @returns Verification response
+     */
+    verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a payment with the facilitator
+     *
+     * @param paymentPayload - The payment to settle
+     * @param paymentRequirements - The requirements for settlement
+     * @returns Settlement response
+     */
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Get supported payment kinds and extensions from the facilitator.
+     * Retries with exponential backoff on 429 rate limit errors.
+     *
+     * @returns Supported payment kinds and extensions
+     */
+    getSupported(): Promise<SupportedResponse>;
+    /**
+     * Query on-chain settlement status by transaction hash.
+     *
+     * @param txHash - The transaction hash to query
+     * @returns Settlement status response
+     */
+    getSettleStatus(txHash: string): Promise<SettleStatusResponse>;
+    /**
+     * Creates authentication headers for a specific path.
+     *
+     * @param path - The path to create authentication headers for (e.g., "verify", "settle", "supported")
+     * @returns An object containing the authentication headers for the specified path
+     */
+    createAuthHeaders(path: string): Promise<{
+        headers: Record<string, string>;
+    }>;
+    /**
+     * Helper to convert objects to JSON-safe format.
+     * Handles BigInt and other non-JSON types.
+     *
+     * @param obj - The object to convert
+     * @returns The JSON-safe representation of the object
+     */
+    private toJsonSafe;
+}
+
+/** Default poll interval for settle/status queries (1 second). */
+declare const DEFAULT_POLL_INTERVAL_MS = 1000;
+/** Default poll deadline for settle/status queries (5 seconds). */
+declare const DEFAULT_POLL_DEADLINE_MS = 5000;
+/** Result of polling `GET /settle/status`. */
+type PollResult = "success" | "failed" | "timeout";
+/**
+ * Configuration for a protected resource
+ * Only contains payment-specific configuration, not resource metadata
+ */
+interface ResourceConfig {
+    scheme: string;
+    payTo: string;
+    price: Price;
+    network: Network;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+}
+/**
+ * Lifecycle Hook Context Interfaces
+ */
+interface PaymentRequiredContext {
+    requirements: PaymentRequirements[];
+    resourceInfo: ResourceInfo;
+    error?: string;
+    paymentRequiredResponse: PaymentRequired;
+    transportContext?: unknown;
+}
+interface VerifyContext {
+    paymentPayload: PaymentPayload;
+    requirements: PaymentRequirements;
+}
+interface VerifyResultContext extends VerifyContext {
+    result: VerifyResponse;
+}
+interface VerifyFailureContext extends VerifyContext {
+    error: Error;
+}
+interface SettleContext {
+    paymentPayload: PaymentPayload;
+    requirements: PaymentRequirements;
+}
+interface SettleResultContext extends SettleContext {
+    result: SettleResponse;
+    transportContext?: unknown;
+}
+interface SettleFailureContext extends SettleContext {
+    error: Error;
+}
+/**
+ * Lifecycle Hook Type Definitions
+ */
+type BeforeVerifyHook = (context: VerifyContext) => Promise<void | {
+    abort: true;
+    reason: string;
+    message?: string;
+}>;
+type AfterVerifyHook = (context: VerifyResultContext) => Promise<void>;
+type OnVerifyFailureHook = (context: VerifyFailureContext) => Promise<void | {
+    recovered: true;
+    result: VerifyResponse;
+}>;
+type BeforeSettleHook = (context: SettleContext) => Promise<void | {
+    abort: true;
+    reason: string;
+    message?: string;
+}>;
+type AfterSettleHook = (context: SettleResultContext) => Promise<void>;
+type OnSettleFailureHook = (context: SettleFailureContext) => Promise<void | {
+    recovered: true;
+    result: SettleResponse;
+}>;
+/**
+ * Optional overrides for settlement parameters.
+ * Used to support partial settlement (e.g., upto scheme billing by actual usage).
+ *
+ * Note: Overriding the amount to a value different from the agreed-upon
+ * `PaymentRequirements.amount` is only valid in schemes that explicitly support
+ * partial settlement, such as the `upto` scheme. Using this with standard
+ * x402 schemes (e.g., `exact`) will likely cause settlement verification to fail.
+ */
+interface SettlementOverrides {
+    /**
+     * Amount to settle. Supports three formats:
+     *
+     * - **Raw atomic units** — e.g., `"1000"` settles exactly 1000 atomic units.
+     * - **Percent** — e.g., `"50%"` settles 50% of `PaymentRequirements.amount`.
+     *   Supports up to two decimal places (e.g., `"33.33%"`). The result is floored
+     *   to the nearest atomic unit.
+     * - **Dollar price** — e.g., `"$0.05"` converts a USD-denominated price to
+     *   atomic units. Uses `PaymentRequirements.extra.decimals` if set; otherwise
+     *   defaults to 6 (standard for USDC stablecoins). The result is rounded to
+     *   the nearest atomic unit.
+     *
+     * The resolved amount must be <= the authorized maximum in `PaymentRequirements`.
+     *
+     * Note: Setting this to an amount other than `PaymentRequirements.amount` is
+     * only valid in schemes that support partial settlement, such as `upto`.
+     */
+    amount?: string;
+}
+/**
+ * Core x402 protocol server for resource protection
+ * Transport-agnostic implementation of the x402 payment protocol
+ */
+declare class x402ResourceServer {
+    private facilitatorClients;
+    private registeredServerSchemes;
+    private supportedResponsesMap;
+    private facilitatorClientsMap;
+    private registeredExtensions;
+    private beforeVerifyHooks;
+    private afterVerifyHooks;
+    private onVerifyFailureHooks;
+    private beforeSettleHooks;
+    private afterSettleHooks;
+    private onSettleFailureHooks;
+    /**
+     * Creates a new x402ResourceServer instance.
+     *
+     * @param facilitatorClients - Optional facilitator client(s) for payment processing
+     */
+    constructor(facilitatorClients?: FacilitatorClient | FacilitatorClient[]);
+    /**
+     * Register a scheme/network server implementation.
+     *
+     * @param network - The network identifier
+     * @param server - The scheme/network server implementation
+     * @returns The x402ResourceServer instance for chaining
+     */
+    register(network: Network, server: SchemeNetworkServer): x402ResourceServer;
+    /**
+     * Check if a scheme is registered for a given network.
+     *
+     * @param network - The network identifier
+     * @param scheme - The payment scheme name
+     * @returns True if the scheme is registered for the network, false otherwise
+     */
+    hasRegisteredScheme(network: Network, scheme: string): boolean;
+    /**
+     * Registers a resource service extension that can enrich extension declarations.
+     *
+     * @param extension - The extension to register
+     * @returns The x402ResourceServer instance for chaining
+     */
+    registerExtension(extension: ResourceServerExtension): this;
+    /**
+     * Check if an extension is registered.
+     *
+     * @param key - The extension key
+     * @returns True if the extension is registered
+     */
+    hasExtension(key: string): boolean;
+    /**
+     * Get all registered extensions.
+     *
+     * @returns Array of registered extensions
+     */
+    getExtensions(): ResourceServerExtension[];
+    /**
+     * Enriches declared extensions using registered extension hooks.
+     *
+     * @param declaredExtensions - Extensions declared on the route
+     * @param transportContext - Transport-specific context (HTTP, A2A, MCP, etc.)
+     * @returns Enriched extensions map
+     */
+    enrichExtensions(declaredExtensions: Record<string, unknown>, transportContext: unknown): Record<string, unknown>;
+    /**
+     * Register a hook to execute before payment verification.
+     * Can abort verification by returning { abort: true, reason: string }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402ResourceServer instance for chaining
+     */
+    onBeforeVerify(hook: BeforeVerifyHook): x402ResourceServer;
+    /**
+     * Register a hook to execute after successful payment verification.
+     *
+     * @param hook - The hook function to register
+     * @returns The x402ResourceServer instance for chaining
+     */
+    onAfterVerify(hook: AfterVerifyHook): x402ResourceServer;
+    /**
+     * Register a hook to execute when payment verification fails.
+     * Can recover from failure by returning { recovered: true, result: VerifyResponse }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402ResourceServer instance for chaining
+     */
+    onVerifyFailure(hook: OnVerifyFailureHook): x402ResourceServer;
+    /**
+     * Register a hook to execute before payment settlement.
+     * Can abort settlement by returning { abort: true, reason: string }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402ResourceServer instance for chaining
+     */
+    onBeforeSettle(hook: BeforeSettleHook): x402ResourceServer;
+    /**
+     * Register a hook to execute after successful payment settlement.
+     *
+     * @param hook - The hook function to register
+     * @returns The x402ResourceServer instance for chaining
+     */
+    onAfterSettle(hook: AfterSettleHook): x402ResourceServer;
+    /**
+     * Register a hook to execute when payment settlement fails.
+     * Can recover from failure by returning { recovered: true, result: SettleResponse }
+     *
+     * @param hook - The hook function to register
+     * @returns The x402ResourceServer instance for chaining
+     */
+    onSettleFailure(hook: OnSettleFailureHook): x402ResourceServer;
+    /**
+     * Initialize by fetching supported kinds from all facilitators
+     * Creates mappings for supported responses and facilitator clients
+     * Earlier facilitators in the array get precedence
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get supported kind for a specific version, network, and scheme
+     *
+     * @param x402Version - The x402 version
+     * @param network - The network identifier
+     * @param scheme - The payment scheme
+     * @returns The supported kind or undefined if not found
+     */
+    getSupportedKind(x402Version: number, network: Network, scheme: string): SupportedKind | undefined;
+    /**
+     * Get facilitator extensions for a specific version, network, and scheme
+     *
+     * @param x402Version - The x402 version
+     * @param network - The network identifier
+     * @param scheme - The payment scheme
+     * @returns The facilitator extensions or empty array if not found
+     */
+    getFacilitatorExtensions(x402Version: number, network: Network, scheme: string): string[];
+    /**
+     * Build payment requirements for a protected resource
+     *
+     * @param resourceConfig - Configuration for the protected resource
+     * @returns Array of payment requirements
+     */
+    buildPaymentRequirements(resourceConfig: ResourceConfig): Promise<PaymentRequirements[]>;
+    /**
+     * Build payment requirements from multiple payment options
+     * This method handles resolving dynamic payTo/price functions and builds requirements for each option
+     *
+     * @param paymentOptions - Array of payment options to convert
+     * @param context - HTTP request context for resolving dynamic functions
+     * @returns Array of payment requirements (one per option)
+     */
+    buildPaymentRequirementsFromOptions<TContext = unknown>(paymentOptions: Array<{
+        scheme: string;
+        payTo: string | ((context: TContext) => string | Promise<string>);
+        price: Price | ((context: TContext) => Price | Promise<Price>);
+        network: Network;
+        maxTimeoutSeconds?: number;
+        extra?: Record<string, unknown>;
+    }>, context: TContext): Promise<PaymentRequirements[]>;
+    /**
+     * Create a payment required response
+     *
+     * @param requirements - Payment requirements
+     * @param resourceInfo - Resource information
+     * @param error - Error message
+     * @param extensions - Optional declared extensions (for per-key enrichment)
+     * @param transportContext - Optional transport-specific context (e.g., HTTP request, MCP tool context)
+     * @returns Payment required response object
+     */
+    createPaymentRequiredResponse(requirements: PaymentRequirements[], resourceInfo: ResourceInfo, error?: string, extensions?: Record<string, unknown>, transportContext?: unknown): Promise<PaymentRequired>;
+    /**
+     * Verify a payment against requirements
+     *
+     * @param paymentPayload - The payment payload to verify
+     * @param requirements - The payment requirements
+     * @returns Verification response
+     */
+    verifyPayment(paymentPayload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Settle a verified payment
+     *
+     * @param paymentPayload - The payment payload to settle
+     * @param requirements - The payment requirements
+     * @param declaredExtensions - Optional declared extensions (for per-key enrichment)
+     * @param transportContext - Optional transport-specific context (e.g., HTTP request/response, MCP tool context)
+     * @param settlementOverrides - Optional overrides for settlement parameters (e.g., partial settlement amount)
+     * @returns Settlement response
+     */
+    settlePayment(paymentPayload: PaymentPayload, requirements: PaymentRequirements, declaredExtensions?: Record<string, unknown>, transportContext?: unknown, settlementOverrides?: SettlementOverrides): Promise<SettleResponse>;
+    /**
+     * Find matching payment requirements for a payment
+     *
+     * @param availableRequirements - Array of available payment requirements
+     * @param paymentPayload - The payment payload
+     * @returns Matching payment requirements or undefined
+     */
+    findMatchingRequirements(availableRequirements: PaymentRequirements[], paymentPayload: PaymentPayload): PaymentRequirements | undefined;
+    /**
+     * Process a payment request
+     *
+     * @param paymentPayload - Optional payment payload if provided
+     * @param resourceConfig - Configuration for the protected resource
+     * @param resourceInfo - Information about the resource being accessed
+     * @param extensions - Optional extensions to include in the response
+     * @returns Processing result
+     */
+    processPaymentRequest(paymentPayload: PaymentPayload | null, resourceConfig: ResourceConfig, resourceInfo: ResourceInfo, extensions?: Record<string, unknown>): Promise<{
+        success: boolean;
+        requiresPayment?: PaymentRequired;
+        verificationResult?: VerifyResponse;
+        settlementResult?: SettleResponse;
+        error?: string;
+    }>;
+    /**
+     * Poll `GET /settle/status` until a terminal state is reached or deadline expires.
+     *
+     * Used when settle returns `status="timeout"` (exact + syncSettle=true).
+     * Mirrors Rust: `X402ResourceServer::poll_settle_status`.
+     *
+     * @param txHash - Transaction hash to query
+     * @param paymentPayload - The payment payload (used to find the correct facilitator client)
+     * @param requirements - The payment requirements (used to find the correct facilitator client)
+     * @param pollDeadlineMs - Max time to poll in ms (default 5000)
+     * @returns Poll result: "success", "failed", or "timeout"
+     */
+    pollSettleStatus(txHash: string, paymentPayload: PaymentPayload, requirements: PaymentRequirements, pollDeadlineMs?: number): Promise<PollResult>;
+    /**
+     * Get facilitator client for a specific version, network, and scheme
+     *
+     * @param x402Version - The x402 version
+     * @param network - The network identifier
+     * @param scheme - The payment scheme
+     * @returns The facilitator client or undefined if not found
+     */
+    private getFacilitatorClient;
+}
+
+/**
+ * Base interface for facilitator extensions.
+ * Extensions registered with x402Facilitator are stored by key and made
+ * available to mechanism implementations via FacilitatorContext.
+ *
+ * Specific extensions extend this with additional capabilities:
+ *
+ * @example
+ * interface Erc20GasSponsoringExtension extends FacilitatorExtension {
+ *   batchSigner: SmartWalletBatchSigner;
+ * }
+ */
+interface FacilitatorExtension {
+    key: string;
+}
+interface ResourceServerExtension {
+    key: string;
+    /**
+     * Enrich extension declaration with extension-specific data.
+     *
+     * @param declaration - Extension declaration from route config
+     * @param transportContext - Transport-specific context (HTTP, A2A, MCP, etc.)
+     * @returns Enriched extension declaration
+     */
+    enrichDeclaration?: (declaration: unknown, transportContext: unknown) => unknown;
+    /**
+     * Called when generating a 402 PaymentRequired response.
+     * Return extension data to add to extensions[key], or undefined to skip.
+     *
+     * @param declaration - Extension declaration from route config
+     * @param context - PaymentRequired context containing response, requirements, and optional transportContext
+     * @returns Extension data to add to response.extensions[key]
+     */
+    enrichPaymentRequiredResponse?: (declaration: unknown, context: PaymentRequiredContext) => Promise<unknown>;
+    /**
+     * Called after successful payment settlement.
+     * Return extension data to add to response.extensions[key], or undefined to skip.
+     *
+     * @param declaration - Extension declaration from route config
+     * @param context - Settlement result context containing payment payload, requirements, result and optional transportContext
+     * @returns Extension data to add to response.extensions[key]
+     */
+    enrichSettlementResponse?: (declaration: unknown, context: SettleResultContext) => Promise<unknown>;
+}
+
+type Network = `${string}:${string}`;
+type Money = string | number;
+type AssetAmount = {
+    asset: string;
+    amount: string;
+    extra?: Record<string, unknown>;
+};
+type Price = Money | AssetAmount;
+
+interface ResourceInfo {
+    url: string;
+    description?: string;
+    mimeType?: string;
+}
+type PaymentRequirements = {
+    scheme: string;
+    network: Network;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+};
+type PaymentRequired = {
+    x402Version: number;
+    error?: string;
+    resource: ResourceInfo;
+    accepts: PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+};
+type PaymentPayload = {
+    x402Version: number;
+    resource?: ResourceInfo;
+    accepted: PaymentRequirements;
+    payload: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+};
+
+type VerifyRequest = {
+    x402Version: number;
+    paymentPayload: PaymentPayload;
+    paymentRequirements: PaymentRequirements;
+};
+type VerifyResponse = {
+    isValid: boolean;
+    invalidReason?: string;
+    invalidMessage?: string;
+    payer?: string;
+    extensions?: Record<string, unknown>;
+};
+type SettleRequest = {
+    x402Version: number;
+    paymentPayload: PaymentPayload;
+    paymentRequirements: PaymentRequirements;
+};
+type SettleResponse = {
+    success: boolean;
+    /** OKX extension: pending (async, Seller trusts Facilitator), success (immediate), timeout (on-chain timed out) */
+    status?: "pending" | "success" | "timeout";
+    errorReason?: string;
+    errorMessage?: string;
+    payer?: string;
+    transaction: string;
+    network: Network;
+    /** Actual amount settled in atomic token units. Present for schemes like `upto` where settlement amount may differ from the authorized maximum. */
+    amount?: string;
+    extensions?: Record<string, unknown>;
+};
+type SupportedKind = {
+    x402Version: number;
+    scheme: string;
+    network: Network;
+    extra?: Record<string, unknown>;
+};
+type SupportedResponse = {
+    kinds: SupportedKind[];
+    extensions: string[];
+    signers: Record<string, string[]>;
+};
+/**
+ * Response from `GET /settle/status?txHash=...`.
+ * OKX extension: query on-chain settlement status by transaction hash.
+ */
+type SettleStatusResponse = {
+    success: boolean;
+    status?: "pending" | "success" | "failed";
+    errorReason?: string;
+    errorMessage?: string;
+    payer?: string;
+    transaction?: string;
+    network?: Network;
+};
+/**
+ * Error thrown when payment verification fails.
+ */
+declare class VerifyError extends Error {
+    readonly invalidReason?: string;
+    readonly invalidMessage?: string;
+    readonly payer?: string;
+    readonly statusCode: number;
+    /**
+     * Creates a VerifyError from a failed verification response.
+     *
+     * @param statusCode - HTTP status code from the facilitator
+     * @param response - The verify response containing error details
+     */
+    constructor(statusCode: number, response: VerifyResponse);
+}
+/**
+ * Error thrown when payment settlement fails.
+ */
+declare class SettleError extends Error {
+    readonly errorReason?: string;
+    readonly errorMessage?: string;
+    readonly payer?: string;
+    readonly transaction: string;
+    readonly network: Network;
+    readonly statusCode: number;
+    /**
+     * Creates a SettleError from a failed settlement response.
+     *
+     * @param statusCode - HTTP status code from the facilitator
+     * @param response - The settle response containing error details
+     */
+    constructor(statusCode: number, response: SettleResponse);
+}
+/**
+ * Error thrown when a facilitator returns malformed success payload data.
+ */
+declare class FacilitatorResponseError extends Error {
+    /**
+     * Creates a FacilitatorResponseError for malformed facilitator responses.
+     *
+     * @param message - The boundary error message
+     */
+    constructor(message: string);
+}
+/**
+ * Walks an error cause chain to find the first facilitator response error.
+ *
+ * @param error - The thrown value to inspect
+ * @returns The nested facilitator response error, if present
+ */
+declare function getFacilitatorResponseError(error: unknown): FacilitatorResponseError | null;
+
+/**
+ * Money parser function that converts a numeric amount to an AssetAmount
+ * Receives the amount as a decimal number (e.g., 1.50 for $1.50)
+ * Returns null to indicate "cannot handle this amount", causing fallback to next parser
+ * Always returns a Promise for consistency - use async/await
+ *
+ * @param amount - The decimal amount (e.g., 1.50)
+ * @param network - The network identifier for context
+ * @returns AssetAmount or null to try next parser
+ */
+type MoneyParser = (amount: number, network: Network) => Promise<AssetAmount | null>;
+/**
+ * Result of createPaymentPayload - the core payload fields.
+ * Contains the x402 version, scheme-specific payload data, and optional extension data.
+ * Schemes may return extensions (e.g., EIP-2612 gas sponsoring) that get merged
+ * with server-declared extensions in the final PaymentPayload.
+ *
+ * acceptedExtraOverrides: OKX extension — key-value pairs to merge into
+ * paymentPayload.accepted.extra before sending to the facilitator.
+ * Used by aggr_deferred to inject sessionCert into accepted.extra per OKX spec.
+ */
+type PaymentPayloadResult = Pick<PaymentPayload, "x402Version" | "payload"> & {
+    extensions?: Record<string, unknown>;
+    acceptedExtraOverrides?: Record<string, unknown>;
+};
+/**
+ * Context passed to scheme's createPaymentPayload for extensions awareness.
+ * Contains the server-declared extensions from PaymentRequired so the scheme
+ * can check which extensions are advertised and respond accordingly.
+ */
+interface PaymentPayloadContext {
+    extensions?: Record<string, unknown>;
+}
+interface SchemeNetworkClient {
+    readonly scheme: string;
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements, context?: PaymentPayloadContext): Promise<PaymentPayloadResult>;
+}
+/**
+ * Context passed to SchemeNetworkFacilitator.verify/settle, providing
+ * access to registered facilitator extensions. Mechanism implementations
+ * use this to retrieve extension-provided capabilities (e.g., a batch signer).
+ */
+interface FacilitatorContext {
+    getExtension<T extends FacilitatorExtension = FacilitatorExtension>(key: string): T | undefined;
+}
+interface SchemeNetworkFacilitator {
+    readonly scheme: string;
+    /**
+     * CAIP family pattern that this facilitator supports.
+     * Used to group signers by blockchain family in the supported response.
+     *
+     * @example
+     * // EVM facilitators
+     * readonly caipFamily = "eip155:*";
+     */
+    readonly caipFamily: string;
+    /**
+     * Get mechanism-specific extra data needed for the supported kinds endpoint.
+     * This method is called when building the facilitator's supported response.
+     *
+     * @param network - The network identifier for context
+     * @returns Extra data object or undefined if no extra data is needed
+     *
+     * @example
+     * // EVM schemes return undefined (no extra data needed)
+     * getExtra(network: Network): undefined {
+     *   return undefined;
+     * }
+     */
+    getExtra(network: Network): Record<string, unknown> | undefined;
+    /**
+     * Get signer addresses used by this facilitator for a given network.
+     * These are included in the supported response to help clients understand
+     * which addresses might sign/pay for transactions.
+     *
+     * Supports multiple addresses for load balancing, key rotation, and high availability.
+     *
+     * @param network - The network identifier
+     * @returns Array of signer addresses (wallet addresses, fee payer addresses, etc.)
+     *
+     * @example
+     * // EVM facilitator
+     * getSigners(network: string): string[] {
+     *   return [...this.signer.getAddresses()];
+     * }
+     */
+    getSigners(network: string): string[];
+    verify(payload: PaymentPayload, requirements: PaymentRequirements, context?: FacilitatorContext): Promise<VerifyResponse>;
+    settle(payload: PaymentPayload, requirements: PaymentRequirements, context?: FacilitatorContext): Promise<SettleResponse>;
+}
+interface SchemeNetworkServer {
+    readonly scheme: string;
+    /**
+     * Convert a user-friendly price to the scheme's specific amount and asset format
+     * Always returns a Promise for consistency
+     *
+     * @param price - User-friendly price (e.g., "$0.10", "0.10", { amount: "100000", asset: "USDC" })
+     * @param network - The network identifier for context
+     * @returns Promise that resolves to the converted amount, asset identifier, and any extra metadata
+     *
+     * @example
+     * // For XLayer with USDT0:
+     * await parsePrice("$0.10", "eip155:196") => { amount: "100000", asset: "0x779ded0c9e1022225f8e0630b35a9b54be713736" }
+     *
+     * // For custom schemes:
+     * await parsePrice("10 points", "custom:network") => { amount: "10", asset: "points" }
+     */
+    parsePrice(price: Price, network: Network): Promise<AssetAmount>;
+    /**
+     * Build payment requirements for this scheme/network combination
+     *
+     * @param paymentRequirements - Base payment requirements with amount/asset already set
+     * @param supportedKind - The supported kind from facilitator's /supported endpoint
+     * @param supportedKind.x402Version - The x402 version
+     * @param supportedKind.scheme - The payment scheme
+     * @param supportedKind.network - The network identifier
+     * @param supportedKind.extra - Optional extra metadata
+     * @param facilitatorExtensions - Extensions supported by the facilitator
+     * @returns Enhanced payment requirements ready to be sent to clients
+     */
+    enhancePaymentRequirements(paymentRequirements: PaymentRequirements, supportedKind: {
+        x402Version: number;
+        scheme: string;
+        network: Network;
+        extra?: Record<string, unknown>;
+    }, facilitatorExtensions: string[]): Promise<PaymentRequirements>;
+}
+
+export { type AssetAmount as A, VerifyError as B, type VerifyRequest as C, DEFAULT_POLL_DEADLINE_MS as D, type FacilitatorExtension as F, HTTPFacilitatorClient as H, type Money as M, type Network as N, type PaymentPayload as P, type ResourceConfig as R, type SettleResponse as S, type VerifyResponse as V, type PaymentRequirements as a, type SchemeNetworkFacilitator as b, type PaymentRequired as c, type FacilitatorClient as d, type FacilitatorConfig as e, FacilitatorResponseError as f, getFacilitatorResponseError as g, type SupportedResponse as h, type SettleStatusResponse as i, type SchemeNetworkClient as j, DEFAULT_POLL_INTERVAL_MS as k, type PollResult as l, type SettleResultContext as m, type SettlementOverrides as n, type Price as o, type FacilitatorContext as p, type MoneyParser as q, type PaymentPayloadContext as r, type PaymentPayloadResult as s, type PaymentRequiredContext as t, type ResourceInfo as u, type ResourceServerExtension as v, type SchemeNetworkServer as w, x402ResourceServer as x, SettleError as y, type SettleRequest as z };