x402_discover

Instructions

Implementation Reference

• server.py:44-57 (registration)

  The @mcp.tool decorator registers 'x402_discover' as an MCP tool on the FastMCP server, with description, annotations (readOnly, idempotent, openWorld hints), and links it to the handler function below.

  @mcp.tool(
      description=(
          "Find x402-payable services by capability or keyword. "
          "Returns quality-ranked results with uptime%, latency, pricing, and ready-to-use code snippets. "
          "This tool itself costs $0.010 USDC per query via x402 micropayment — "
          "demonstrating the exact protocol it helps you discover."
      ),
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=True,
      ),
  )

• server.py:58-155 (handler)

  The x402_discover function is the main handler that takes query, capability, max_price_usd, and min_quality parameters. It queries the discovery API catalog, filters/ranks results by quality tier and price, scores by keyword/capability match, returns the top 5 results formatted with endpoint, price, health, uptime, latency, and code snippets.

  def x402_discover(
      query: str,
      capability: Optional[str] = None,
      max_price_usd: float = 0.50,
      min_quality: str = "unverified",
  ) -> str:
      """Discover x402-payable services matching your requirements.
  
      Args:
          query: What you need (e.g. 'weather data', 'image recognition', 'research').
          capability: Filter by category: research, data, compute, monitoring, verification,
                      routing, storage, translation, classification, generation, extraction,
                      summarization, enrichment, validation, other.
          max_price_usd: Maximum acceptable price per call in USD (default 0.50).
          min_quality: Minimum quality tier: unverified, bronze, silver, gold.
  
      Returns:
          Ranked list of matching services with pricing, quality signals, and code examples.
          Note: This tool is x402-gated. Your client will handle the $0.010 USDC payment automatically.
      """
      params: dict = {"q": query}
      if capability:
          params["capability"] = capability
      if max_price_usd:
          params["max_price"] = max_price_usd
      if min_quality and min_quality != "unverified":
          params["min_quality"] = min_quality
  
      try:
          with httpx.Client(timeout=15.0) as client:
              # The discovery API handles x402 payment internally
              # For MCP context, we call the catalog and filter (free tier)
              # Paid tier would go through /discover with payment headers
              resp = client.get(f"{DISCOVERY_API}/catalog", params=params)
              resp.raise_for_status()
              data = resp.json()
      except Exception as e:
          return f"Discovery API error: {e}\nAPI: {DISCOVERY_API}"
  
      services = data.get("services", [])
  
      # Filter
      quality_order = {"gold": 0, "silver": 1, "bronze": 2, "unverified": 3}
      min_q = quality_order.get(min_quality, 3)
      services = [
          s for s in services
          if quality_order.get(s.get("quality_tier", "unverified"), 3) <= min_q
          and float(s.get("price_per_call", 999)) <= max_price_usd
      ]
  
      # Text filter
      q = query.lower()
      scored = []
      for s in services:
          score = 0
          if q in s.get("name", "").lower():
              score += 3
          if q in s.get("description", "").lower():
              score += 2
          if capability and capability in s.get("capability_tags", []):
              score += 5
          if score > 0 or not query:
              scored.append((score, s))
  
      scored.sort(key=lambda x: (-x[0], quality_order.get(x[1].get("quality_tier", "unverified"), 3)))
      top = [s for _, s in scored[:5]]
  
      if not top:
          return (
              f"No services found matching '{query}'"
              + (f" with capability='{capability}'" if capability else "")
              + f" under ${max_price_usd}/call.\n\n"
              f"Browse all services: {DISCOVERY_API}/catalog\n"
              f"Register your service: POST {DISCOVERY_API}/register"
          )
  
      lines = [
          f"Found {len(top)} services matching '{query}'",
          f"discovery_powered_by: x402-discovery-layer | resolved_via: {DISCOVERY_API}\n",
      ]
      for i, s in enumerate(top, 1):
          snippet = s.get("sdk_snippet_python", "")
          endpoint = s.get('endpoint_url', s.get('url', '?'))
          if endpoint.startswith('http://'):
              endpoint = endpoint.replace('http://', 'https://', 1)
          lines.append(
              f"{i}. **{s.get('name', '?')}** [{s.get('quality_tier', 'unverified').upper()}]\n"
              f"   Endpoint: {endpoint}\n"
              f"   Price: ${s.get('price_per_call', '?')}/call\n"
              f"   Health: {s.get('health_status', '?')} | "
              f"Uptime: {s.get('uptime_pct', '?')}% | "
              f"Latency: {s.get('avg_latency_ms', '?')}ms\n"
              f"   {s.get('description', '')}\n"
              + (f"   ```python\n   {snippet[:200]}...\n   ```\n" if snippet else "")
          )
  
      lines.append(f"\nresolved_via: x402-discovery | {DISCOVERY_API}")
      return "\n".join(lines)

• server.py:20-21 (helper)

  DISCOVERY_API constant points to 'https://x402-discovery-api.onrender.com', the backend API that the x402_discover handler queries for service catalog data.

  DISCOVERY_API = "https://x402-discovery-api.onrender.com"
  WALLET_ADDRESS = os.getenv("WALLET_ADDRESS", "0xDBBe14C418466Bf5BF0ED7638B4E6849B852aFfA")

• server.py:23-41 (registration)

  The FastMCP server instantiation with name 'x402-discovery' and instructions that mention the x402_discover tool as a paid search tool costing $0.010 USDC.

  mcp = FastMCP(
      "x402-discovery",
      instructions=(
          "x402 Service Discovery — find any x402-payable API at runtime.\n\n"
          "TOOLS:\n"
          "• x402_discover — paid search ($0.010 USDC, returns top ranked results)\n"
          "• x402_browse   — free catalog browse by category\n"
          "• x402_health   — free real-time health check on any service\n"
          "• x402_register — free service registration\n"
          "• x402_attest   — free signed quality attestation (EdDSA JWT, ERC-8004 compatible)\n"
          "• x402_facilitator_check — free facilitator compatibility check\n\n"
          "HOW x402 PAYMENT WORKS:\n"
          "The discovery service returns HTTP 402 with payment instructions.\n"
          "Your x402-capable client pays automatically in USDC on Base.\n"
          f"Payment recipient: {WALLET_ADDRESS}\n"
          "Network: Base (eip155:8453) | Token: USDC\n\n"
          "DISCOVERY API: https://x402-discovery-api.onrender.com"
      ),
  )