X402 MCP Template

Instructions

Implementation Reference

• index.ts:159-256 (handler)

  The handler function for 'example_api_call' tool. It destructures arguments, validates the query, handles demo mode with sample data and setup instructions, and in payment mode makes a POST request to the API endpoint using the X402-enabled client, returning formatted results or handling payment errors.
  case "example_api_call": { const { query, limit = 10 } = args as { query: string; limit?: number }; if (!query?.trim()) { throw new McpError(ErrorCode.InvalidParams, "Query parameter is required"); } // Demo mode - return sample data with setup instructions if (!paymentEnabled) { return { content: [ { type: "text", text: JSON.stringify( { demo_mode: true, message: "X402 payment client not configured - returning sample data", sample_data: { query: query, limit: limit, results: [ { id: "sample-1", name: "Sample Result 1", description: "This is sample data returned in demo mode", }, { id: "sample-2", name: "Sample Result 2", description: "Configure PRIVATE_KEY in .env to enable real payments", }, ], }, setup_instructions: { step_1: "Get testnet USDC from https://faucet.circle.com/", step_2: "Add your private key to .env file: PRIVATE_KEY=0x...", step_3: "Set RESOURCE_SERVER_URL to your X402 API endpoint", step_4: "Rebuild and restart: npm run build", step_5: "Try the tool again - payments will be automatic!", }, payment_info: { protocol: "X402 v1.0", network: network, cost: "Typically $0.001 - $0.01 per request", gasless: true, note: "You only pay for the API call, no gas fees!", }, }, null, 2 ), }, ], }; } // Payment mode - make real API call // TODO: Customize endpoint path and request structure for your API const endpointPath = "/api/your-endpoint"; // ← Replace with your actual endpoint try { const response = await client.post(endpointPath, { query: query.trim(), limit: limit, }); return { content: [ { type: "text", text: JSON.stringify( { success: true, payment_processed: true, data: response.data, metadata: { endpoint: endpointPath, payment_protocol: "X402 v1.0", network: network, }, }, null, 2 ), }, ], }; } catch (error: any) { // Handle X402 payment errors if (error.response?.status === 402) { throw new McpError( ErrorCode.InternalError, `Payment Required: ${error.response.data?.error || "Insufficient USDC balance or payment failed"}` ); } throw error; } }
• index.ts:112-128 (schema)

  Input schema for the 'example_api_call' tool defining the expected parameters: required 'query' string and optional 'limit' number with bounds.
  inputSchema: { type: "object", properties: { query: { type: "string", description: "Example query parameter - customize for your API", }, limit: { type: "number", description: "Optional: Maximum number of results to return", minimum: 1, maximum: 100, default: 10, }, }, required: ["query"], },
• index.ts:109-129 (registration)

  Registration of the 'example_api_call' tool in the ListTools response, including name, description, and reference to inputSchema.
  { name: "example_api_call", description: "Example tool for making X402-protected API calls. Replace with your actual API endpoints.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Example query parameter - customize for your API", }, limit: { type: "number", description: "Optional: Maximum number of results to return", minimum: 1, maximum: 100, default: 10, }, }, required: ["query"], }, },