x402discovery 0.1.1

Runtime service discovery for the x402 payment protocol — find x402-payable API endpoints at runtime

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.

Parameter	Type	Default	Description
category	str	None	Filter: research, data, compute, monitoring, generation, verification, routing, storage, other
max_price_usd	float	None	Max price per call
query	str	None	Text search on name + description
base_url	str	discovery API	Override endpoint

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:

Framework	Package
LangChain	pip install langchain-x402-discovery
AutoGen	pip install autogen-x402-discovery
CrewAI	pip install crewai-x402-discovery
LlamaIndex	pip install llama-index-x402-discovery

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