x402_discover

Instructions

Implementation Reference

• cli.js:363-395 (registration)

  Tool definition and schema registration for x402_discover with input schema requiring a 'query' string.

  const TOOLS = [
    {
      name: 'x402_discover',
      description: `Search for x402 paid API endpoints that can answer a question or provide data.
  
  Discovery powered by Decixa (5,500+ verified x402 endpoints) with local registry fallback.
  Searches across the entire x402 ecosystem — not just Alderpost endpoints.
  
  Local registry includes premium endpoints backed by VirusTotal, People Data Labs, 
  Hunter.io, AbuseIPDB, Qualys SSL Labs, NIH RxNorm, US Census Bureau, OpenWeather, 
  The Odds API.
  
  Categories: security, company/business, threat intelligence, sales/leads, compliance, 
  health/drug, property/location, sports, and any x402 capability indexed by Decixa.
  
  Examples:
    - query "domain security" → finds Domain Shield + other x402 security scanners
    - query "company information" → finds Company X-Ray + other enrichment APIs
    - query "verify factual claims" → finds verification endpoints via Decixa
    - query "drug interactions" → finds Health Signal (NIH RxNorm)
  
  Use x402_call to call any discovered endpoint.`,
      inputSchema: {
        type: 'object',
        properties: {
          query: {
            type: 'string',
            description: 'What data do you need? E.g. "domain security", "company revenue", "drug interactions", "verify a claim"',
          },
        },
        required: ['query'],
      },
    },

• cli.js:479-516 (handler)

  Handler function that validates the query, calls searchAll() (which queries Decixa first, then falls back to the local registry), and formats the results.

  async function handleDiscover(args) {
    const query = args.query;
    if (!query || query.length < 2) {
      return { content: [{ type: 'text', text: 'Query must be at least 2 characters.' }], isError: true };
    }
  
    const { results, decixaUsed } = await searchAll(query);
  
    if (results.length === 0) {
      return {
        content: [{
          type: 'text',
          text: 'No x402 endpoints found matching your query. Try broader terms like "security", "company", "health", or "location".',
        }],
      };
    }
  
    const source = decixaUsed ? 'Decixa + local registry' : 'local registry (Decixa unavailable)';
    const lines = [`Found ${results.length} x402 endpoint(s) via ${source}:\n`];
  
    for (const ep of results) {
      lines.push(`**${ep.name}** — $${ep.price.toFixed(2)}/call`);
      lines.push(`  ${ep.description}`);
      if (ep.input) {
        lines.push(`  URL: ${ep.url}?${ep.input.param}=${ep.input.example}`);
      } else {
        lines.push(`  URL: ${ep.url}`);
      }
      lines.push(`  Provider: ${ep.provider}${ep.featured ? ' ★' : ''}`);
      if (ep.detail_url) {
        lines.push(`  Details: ${ep.detail_url}`);
      }
      lines.push('');
    }
    lines.push('Use x402_call with the full URL to call any endpoint.');
  
    return { content: [{ type: 'text', text: lines.join('\n') }] };
  }

• cli.js:43-67 (helper)

  Helper that calls the Decixa API to discover x402 endpoints based on capability and intent.

  async function resolveDecixa(capability, intent, opts = {}) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), DECIXA_TIMEOUT_MS);
  
    try {
      const res = await fetch('https://api.decixa.ai/api/agent/resolve', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        signal: controller.signal,
        body: JSON.stringify({
          capability: capability.toLowerCase(),
          intent,
          constraints: {
            budget: opts.budget,
            latency: opts.latency,
          },
        }),
      });
  
      if (!res.ok) throw new Error(`Decixa HTTP ${res.status}`);
      return await res.json();
    } finally {
      clearTimeout(timeout);
    }
  }

• cli.js:73-106 (helper)

  Helper that maps a natural language query to a Decixa capability + intent for the discovery API call.

  function queryToDecixa(query) {
    const q = query.toLowerCase();
  
    // Security / threat / compliance → analyze
    if (/secur|threat|malware|virus|abuse|blacklist|phish|vuln|ssl|dkim|spf|dmarc|dnssec|compli|audit|owasp|header/.test(q)) {
      return { capability: 'analyze', intent: query };
    }
    // Company / business / firmographics → analyze (Decixa classified these as Analyze)
    if (/company|business|firmograph|revenue|employee|tech.?stack|industry|enrichment|pdl/.test(q)) {
      return { capability: 'analyze', intent: query };
    }
    // Sales / leads / contacts / email → extract
    if (/sales|lead|contact|email|prospect|hunter|outreach/.test(q)) {
      return { capability: 'extract', intent: query };
    }
    // Health / drug / FDA / nutrition → analyze
    if (/health|drug|interact|fda|rxnorm|nutrition|medicine|pharma|recall|adverse/.test(q)) {
      return { capability: 'analyze', intent: query };
    }
    // Property / location / demographics → extract
    if (/property|location|address|census|demograph|school|amenity|weather|real.?estate|walkab/.test(q)) {
      return { capability: 'extract', intent: query };
    }
    // Sports / betting / odds → analyze
    if (/sport|betting|odds|nba|nfl|mlb|nhl|mls|epl|soccer|basketball|football|baseball|hockey|game/.test(q)) {
      return { capability: 'analyze', intent: query };
    }
    // Search / find / lookup → search
    if (/search|find|lookup|discover/.test(q)) {
      return { capability: 'search', intent: query };
    }
    // Generic — try analyze as broadest category
    return { capability: 'analyze', intent: query };
  }

• cli.js:270-308 (helper)

  Orchestrator helper that tries Decixa first, falls back to local registry, merges and deduplicates results.

  async function searchAll(query) {
    // Try Decixa first
    const mapping = queryToDecixa(query);
    let decixaResults = [];
    let decixaUsed = false;
  
    try {
      const data = await resolveDecixa(mapping.capability, mapping.intent, { budget: 1.00 });
      decixaResults = decixaToEndpoints(data);
      decixaUsed = true;
    } catch (err) {
      console.error(`[decixa] fallback to local: ${err.message}`);
    }
  
    // Always include local results
    const localResults = searchLocal(query);
  
    // Merge: deduplicate by URL, Decixa results first for non-Alderpost endpoints
    const seen = new Set();
    const merged = [];
  
    // Local (Alderpost) results first — they have richer metadata
    for (const ep of localResults) {
      if (!seen.has(ep.url)) {
        seen.add(ep.url);
        merged.push(ep);
      }
    }
  
    // Decixa results — add any non-Alderpost endpoints we don't already have
    for (const ep of decixaResults) {
      if (!seen.has(ep.url)) {
        seen.add(ep.url);
        merged.push(ep);
      }
    }
  
    return { results: merged, decixaUsed };
  }