x402_call

Instructions

Implementation Reference

• cli.js:518-532 (handler)

  Handler function for x402_call. Validates URL, delegates to callX402Endpoint (which wraps agentcash fetch), and returns the endpoint data or error.

  async function handleCall(args) {
    const url = args.url;
    if (!url || !url.startsWith('http')) {
      return { content: [{ type: 'text', text: 'Invalid URL. Provide a full URL like https://www.alderpost.co/api/domain-shield?domain=stripe.com' }], isError: true };
    }
  
    const result = await callX402Endpoint(url);
  
    if (!result.success) {
      return { content: [{ type: 'text', text: `Call failed: ${result.error}` }], isError: true };
    }
  
    const text = typeof result.data === 'string' ? result.data : JSON.stringify(result.data, null, 2);
    return { content: [{ type: 'text', text }] };
  }

• cli.js:396-423 (registration)

  Tool registration with name 'x402_call', description, and input schema (url parameter only).

    {
      name: 'x402_call',
      description: `Call any x402 paid API endpoint with automatic USDC payment via AgentCash.
  
  Accepts a full URL with query parameters. Handles the complete x402 payment flow:
    1. Sends request → receives 402 payment requirement
    2. Signs USDC payment on Base via AgentCash wallet
    3. Retries with payment proof → returns endpoint data
  
  Requires AgentCash wallet to be set up and funded (https://agentcash.dev).
  
  Examples:
    - url: "https://www.alderpost.co/api/domain-shield?domain=stripe.com"
    - url: "https://www.alderpost.co/api/company-xray?domain=hubspot.com"
    - url: "https://www.alderpost.co/api/health-signal?query=ibuprofen"
    - url: "https://www.alderpost.co/api/property-intel?address=123+Main+St+Milwaukee+WI"
    - Works with any x402 endpoint URL discovered via x402_discover.`,
      inputSchema: {
        type: 'object',
        properties: {
          url: {
            type: 'string',
            description: 'Full endpoint URL with query parameters',
          },
        },
        required: ['url'],
      },
    },

• cli.js:678-696 (registration)

  MCP server handler registration routing 'x402_call' to handleCall function.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    switch (name) {
      case 'x402_discover':
        return handleDiscover(args);
      case 'x402_call':
        return handleCall(args);
      case 'x402_balance':
        return handleBalance();
      case 'x402_research':
        return handleResearch(args);
      default:
        return {
          content: [{ type: 'text', text: `Unknown tool: ${name}. Available: x402_discover, x402_call, x402_balance, x402_research` }],
          isError: true,
        };
    }
  });

• cli.js:351-353 (helper)

  Helper that calls agentcashExec to perform the x402 fetch with automatic payment flow.

  async function callX402Endpoint(url) {
    return agentcashExec(`fetch "${url}" -m GET --format json`);
  }

• cli.js:324-349 (helper)

  Helper that executes the AgentCash CLI command to handle x402 payment and data retrieval.

  async function agentcashExec(args) {
    try {
      const { stdout, stderr } = await execAsync(
        `npx -y agentcash ${args}`,
        { timeout: AGENTCASH_TIMEOUT_MS, maxBuffer: 1024 * 1024 }
      );
      const text = stdout.trim();
      if (!text) return { success: false, error: 'Empty response from AgentCash' };
      try {
        return { success: true, data: JSON.parse(text) };
      } catch {
        const jsonMatch = text.match(/\{[\s\S]*\}/);
        if (jsonMatch) return { success: true, data: JSON.parse(jsonMatch[0]) };
        return { success: true, data: { raw: text } };
      }
    } catch (err) {
      const msg = (err.stderr || err.message || 'Unknown error').toString();
      if (msg.includes('INSUFFICIENT_BALANCE')) {
        return { success: false, error: 'Insufficient USDC balance. Fund your wallet at https://agentcash.dev/deposit' };
      }
      if (msg.includes('ENOENT') || msg.includes('not found') || msg.includes('not recognized')) {
        return { success: false, error: 'AgentCash not found. Set up at https://agentcash.dev then run: npx agentcash install' };
      }
      return { success: false, error: `AgentCash error: ${msg.slice(0, 300)}` };
    }
  }