# x402discovery

Runtime service discovery for the [x402](https://x402.org) payment protocol.

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

## Install

```bash
pip install x402discovery
```

## Quick Start

```python
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.

```python
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).

```python
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:

```python
{
    "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
