x402_research

Instructions

Implementation Reference

• cli.js:559-663 (handler)

  Main handler for the x402_research tool. Validates subject, detects input type (domain/IP/address/drug/sport), selects cheapest endpoints within budget (up to 5 parallel calls), calls them concurrently via AgentCash, then formats and returns a combined intelligence report.

  async function handleResearch(args) {
    const subject = args.subject;
    const budget = args.max_cost ?? 1.00;
  
    if (!subject || subject.length < 2) {
      return { content: [{ type: 'text', text: 'Subject must be at least 2 characters.' }], isError: true };
    }
  
    const inputType = detectInputType(subject);
  
    if (inputType === 'unknown') {
      return {
        content: [{
          type: 'text',
          text: `Could not determine the type of "${subject}". Provide a domain (stripe.com), IP (8.8.8.8), address (123 Main St Milwaukee WI), drug name (ibuprofen), or sport (nba).`,
        }],
        isError: true,
      };
    }
  
    // Find matching endpoints from local registry
    let endpoints;
    if (inputType === 'domain') {
      endpoints = REGISTRY.filter(ep => ep.input.type === 'domain' || ep.input.type === 'ip_or_domain');
    } else if (inputType === 'ip_or_domain') {
      endpoints = REGISTRY.filter(ep => ep.input.type === 'ip_or_domain');
    } else {
      endpoints = REGISTRY.filter(ep => ep.input.type === inputType);
    }
  
    if (endpoints.length === 0) {
      return {
        content: [{
          type: 'text',
          text: `No endpoints found for input type "${inputType}". Available: domain, IP, address, drug name, sport.`,
        }],
        isError: true,
      };
    }
  
    // Select endpoints within budget (cheapest first)
    endpoints.sort((a, b) => a.price - b.price);
    const selected = [];
    let runningCost = 0;
    for (const ep of endpoints) {
      if (runningCost + ep.price <= budget && selected.length < MAX_PARALLEL_CALLS) {
        selected.push(ep);
        runningCost += ep.price;
      }
    }
  
    if (selected.length === 0) {
      return {
        content: [{
          type: 'text',
          text: `Budget of $${budget.toFixed(2)} is too low. Cheapest endpoint costs $${endpoints[0].price.toFixed(2)}.`,
        }],
        isError: true,
      };
    }
  
    // Build URLs and call in parallel
    const calls = selected.map(ep => {
      const paramValue = encodeURIComponent(subject);
      const url = `${ep.url}?${ep.input.param}=${paramValue}`;
      return { endpoint: ep, url };
    });
  
    const results = await Promise.all(
      calls.map(async ({ endpoint, url }) => {
        const result = await callX402Endpoint(url);
        return {
          name: endpoint.name,
          price: endpoint.price,
          success: result.success,
          data: result.success ? result.data : null,
          error: result.success ? null : result.error,
        };
      })
    );
  
    // Format combined results
    const lines = [`## x402 Intelligence Report: ${subject}\n`];
    let totalCost = 0;
    let successCount = 0;
  
    for (const r of results) {
      if (r.success) {
        successCount++;
        totalCost += r.price;
        lines.push(`### ${r.name} ($${r.price.toFixed(2)})`);
        lines.push('```json');
        lines.push(JSON.stringify(r.data, null, 2).slice(0, 3000));
        lines.push('```\n');
      } else {
        lines.push(`### ${r.name} — FAILED`);
        lines.push(`Error: ${r.error}\n`);
      }
    }
  
    lines.push('---');
    lines.push(`**Summary:** ${successCount}/${results.length} endpoints called. Total cost: $${totalCost.toFixed(2)} USDC.`);
  
    return { content: [{ type: 'text', text: lines.join('\n') }] };
  }

• cli.js:438-472 (schema)

  Schema/definition for the x402_research tool, including its input schema (subject string, max_cost number) and description explaining the parallel research behavior.

    {
      name: 'x402_research',
      description: `Run comprehensive research by calling multiple x402 endpoints in parallel.
  
  Given a subject (domain, IP, address, drug name, or sport), this tool:
    1. Detects the input type automatically
    2. Finds all relevant x402 endpoints (local registry)
    3. Calls up to 5 endpoints simultaneously with automatic payment
    4. Returns all results combined for synthesis
  
  This is the fastest way to get a complete intelligence picture on any subject.
  
  Input types (auto-detected):
    - Domain "stripe.com" → calls security + company + threat + compliance + sales (~$0.64)
    - IP "8.8.8.8" → calls threat intelligence (~$0.10)
    - Address "123 Main St Milwaukee WI" → calls property/location (~$0.10)
    - Drug "ibuprofen" → calls health intelligence (~$0.10)
    - Sport "nba" → calls sports intelligence (~$0.12)
  
  Set max_cost to control budget per research call (default: $1.00).`,
      inputSchema: {
        type: 'object',
        properties: {
          subject: {
            type: 'string',
            description: 'The subject to research: domain, IP, address, drug name, or sport',
          },
          max_cost: {
            type: 'number',
            description: 'Maximum total cost in USD (default: 1.00). Cheapest endpoints called first.',
          },
        },
        required: ['subject'],
      },
    },

• cli.js:678-696 (registration)

  Registration of x402_research in the MCP CallToolRequestSchema handler — maps the name 'x402_research' to the handleResearch 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:310-318 (helper)

  Helper function that auto-detects the input type of the research subject (domain, IP, address, sport, drug) using regex patterns — used by handleResearch.

  function detectInputType(subject) {
    const s = subject.trim();
    if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(s)) return 'ip_or_domain';
    if (/^[a-zA-Z0-9][a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(s)) return 'domain';
    if (/\d+.*[a-zA-Z]+.*[a-zA-Z]{2,}/.test(s) && s.includes(' ')) return 'address';
    if (/^(nba|nfl|mlb|nhl|mls|epl|soccer|basketball|football|baseball|hockey)$/i.test(s)) return 'sport';
    if (s.length < 50) return 'drug_or_food';
    return 'unknown';
  }