X402 MCP Template

Instructions

Implementation Reference

• index.ts:159-256 (handler)

  The handler for 'example_api_call' tool. It processes input arguments, handles demo mode with sample data, and in payment mode makes a POST request to the configured API endpoint using the X402 payment client, with proper error handling for payment failures.

  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)

  The input schema definition for the 'example_api_call' tool, specifying required 'query' string and optional 'limit' number.

  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)

  The registration of the 'example_api_call' tool in the listTools response, including name, description, and input schema.

  {
    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"],
    },
  },