@x402/mcp 2.3.0-alpha

package/dist/cjs/index.d.ts

@@ -0,0 +1,971 @@
+import { PaymentRequired, PaymentPayload, SettleResponse, PaymentRequirements, Network, Price, SchemeNetworkClient } from '@x402/core/types';
+export { Network, PaymentPayload, PaymentRequired, PaymentRequirements, SchemeNetworkClient, SchemeNetworkServer, SettleResponse } from '@x402/core/types';
+import { x402Client, x402ClientConfig } from '@x402/core/client';
+export { PaymentPolicy, SelectPaymentRequirements, x402Client, x402ClientConfig } from '@x402/core/client';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { x402ResourceServer } from '@x402/core/server';
+export { x402ResourceServer } from '@x402/core/server';
+
+/**
+ * MCP JSON-RPC error code for payment required (x402)
+ */
+declare const MCP_PAYMENT_REQUIRED_CODE = 402;
+/**
+ * MCP _meta key for payment payload (client → server)
+ */
+declare const MCP_PAYMENT_META_KEY = "x402/payment";
+/**
+ * MCP _meta key for payment response (server → client)
+ */
+declare const MCP_PAYMENT_RESPONSE_META_KEY = "x402/payment-response";
+/**
+ * Dynamic function to resolve payTo address based on tool call context
+ */
+type DynamicPayTo = (context: MCPToolContext) => string | Promise<string>;
+/**
+ * Dynamic function to resolve price based on tool call context
+ */
+type DynamicPrice = (context: MCPToolContext) => Price | Promise<Price>;
+/**
+ * Context provided to dynamic functions and hooks during tool execution
+ */
+interface MCPToolContext {
+    /** The name of the tool being called */
+    toolName: string;
+    /** The arguments passed to the tool */
+    arguments: Record<string, unknown>;
+    /** Optional metadata from the request */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Payment configuration for a paid MCP tool
+ */
+interface MCPToolPaymentConfig {
+    /** Payment scheme identifier (e.g., "exact") */
+    scheme: string;
+    /** Blockchain network identifier in CAIP-2 format (e.g., "eip155:84532") */
+    network: Network;
+    /** Price for the tool call (e.g., "$0.10", "1000000") */
+    price: Price | DynamicPrice;
+    /** Recipient wallet address or dynamic resolver */
+    payTo: string | DynamicPayTo;
+    /** Maximum time allowed for payment completion in seconds */
+    maxTimeoutSeconds?: number;
+    /** Scheme-specific additional information */
+    extra?: Record<string, unknown>;
+    /** Resource metadata for the tool */
+    resource?: {
+        /** Custom URL for the resource (defaults to mcp://tool/{toolName}) */
+        url?: string;
+        /** Human-readable description of the tool */
+        description?: string;
+        /** MIME type of the tool response */
+        mimeType?: string;
+    };
+}
+/**
+ * Result of processing an MCP tool request for payment
+ */
+type MCPPaymentProcessResult = {
+    type: "no-payment-required";
+} | {
+    type: "payment-verified";
+    paymentPayload: PaymentPayload;
+    paymentRequirements: PaymentRequirements;
+} | {
+    type: "payment-error";
+    error: MCPPaymentError;
+};
+/**
+ * MCP payment error structure for JSON-RPC error responses
+ */
+interface MCPPaymentError {
+    /** JSON-RPC error code (402 for payment required) */
+    code: number;
+    /** Human-readable error message */
+    message: string;
+    /** PaymentRequired data for 402 errors */
+    data?: PaymentRequired;
+}
+/**
+ * Context provided to onPaymentRequired hooks
+ */
+interface PaymentRequiredContext {
+    /** The tool name that returned 402 */
+    toolName: string;
+    /** The arguments that were passed to the tool */
+    arguments: Record<string, unknown>;
+    /** The payment requirements from the server */
+    paymentRequired: PaymentRequired;
+}
+/**
+ * Result from onPaymentRequired hook
+ */
+interface PaymentRequiredHookResult {
+    /** Custom payment payload to use instead of auto-generated */
+    payment?: PaymentPayload;
+    /** Skip payment and abort the call */
+    abort?: boolean;
+}
+/**
+ * Hook called when a 402 response is received, before payment processing.
+ * Return payment to use that instead of auto-generating, abort: true to stop.
+ * Return void/undefined to proceed with normal payment flow.
+ */
+type PaymentRequiredHook = (context: PaymentRequiredContext) => Promise<PaymentRequiredHookResult | void> | PaymentRequiredHookResult | void;
+/**
+ * Options for x402MCPClient
+ */
+interface x402MCPClientOptions {
+    /**
+     * Whether to automatically retry tool calls with payment on 402 errors.
+     * When true (default), the client will automatically create and submit
+     * payment when a 402 error is received.
+     * When false, the client will throw the 402 error for manual handling.
+     *
+     * @default true
+     */
+    autoPayment?: boolean;
+    /**
+     * Hook called when a payment is requested by the server (402 response).
+     * Return true to proceed with payment, false to abort.
+     * Only called when autoPayment is true.
+     *
+     * This can be used to implement human-in-the-loop approval.
+     */
+    onPaymentRequested?: (context: PaymentRequestedContext) => Promise<boolean> | boolean;
+}
+/**
+ * Context provided to payment requested hook
+ */
+interface PaymentRequestedContext {
+    /** The tool being called */
+    toolName: string;
+    /** The arguments passed to the tool */
+    arguments: Record<string, unknown>;
+    /** The payment requirements from the server */
+    paymentRequired: PaymentRequired;
+}
+/**
+ * Context provided to server-side hooks during tool execution
+ */
+interface ServerHookContext {
+    /** The name of the tool being called */
+    toolName: string;
+    /** The arguments passed to the tool */
+    arguments: Record<string, unknown>;
+    /** The resolved payment requirements */
+    paymentRequirements: PaymentRequirements;
+    /** The payment payload from the client */
+    paymentPayload: PaymentPayload;
+}
+/**
+ * Hook called before tool execution (after payment verification)
+ * Return false to abort execution and return a 402 error
+ */
+type BeforeExecutionHook = (context: ServerHookContext) => Promise<boolean | void> | boolean | void;
+/**
+ * Context for after execution hook including the result
+ */
+interface AfterExecutionContext extends ServerHookContext {
+    /** The tool execution result */
+    result: {
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        isError?: boolean;
+    };
+}
+/**
+ * Hook called after tool execution (before settlement)
+ */
+type AfterExecutionHook = (context: AfterExecutionContext) => Promise<void> | void;
+/**
+ * Context for settlement hooks
+ */
+interface SettlementContext extends ServerHookContext {
+    /** The settlement result */
+    settlement: SettleResponse;
+}
+/**
+ * Hook called after successful settlement
+ */
+type AfterSettlementHook = (context: SettlementContext) => Promise<void> | void;
+/**
+ * Tool content item type
+ */
+interface ToolContentItem {
+    [key: string]: unknown;
+    type: string;
+    text?: string;
+}
+/**
+ * Result of a tool call that includes payment response metadata
+ */
+interface MCPToolResultWithPayment {
+    /** Standard MCP tool result content */
+    content: ToolContentItem[];
+    /** Whether the tool execution resulted in an error */
+    isError?: boolean;
+    /** Payment response metadata (settlement info) */
+    paymentResponse?: SettleResponse;
+}
+/**
+ * MCP metadata with payment
+ */
+interface MCPMetaWithPayment {
+    [key: string]: unknown;
+    [MCP_PAYMENT_META_KEY]?: PaymentPayload;
+}
+/**
+ * MCP request params with optional _meta field for payment
+ */
+interface MCPRequestParamsWithMeta {
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    arguments?: Record<string, unknown>;
+    /** Metadata including potential payment payload */
+    _meta?: MCPMetaWithPayment;
+}
+/**
+ * MCP metadata with payment response
+ */
+interface MCPMetaWithPaymentResponse {
+    [key: string]: unknown;
+    [MCP_PAYMENT_RESPONSE_META_KEY]?: SettleResponse;
+}
+/**
+ * MCP result with optional _meta field for payment response
+ */
+interface MCPResultWithMeta {
+    /** Tool result content */
+    content?: ToolContentItem[];
+    /** Whether the result is an error */
+    isError?: boolean;
+    /** Metadata including potential payment response */
+    _meta?: MCPMetaWithPaymentResponse;
+}
+/**
+ * MCP JSON-RPC error with payment required data
+ */
+interface MCPPaymentRequiredError {
+    /** JSON-RPC error code (402) */
+    code: typeof MCP_PAYMENT_REQUIRED_CODE;
+    /** Error message */
+    message: string;
+    /** PaymentRequired data */
+    data: PaymentRequired;
+}
+/**
+ * Type guard to check if an error is a payment required error
+ *
+ * @param error - The error to check
+ * @returns True if the error is a payment required error
+ */
+declare function isPaymentRequiredError(error: unknown): error is MCPPaymentRequiredError;
+
+/**
+ * MCP content item - using a flexible type that matches the MCP SDK's content format.
+ * The MCP SDK returns content items with a `type` discriminator and type-specific fields.
+ * We use this type to preserve the original response structure from the SDK.
+ */
+type MCPContentItem = {
+    [key: string]: unknown;
+    type: string;
+};
+/**
+ * Hook called before payment is created
+ */
+type BeforePaymentHook = (context: PaymentRequestedContext) => Promise<void> | void;
+/**
+ * Hook called after payment is submitted
+ */
+type AfterPaymentHook = (context: {
+    toolName: string;
+    paymentPayload: PaymentPayload;
+    result: MCPResultWithMeta;
+    settleResponse: SettleResponse | null;
+}) => Promise<void> | void;
+/**
+ * Result of a tool call with payment metadata.
+ * Content is forwarded directly from the MCP SDK to preserve the original response structure.
+ */
+interface x402MCPToolCallResult {
+    /** The tool result content, forwarded directly from MCP SDK */
+    content: MCPContentItem[];
+    /** Whether the tool returned an error */
+    isError?: boolean;
+    /** Payment settlement response if payment was made */
+    paymentResponse?: SettleResponse;
+    /** Whether payment was required and submitted */
+    paymentMade: boolean;
+}
+/**
+ * x402-enabled MCP client that handles payment for tool calls.
+ *
+ * Wraps an MCP client to automatically detect 402 (payment required) errors
+ * from tool calls, create payment payloads, and retry with payment attached.
+ *
+ * PROTOCOL COMPLIANCE:
+ * This wrapper is a COMPLETE, TRANSPARENT passthrough exposing all 19 public methods
+ * from the MCP SDK Client class. It's suitable for any MCP use case including:
+ * - Chatbots and conversational agents
+ * - IDE integrations (like Cursor, VSCode)
+ * - Autonomous agents
+ * - Custom MCP applications
+ *
+ * Only callTool() is enhanced with payment handling. All other methods are direct
+ * passthroughs ensuring full MCP protocol compatibility.
+ *
+ * STABILITY:
+ * Depends on formal MCP specification (JSON-RPC 2.0 based) with semantic versioning.
+ * Proven stable across SDK versions: 1.9.0 → 1.12.1 → 1.15.1
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+ * import { x402MCPClient } from "@x402/mcp";
+ * import { x402Client } from "@x402/core/client";
+ * import { ExactEvmScheme } from "@x402/evm/exact/client";
+ *
+ * const paymentClient = new x402Client()
+ *   .register("eip155:84532", new ExactEvmScheme(account));
+ *
+ * const mcpClient = new Client({ name: "my-agent", version: "1.0.0" }, {...});
+ * const x402Mcp = new x402MCPClient(mcpClient, paymentClient, {
+ *   autoPayment: true,
+ *   onPaymentRequested: async ({ paymentRequired }) => {
+ *     return confirm(`Pay ${paymentRequired.accepts[0].amount}?`);
+ *   },
+ * });
+ *
+ * await x402Mcp.connect(transport);
+ *
+ * // Full MCP protocol access - all 19 methods available
+ * const tools = await x402Mcp.listTools();
+ * const resource = await x402Mcp.readResource({ uri: "file://..." });
+ * const prompt = await x402Mcp.getPrompt({ name: "code-review" });
+ * const result = await x402Mcp.callTool("financial_analysis", { ticker: "AAPL" });
+ * ```
+ */
+declare class x402MCPClient {
+    private readonly mcpClient;
+    private readonly _paymentClient;
+    private readonly options;
+    private readonly paymentRequiredHooks;
+    private readonly beforePaymentHooks;
+    private readonly afterPaymentHooks;
+    /**
+     * Creates a new x402MCPClient instance.
+     *
+     * @param mcpClient - The underlying MCP client instance
+     * @param paymentClient - The x402 client for creating payment payloads
+     * @param options - Configuration options
+     */
+    constructor(mcpClient: Client, paymentClient: x402Client, options?: x402MCPClientOptions);
+    /**
+     * Get the underlying MCP client instance.
+     *
+     * @returns The MCP client instance
+     */
+    get client(): Client;
+    /**
+     * Get the underlying x402 payment client instance.
+     *
+     * @returns The x402 client instance
+     */
+    get paymentClient(): x402Client;
+    /**
+     * Connect to an MCP server transport.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param transport - The transport to connect to
+     * @returns Promise that resolves when connected
+     */
+    connect(transport: Parameters<Client["connect"]>[0]): Promise<void>;
+    /**
+     * Close the MCP connection.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Promise that resolves when closed
+     */
+    close(): Promise<void>;
+    /**
+     * List available tools from the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Promise resolving to the list of tools
+     */
+    listTools(): ReturnType<Client["listTools"]>;
+    /**
+     * List available resources from the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Promise resolving to the list of resources
+     */
+    listResources(): ReturnType<Client["listResources"]>;
+    /**
+     * List available prompts from the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Promise resolving to the list of prompts
+     */
+    listPrompts(): ReturnType<Client["listPrompts"]>;
+    /**
+     * Get a specific prompt from the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for getPrompt method
+     * @returns Promise resolving to the prompt
+     */
+    getPrompt(...args: Parameters<Client["getPrompt"]>): ReturnType<Client["getPrompt"]>;
+    /**
+     * Read a resource from the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for readResource method
+     * @returns Promise resolving to the resource content
+     */
+    readResource(...args: Parameters<Client["readResource"]>): ReturnType<Client["readResource"]>;
+    /**
+     * List resource templates from the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for listResourceTemplates method
+     * @returns Promise resolving to the list of resource templates
+     */
+    listResourceTemplates(...args: Parameters<Client["listResourceTemplates"]>): ReturnType<Client["listResourceTemplates"]>;
+    /**
+     * Subscribe to resource updates.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for subscribeResource method
+     * @returns Promise resolving when subscribed
+     */
+    subscribeResource(...args: Parameters<Client["subscribeResource"]>): ReturnType<Client["subscribeResource"]>;
+    /**
+     * Unsubscribe from resource updates.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for unsubscribeResource method
+     * @returns Promise resolving when unsubscribed
+     */
+    unsubscribeResource(...args: Parameters<Client["unsubscribeResource"]>): ReturnType<Client["unsubscribeResource"]>;
+    /**
+     * Ping the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for ping method
+     * @returns Promise resolving to ping response
+     */
+    ping(...args: Parameters<Client["ping"]>): ReturnType<Client["ping"]>;
+    /**
+     * Request completion suggestions.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for complete method
+     * @returns Promise resolving to completion suggestions
+     */
+    complete(...args: Parameters<Client["complete"]>): ReturnType<Client["complete"]>;
+    /**
+     * Set the logging level on the server.
+     * Passthrough to the underlying MCP client.
+     *
+     * @param args - Arguments for setLoggingLevel method
+     * @returns Promise resolving when level is set
+     */
+    setLoggingLevel(...args: Parameters<Client["setLoggingLevel"]>): ReturnType<Client["setLoggingLevel"]>;
+    /**
+     * Get server capabilities after initialization.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Server capabilities or undefined if not initialized
+     */
+    getServerCapabilities(): ReturnType<Client["getServerCapabilities"]>;
+    /**
+     * Get server version information after initialization.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Server version info or undefined if not initialized
+     */
+    getServerVersion(): ReturnType<Client["getServerVersion"]>;
+    /**
+     * Get server instructions after initialization.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Server instructions or undefined if not initialized
+     */
+    getInstructions(): ReturnType<Client["getInstructions"]>;
+    /**
+     * Send notification that roots list has changed.
+     * Passthrough to the underlying MCP client.
+     *
+     * @returns Promise resolving when notification is sent
+     */
+    sendRootsListChanged(): ReturnType<Client["sendRootsListChanged"]>;
+    /**
+     * Register a hook to run when a 402 payment required is received.
+     * Hooks run in order; first to return a result wins.
+     *
+     * This can be used to:
+     * - Provide pre-existing payment payloads (implementation-specific, not part of x402 spec)
+     * - Abort the payment flow for certain tools
+     * - Log or track payment required events
+     *
+     * Note: Payment caching is an implementation pattern and not defined in the x402 MCP
+     * transport specification. Implementations that cache payments should ensure cached
+     * payloads are still valid (not expired, correct nonce, etc.).
+     *
+     * @param hook - Hook function
+     * @returns This instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Example: Custom payment handling (implementation-specific)
+     * client.onPaymentRequired(async ({ toolName, paymentRequired }) => {
+     *   // Custom logic to provide a payment or abort
+     *   if (shouldAbort(toolName)) {
+     *     return { abort: true };
+     *   }
+     *   // Return undefined to proceed with normal payment flow
+     * });
+     * ```
+     */
+    onPaymentRequired(hook: PaymentRequiredHook): this;
+    /**
+     * Register a hook to run before payment is created.
+     *
+     * @param hook - Hook function
+     * @returns This instance for chaining
+     */
+    onBeforePayment(hook: BeforePaymentHook): this;
+    /**
+     * Register a hook to run after payment is submitted.
+     *
+     * @param hook - Hook function
+     * @returns This instance for chaining
+     */
+    onAfterPayment(hook: AfterPaymentHook): this;
+    /**
+     * Calls a tool, automatically handling 402 payment required errors.
+     *
+     * If the tool returns a 402 error and autoPayment is enabled, this method
+     * will automatically create a payment payload and retry the tool call.
+     *
+     * @param name - The name of the tool to call
+     * @param args - Arguments to pass to the tool
+     * @param options - Optional MCP request options (timeout, signal, etc.)
+     * @param options.timeout - Request timeout in milliseconds (default: 60000)
+     * @param options.signal - AbortSignal for cancellation
+     * @param options.resetTimeoutOnProgress - If true, progress notifications reset the timeout
+     * @returns The tool result with payment metadata
+     * @throws Error if payment is required but autoPayment is disabled and no payment provided
+     * @throws Error if payment approval is denied
+     * @throws Error if payment creation fails
+     */
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+        resetTimeoutOnProgress?: boolean;
+    }): Promise<x402MCPToolCallResult>;
+    /**
+     * Calls a tool with an explicit payment payload.
+     *
+     * Use this method when you want to provide payment upfront or when
+     * implementing custom payment handling.
+     *
+     * @param name - The name of the tool to call
+     * @param args - Arguments to pass to the tool
+     * @param paymentPayload - The payment payload to include
+     * @param options - Optional MCP request options (timeout, signal, etc.)
+     * @param options.timeout - Request timeout in milliseconds (default: 60000)
+     * @param options.signal - AbortSignal for cancellation
+     * @param options.resetTimeoutOnProgress - If true, progress notifications reset the timeout
+     * @returns The tool result with payment metadata
+     */
+    callToolWithPayment(name: string, args: Record<string, unknown>, paymentPayload: PaymentPayload, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+        resetTimeoutOnProgress?: boolean;
+    }): Promise<x402MCPToolCallResult>;
+    /**
+     * Probes a tool to discover its payment requirements.
+     *
+     * **WARNING: Side Effects** - This method actually calls the tool to trigger a 402 response.
+     * If the tool is free (no payment required), it will execute and return null.
+     * Use with caution on tools that have side effects or are expensive to run.
+     *
+     * Useful for displaying pricing information to users before calling paid tools.
+     *
+     * @param name - The name of the tool to probe
+     * @param args - Arguments that may affect pricing (for dynamic pricing scenarios)
+     * @returns The payment requirements if the tool requires payment, null if the tool is free
+     *
+     * @example
+     * ```typescript
+     * // Check if a tool requires payment before calling
+     * const requirements = await client.getToolPaymentRequirements("expensive_analysis");
+     *
+     * if (requirements) {
+     *   const price = requirements.accepts[0];
+     *   console.log(`This tool costs ${price.amount} on ${price.network}`);
+     *   // Optionally show user and get confirmation before calling
+     * } else {
+     *   console.log("This tool is free");
+     *   // Note: the tool has already executed!
+     * }
+     * ```
+     */
+    getToolPaymentRequirements(name: string, args?: Record<string, unknown>): Promise<PaymentRequired | null>;
+    /**
+     * Extracts PaymentRequired from a tool result (structured 402 response).
+     *
+     * Per MCP transport spec, supports:
+     * 1. structuredContent with direct PaymentRequired object (optional, preferred)
+     * 2. content[0].text with JSON-encoded PaymentRequired object (required)
+     *
+     * @param result - The tool call result
+     * @returns PaymentRequired if this is a 402 response, null otherwise
+     */
+    private extractPaymentRequiredFromResult;
+    /**
+     * Extracts PaymentRequired from an object.
+     * Expects direct PaymentRequired format (per MCP transport spec).
+     *
+     * @param obj - The object to extract from
+     * @returns PaymentRequired if found, null otherwise
+     */
+    private extractPaymentRequiredFromObject;
+}
+/**
+ * Configuration for createx402MCPClient factory
+ */
+interface x402MCPClientConfig {
+    /** MCP client name */
+    name: string;
+    /** MCP client version */
+    version: string;
+    /**
+     * Payment scheme registrations.
+     * Each registration maps a network to its scheme client implementation.
+     */
+    schemes: Array<{
+        network: Network;
+        client: SchemeNetworkClient;
+        x402Version?: number;
+    }>;
+    /**
+     * Whether to automatically retry tool calls with payment on 402 errors.
+     *
+     * @default true
+     */
+    autoPayment?: boolean;
+    /**
+     * Hook called when a payment is requested.
+     * Return true to proceed with payment, false to abort.
+     */
+    onPaymentRequested?: (context: PaymentRequestedContext) => Promise<boolean> | boolean;
+    /**
+     * Additional MCP client options
+     */
+    mcpClientOptions?: Record<string, unknown>;
+}
+/**
+ * Wraps an existing MCP client with x402 payment handling.
+ *
+ * Use this when you already have an MCP client instance and want to add
+ * payment capabilities. For a simpler setup, use createx402MCPClient instead.
+ *
+ * @param mcpClient - The MCP client to wrap
+ * @param paymentClient - The x402 client for payment handling
+ * @param options - Configuration options
+ * @returns An x402MCPClient instance
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+ * import { wrapMCPClientWithPayment } from "@x402/mcp";
+ * import { x402Client } from "@x402/core/client";
+ * import { ExactEvmScheme } from "@x402/evm/exact/client";
+ *
+ * const mcpClient = new Client({ name: "my-agent", version: "1.0.0" });
+ * const paymentClient = new x402Client()
+ *   .register("eip155:84532", new ExactEvmScheme(account));
+ *
+ * const x402Mcp = wrapMCPClientWithPayment(mcpClient, paymentClient, {
+ *   autoPayment: true,
+ * });
+ *
+ * await x402Mcp.connect(transport);
+ * const result = await x402Mcp.callTool("paid_tool", { arg: "value" });
+ * ```
+ */
+declare function wrapMCPClientWithPayment(mcpClient: Client, paymentClient: x402Client, options?: x402MCPClientOptions): x402MCPClient;
+/**
+ * Wraps an existing MCP client with x402 payment handling using a config object.
+ *
+ * Similar to wrapMCPClientWithPayment but uses a configuration object for
+ * setting up the payment client, similar to the axios pattern.
+ *
+ * @param mcpClient - The MCP client to wrap
+ * @param config - Payment client configuration
+ * @param options - x402 MCP client options
+ * @returns An x402MCPClient instance
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+ * import { wrapMCPClientWithPaymentFromConfig } from "@x402/mcp";
+ * import { ExactEvmScheme } from "@x402/evm/exact/client";
+ *
+ * const mcpClient = new Client({ name: "my-agent", version: "1.0.0" });
+ *
+ * const x402Mcp = wrapMCPClientWithPaymentFromConfig(mcpClient, {
+ *   schemes: [
+ *     { network: "eip155:84532", client: new ExactEvmScheme(account) },
+ *   ],
+ * });
+ *
+ * await x402Mcp.connect(transport);
+ * ```
+ */
+declare function wrapMCPClientWithPaymentFromConfig(mcpClient: Client, config: x402ClientConfig, options?: x402MCPClientOptions): x402MCPClient;
+/**
+ * Creates a fully configured x402 MCP client with sensible defaults.
+ *
+ * This factory function provides the simplest way to create an x402-enabled MCP client.
+ * It handles creation of both the underlying MCP Client and x402Client, making it
+ * easy to get started with paid tool calls.
+ *
+ * @param config - Client configuration options
+ * @returns A configured x402MCPClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createx402MCPClient } from "@x402/mcp";
+ * import { ExactEvmScheme } from "@x402/evm/exact/client";
+ * import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+ *
+ * const client = createx402MCPClient({
+ *   name: "my-agent",
+ *   version: "1.0.0",
+ *   schemes: [
+ *     { network: "eip155:84532", client: new ExactEvmScheme(account) },
+ *   ],
+ *   autoPayment: true,
+ *   onPaymentRequested: async ({ paymentRequired }) => {
+ *     console.log(`Payment required: ${paymentRequired.accepts[0].amount}`);
+ *     return true; // Auto-approve
+ *   },
+ * });
+ *
+ * // Connect to server
+ * const transport = new SSEClientTransport(new URL("http://localhost:4022/sse"));
+ * await client.connect(transport);
+ *
+ * // List available tools
+ * const { tools } = await client.listTools();
+ *
+ * // Call a paid tool (payment handled automatically)
+ * const result = await client.callTool("get_weather", { city: "NYC" });
+ * ```
+ */
+declare function createx402MCPClient(config: x402MCPClientConfig): x402MCPClient;
+
+/**
+ * Payment wrapper for MCP tool handlers
+ *
+ * This module provides a functional API for adding x402 payment to MCP tool handlers.
+ * Use createPaymentWrapper to wrap tool handlers with payment verification and settlement.
+ */
+
+/**
+ * Configuration for payment wrapper.
+ */
+interface PaymentWrapperConfig {
+    /**
+     * Payment requirements that must be satisfied to call the tool.
+     * Typically a single entry, but can support multiple payment options.
+     *
+     * Each requirement specifies:
+     * - scheme: Payment scheme identifier (e.g., "exact")
+     * - network: Blockchain network in CAIP-2 format (e.g., "eip155:84532")
+     * - amount: Payment amount in token's smallest unit
+     * - asset: Token contract address
+     * - payTo: Recipient wallet address
+     * - maxTimeoutSeconds: Payment timeout (optional)
+     * - extra: Scheme-specific data (optional)
+     */
+    accepts: PaymentRequirements[];
+    /** Resource metadata for the tool */
+    resource?: {
+        /** Custom URL for the resource (defaults to mcp://tool/{toolName}) */
+        url?: string;
+        /** Human-readable description of the tool */
+        description?: string;
+        /** MIME type of the tool response */
+        mimeType?: string;
+    };
+    /** Hooks for payment lifecycle events */
+    hooks?: {
+        /** Called after payment verification, before tool execution. Return false to abort. */
+        onBeforeExecution?: BeforeExecutionHook;
+        /** Called after tool execution, before settlement */
+        onAfterExecution?: AfterExecutionHook;
+        /** Called after successful settlement */
+        onAfterSettlement?: AfterSettlementHook;
+    };
+}
+/**
+ * Result type for wrapped tool handlers.
+ * Matches the MCP SDK's expected tool result format with optional _meta.
+ */
+interface WrappedToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+    structuredContent?: Record<string, unknown>;
+}
+/**
+ * Tool result type without payment metadata
+ */
+interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Handler function type for tools to be wrapped with payment.
+ */
+type PaymentWrappedHandler<TArgs = Record<string, unknown>> = (args: TArgs, context: MCPToolContext) => Promise<ToolResult> | ToolResult;
+/**
+ * MCP SDK compatible tool callback type.
+ * This type matches the signature expected by McpServer.tool() for tools with arguments.
+ * The extra parameter contains _meta and other request context from the MCP SDK.
+ */
+type MCPToolCallback<TArgs = Record<string, unknown>> = (args: TArgs, extra: unknown) => WrappedToolResult | Promise<WrappedToolResult>;
+/**
+ * Creates a reusable payment wrapper for adding x402 payment to MCP tool handlers.
+ *
+ * This is the primary API for integrating x402 payments with MCP servers.
+ * Use this when you have an existing McpServer and want to add payment to specific tools.
+ *
+ * @param resourceServer - The x402 resource server for payment verification/settlement
+ * @param config - Payment configuration with accepts array
+ * @returns A function that wraps tool handlers with payment logic
+ *
+ * @example
+ * ```typescript
+ * // Build payment requirements using resource server
+ * const accepts = await resourceServer.buildPaymentRequirements({
+ *   scheme: "exact",
+ *   network: "eip155:84532",
+ *   payTo: "0xRecipient",
+ *   price: "$0.10",
+ * });
+ *
+ * // Create wrapper with payment requirements
+ * const paid = createPaymentWrapper(resourceServer, {
+ *   accepts,
+ *   hooks: {
+ *     onBeforeExecution: async ({ paymentPayload }) => {
+ *       if (await isRateLimited(paymentPayload.payer)) return false;
+ *     },
+ *     onAfterSettlement: async ({ settlement }) => {
+ *       await sendReceipt(settlement.transaction);
+ *     },
+ *   },
+ * });
+ *
+ * // Use with McpServer.tool()
+ * mcpServer.tool("search", "Premium search ($0.10)", { query: z.string() },
+ *   paid(async (args) => ({
+ *     content: [{ type: "text", text: "Search results..." }]
+ *   }))
+ * );
+ * ```
+ */
+declare function createPaymentWrapper(resourceServer: x402ResourceServer, config: PaymentWrapperConfig): <TArgs extends Record<string, unknown>>(handler: PaymentWrappedHandler<TArgs>) => MCPToolCallback<TArgs>;
+
+/**
+ * Extracts payment payload from MCP request _meta field.
+ * Matches HTTP transport's simple validation approach.
+ *
+ * @param params - MCP request parameters that may contain _meta
+ * @returns The payment payload if present and valid, null otherwise
+ */
+declare function extractPaymentFromMeta(params: MCPRequestParamsWithMeta | undefined): PaymentPayload | null;
+/**
+ * Attaches payment payload to MCP request params _meta field
+ *
+ * @param params - Original request params containing name and optional arguments
+ * @param params.name - The tool name
+ * @param params.arguments - Optional tool arguments
+ * @param paymentPayload - Payment payload to attach
+ * @returns New params object with payment in _meta
+ */
+declare function attachPaymentToMeta(params: {
+    name: string;
+    arguments?: Record<string, unknown>;
+}, paymentPayload: PaymentPayload): MCPRequestParamsWithMeta;
+/**
+ * Extracts payment response from MCP result _meta field
+ *
+ * @param result - MCP result that may contain _meta
+ * @returns The settlement response if present, null otherwise
+ */
+declare function extractPaymentResponseFromMeta(result: MCPResultWithMeta | undefined): SettleResponse | null;
+/**
+ * Result content item for MCP responses
+ */
+interface ResultContentItem {
+    [key: string]: unknown;
+    type: string;
+}
+/**
+ * Attaches settlement response to MCP result _meta field
+ *
+ * @param result - Original result object containing content and optional isError flag
+ * @param result.content - The tool result content array
+ * @param result.isError - Optional flag indicating if the result is an error
+ * @param settleResponse - Settlement response to attach
+ * @returns New result object with payment response in _meta
+ */
+declare function attachPaymentResponseToMeta(result: {
+    content: ResultContentItem[];
+    isError?: boolean;
+}, settleResponse: SettleResponse): MCPResultWithMeta;
+/**
+ * Creates an MCP JSON-RPC error for payment required (402)
+ *
+ * @param paymentRequired - The payment requirements
+ * @param message - Optional custom error message
+ * @returns JSON-RPC error object
+ */
+declare function createPaymentRequiredError(paymentRequired: PaymentRequired, message?: string): MCPPaymentRequiredError;
+/**
+ * Extracts PaymentRequired from an MCP JSON-RPC error
+ *
+ * @param error - The error object from a JSON-RPC response
+ * @returns The PaymentRequired if this is a 402 error, null otherwise
+ */
+declare function extractPaymentRequiredFromError(error: unknown): PaymentRequired | null;
+/**
+ * Creates a resource URL for an MCP tool
+ *
+ * @param toolName - The name of the tool
+ * @param customUrl - Optional custom URL override
+ * @returns The resource URL
+ */
+declare function createToolResourceUrl(toolName: string, customUrl?: string): string;
+
+export { type AfterExecutionContext, type AfterExecutionHook, type AfterPaymentHook, type AfterSettlementHook, type BeforeExecutionHook, type BeforePaymentHook, type DynamicPayTo, type DynamicPrice, type MCPContentItem, type MCPPaymentError, type MCPPaymentProcessResult, type MCPPaymentRequiredError, type MCPRequestParamsWithMeta, type MCPResultWithMeta, type MCPToolCallback, type MCPToolContext, type MCPToolPaymentConfig, type MCPToolResultWithPayment, MCP_PAYMENT_META_KEY, MCP_PAYMENT_REQUIRED_CODE, MCP_PAYMENT_RESPONSE_META_KEY, type PaymentRequestedContext, type PaymentRequiredContext, type PaymentRequiredHook, type PaymentRequiredHookResult, type PaymentWrappedHandler, type PaymentWrapperConfig, type ServerHookContext, type SettlementContext, type ToolContentItem, type ToolResult, type WrappedToolResult, attachPaymentResponseToMeta, attachPaymentToMeta, createPaymentRequiredError, createPaymentWrapper, createToolResourceUrl, createx402MCPClient, extractPaymentFromMeta, extractPaymentRequiredFromError, extractPaymentResponseFromMeta, isPaymentRequiredError, wrapMCPClientWithPayment, wrapMCPClientWithPaymentFromConfig, x402MCPClient, type x402MCPClientConfig, type x402MCPClientOptions, type x402MCPToolCallResult };