x402discovery

Runtime service discovery for the x402 payment protocol.

Find x402-payable API endpoints at runtime — no hardcoded URLs, no API key hunting. Works with any agentic framework.

Install

pip install x402discovery

Quick Start

from x402discovery import browse, discover

# Free catalog — no payment needed
services = browse()
print(f"{len(services)} services available")

# Filter by category
research_services = browse(category="research", max_price_usd=0.10)

# Search by keyword
data_services = browse(query="web scraping")

# Get the best service for a task
from x402discovery import X402DiscoveryClient

client = X402DiscoveryClient(max_price_usd=0.20)
best = client.best(category="data")
if best:
    print(f"Best service: {best['name']} at ${best['price_usd']}/call")
    print(f"Endpoint: {best['url']}")

API

browse(**kwargs) -> List[Dict]

Returns services from the free catalog, sorted by uptime% and latency.

discover(**kwargs) -> List[Dict]

Alias for browse() with a capability-focused interface.

health_check(service_id) -> Dict

Live health status for a specific service.

from x402discovery import health_check

status = health_check("legacy/cf-pay-per-crawl")
print(status["health_status"])  # "verified_up"
print(status["uptime_pct"])     # 100.0

X402DiscoveryClient

Stateful client with caching (default 5-minute TTL).

from x402discovery import X402DiscoveryClient

client = X402DiscoveryClient(max_price_usd=0.10, cache_ttl=60)
services = client.browse(category="research")
best = client.best(category="data")
print(client.format_results(services))

Service Schema

Each service dict contains:

{
    "id": "cf-pay-per-crawl",
    "service_id": "legacy/cf-pay-per-crawl",
    "name": "Cloudflare Pay Per Crawl",
    "description": "Access web content via Cloudflare's pay-per-crawl...",
    "url": "https://...",
    "category": "data",
    "price_usd": 0.001,
    "network": "base",
    "uptime_pct": 100.0,
    "avg_latency_ms": 67,
    "health_status": "verified_up",  # verified_up | unverified | verified_down
    "agent_callable": True,
    "auth_required": False,
    "llm_usage_prompt": "To use ...",  # pre-written prompt for LLM context
    "sdk_snippet_python": "import requests\n..."
}

Framework Plugins

Use framework-specific packages for native integration:

Discovery API

The underlying API: https://x402-discovery-api.onrender.com

• GET /catalog — free, full service catalog
• GET /health/{id} — live health check
• GET /.well-known/x402-discovery — well-known discovery endpoint
• GET /discover?q=... — x402-gated ($0.005/query) enhanced search

License

MIT