x402_browse

Instructions

Implementation Reference

• server.py:158-169 (registration)

  The @mcp.tool decorator that registers x402_browse as an MCP tool with FastMCP, including its description and annotations.

  @mcp.tool(
      description=(
          "Browse all registered x402 services, optionally filtered by category. "
          "Free, no payment required. Returns full catalog with quality signals."
      ),
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=True,
      ),
  )

• server.py:170-221 (handler)

  The main handler function for x402_browse. Takes an optional category parameter, fetches the catalog from the discovery API, sorts by quality tier, and returns a formatted string of up to 20 services.

  def x402_browse(category: Optional[str] = None) -> str:
      """Browse the complete catalog of registered x402 services.
  
      Args:
          category: Optional category filter: research, data, compute, monitoring,
                    verification, routing, storage, translation, classification,
                    generation, extraction, summarization, enrichment, validation, other.
  
      Returns:
          Full service catalog with quality tiers, pricing, and health status.
      """
      params: dict = {}
      if category:
          params["category"] = category
  
      try:
          with httpx.Client(timeout=15.0) as client:
              resp = client.get(f"{DISCOVERY_API}/catalog", params=params)
              resp.raise_for_status()
              data = resp.json()
      except Exception as e:
          return f"Error fetching catalog: {e}"
  
      services = data.get("services", [])
      total = data.get("total", len(services))
  
      if not services:
          return f"No services found" + (f" in category '{category}'" if category else "") + "."
  
      quality_order = {"gold": 0, "silver": 1, "bronze": 2, "unverified": 3}
      services.sort(key=lambda s: quality_order.get(s.get("quality_tier", "unverified"), 3))
  
      lines = [
          f"x402 Service Catalog — {total} services registered",
          f"Source: {DISCOVERY_API}/catalog\n",
      ]
      for s in services[:20]:
          endpoint = s.get('endpoint_url', s.get('url', '?'))
          if endpoint.startswith('http://'):
              endpoint = endpoint.replace('http://', 'https://', 1)
          lines.append(
              f"• {s.get('name', '?')} [{s.get('quality_tier', 'unverified').upper()}] "
              f"${s.get('price_per_call', '?')}/call\n"
              f"  {s.get('description', '')}\n"
              f"  {endpoint}"
          )
  
      if total > 20:
          lines.append(f"\n... and {total - 20} more. Full catalog: {DISCOVERY_API}/catalog")
  
      lines.append(f"\ndiscovery_powered_by: x402-discovery-layer")
      return "\n".join(lines)

• server.py:29-29 (helper)

  Reference to x402_browse in the server instructions/help text describing it as a free catalog browse by category.

  "• x402_browse   — free catalog browse by category\n"

• server.py:355-355 (helper)

  Usage hint in x402_attest tool description referencing x402_browse to find valid service IDs.

  Use x402_browse to find valid service IDs.

• server.py:372-372 (helper)

  Error message in x402_attest that directs users to use x402_browse to find valid service IDs.

  f"Browse services with x402_browse to find valid service IDs."