# x402dash

> x402dash is a liveness monitoring and discovery index for the x402 payment protocol ecosystem. It tracks all x402 endpoints registered in the Coinbase CDP Bazaar, checks their availability every 30 minutes, computes a liveness score (0–100), and enriches metadata with AI classification and tags.

**Primary use case for AI agents:** discover which x402 endpoints are alive, what they cost, and whether they are ready to call — before spending USDC on the wrong endpoint.

## Base URLs

- Primary API: https://api.x402dash.com
- Fallback API: https://api.x402market.shop
- Frontend: https://x402dash.com

## Machine-readable discovery

- Payment manifest: `GET https://api.x402dash.com/.well-known/x402`
- This file (LLM discovery): `GET https://x402dash.com/llms.txt`
- Agent integration guide: https://x402dash.com/agents/
- **MCP server**: `https://api.x402dash.com/mcp` (streamable-http transport)
- **Register your endpoint**: `POST https://api.x402dash.com/v1/register` with `{"url": "..."}` — free, verified live, indexed in 30 min
- Submit form (for humans): https://x402dash.com/submit/

## MCP Server (Model Context Protocol)

AI agents can connect natively via MCP to search and evaluate x402 endpoints without HTTP calls.

**URL:** `https://api.x402dash.com/mcp`
**Transport:** streamable-http
**Protocol:** MCP 2025-03-26

Add to your MCP client config:
```json
{
  "mcpServers": {
    "x402dash": {
      "url": "https://api.x402dash.com/mcp"
    }
  }
}
```

**Available tools:**
- `search_endpoints(query, limit)` — FTS5 search with composite BM25 + liveness ranking
- `find_best_endpoint(task)` — agent routing: best endpoint for a task + fallbacks
- `get_endpoint_detail(endpoint)` — full record with AI enrichment, liveness, on-chain data
- `get_endpoint_history(endpoint, limit)` — liveness time-series (uptime over time)
- `list_categories()` — all categories with counts
- `list_providers(limit)` — top providers with aggregate stats
- `get_ecosystem_stats()` — totals, top endpoints, latest crawl
- `check_health()` — service status

## Free API endpoints (no auth)

- `GET /v1/ecosystem` — aggregate stats: total endpoints, avg liveness score, readiness breakdown, top 10 endpoints, last crawl time (10 req/min)
- `GET /v1/categories` — list of all categories with endpoint counts (60 req/min)
- `GET /v1/health` — service status and last crawl run (60 req/min)
- `GET /v1/liveness?endpoint=<id-or-url>` — full record for one endpoint: AI description, accepts[], all liveness layer scores, price_usd, network, pay_to (1 req/min)
- `GET /.well-known/x402` — x402 payment protocol manifest (60 req/min)
- `POST /v1/register` — self-register an x402 endpoint; body: `{"url": "...", "name": "...", "description": "...", "category": "...", "tags": [...], "contact": "..."}` — only `url` required, verified live (5 req/hour)
- `GET /v1/status` — internal operational dashboard (requires `X-Admin-Key` header): crawler, enricher, embeddings, DB health, API traffic
- `GET /v1/runs?limit=48` — last N crawl run records

## Free browse endpoints (10 req/min per IP, no auth)

- `GET /v1/endpoints?limit=50&offset=0&q=&category=&provider=` — paginated endpoint listing with liveness score, AI tags, readiness status
- `GET /v1/providers?limit=50&q=` — provider hosts with aggregate stats (endpoint count, avg/max/min score, categories)

## Paid API endpoints (60 req/min per IP, x402 · USDC on Base)

- `GET /v1/search?q=...` — **$0.002/query** — FTS5/BM25 full-text search with agent-ready filters
- `GET /v1/history?endpoint=<id>` — **$0.003/query** — liveness time-series for one endpoint
- `GET /v1/route?task=...` — **$0.005/query** — agent routing: best endpoint for a task with fallbacks
- `GET /v1/agent-search?q=...` — **$0.004/query** — semantic search: natural language queries matched via embeddings with intelligent fallbacks

### /v1/search parameters

```
q                     (required) search terms, max 200 chars, multi-term OR matching
limit                 default 20, max 100
offset                default 0
category              filter by category name (use /v1/categories for valid values)
min_score             filter by minimum liveness_score (0–100)
integration_readiness filter: ready_now | needs_payload | not_ready
network               filter by chain: e.g. eip155:8453 (Base mainnet)
max_price_usd         filter: only endpoints where price_usd <= this value
```

Each result includes `accepts[]` inline — the payment spec for that endpoint.

### /v1/history parameters

```
endpoint  (required) endpoint id or url
limit     default 100, max 500
```

Returns chronological array of: timestamp, alive, latency_ms, http_status, error.

### /v1/route parameters

```
task                  (required) keyword or short description, max 200 chars — multi-term AND matching (all terms must appear)
budget                max price_usd per endpoint call (filters out expensive endpoints)
network               chain filter: e.g. eip155:8453
min_score             minimum liveness_score, default 50
readiness             default ready_now
limit                 1–10, default 3 (1 primary + N-1 fallbacks)
```

Returns `{ "primary": {...}, "fallbacks": [...], "confidence": "high"|"medium"|"low"|"none", "candidates_evaluated": N }`.
Composite ranking: liveness (50%), latency (20%), on-chain activity (15%), price efficiency (15%). Each result includes `accepts[]` inline.

### /v1/agent-search parameters

```
q                     (required) natural language query, max 500 chars
limit                 default 10, max 50
min_score             filter by minimum liveness_score (0–100)
integration_readiness filter: ready_now | needs_payload | not_ready
network               filter by chain: e.g. eip155:8453
max_price_usd         filter: only endpoints where price_usd <= this value
```

3-tier search strategy: (1) vector cosine similarity on pre-computed embeddings, (2) LLM query expansion → FTS5, (3) direct FTS5 keyword matching.
Response includes `search_method` field indicating which strategy was used. Each result includes `accepts[]` inline.

## Key response fields

- `liveness_score` (0–100): composite of L1 response rate (47%), L2 metadata completeness (29%), L3 stability (24%)
- `integration_readiness`: `ready_now` | `needs_payload` | `not_ready`
- `liveness_confidence`: `high` (≥20 checks) | `medium` (≥5) | `low` (<5)
- `accepts[]`: payment spec for the indexed endpoint — network, payTo, asset, maxAmountRequired
- `ai_description`, `ai_category`, `ai_tags`: LLM-assigned fields, updated hourly
- `price_usd`, `network`, `pay_to`: cost and payment info for the indexed endpoint
- `onchain_tx_count_7d`, `onchain_tx_count_30d`: USDC transfer counts to endpoint's pay_to address (Base mainnet)
- `onchain_unique_payers_30d`: distinct wallets that paid in last 30 days — market signal for real usage
- `onchain_last_tx_at`: timestamp of most recent USDC transfer

## Payment protocol (x402 v2)

1. `GET /.well-known/x402` → read payTo, asset, maxAmountRequired, network
2. Call paid endpoint → receive HTTP 402 + header `X-Payment-Required: <base64 JSON spec>`
3. Sign USDC TransferWithAuthorization (EIP-3009) for exact amount to payTo
4. Retry with header `X-Payment: <base64 signed payload>`
5. Server settles via facilitator → HTTP 200 + results

Payment constants:
- Network: eip155:8453 (Base mainnet)
- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- payTo: 0x8c751d62141c9DF97292815B7ba5F1cAdEBBCE32
- USDC decimals: 6
- /v1/endpoints: FREE (rate limited 10 req/min)
- /v1/providers: FREE (rate limited 10 req/min)
- /v1/search price: 2000 atomic USDC = $0.002
- /v1/history price: 3000 atomic USDC = $0.003
- /v1/route price: 5000 atomic USDC = $0.005
- /v1/agent-search price: 4000 atomic USDC = $0.004

## Quick start (Python)

```python
import base64, json, httpx
from eth_account import Account
from x402 import x402ClientSync, parse_payment_required
from x402.mechanisms.evm.exact.register import register_exact_evm_client

account = Account.from_key("0xYOUR_PRIVATE_KEY")
client = x402ClientSync()
register_exact_evm_client(client, account, networks="eip155:8453")

API = "https://api.x402dash.com"
resp = httpx.get(f"{API}/v1/search", params={"q": "defi oracle", "limit": "5"})
# 402 → parse and sign
payment = client.create_payment_payload(parse_payment_required(resp.json()))
header = base64.b64encode(json.dumps(
    payment.model_dump(by_alias=True, exclude_none=True)
).encode()).decode()
# Retry with payment → 200 + data
data = httpx.get(f"{API}/v1/search",
    params={"q": "defi oracle", "limit": "5"},
    headers={"X-Payment": header}).json()
```

Install: `pip install x402 httpx eth-account`. Wallet needs USDC + ETH on Base mainnet.

## Example agent queries

```
# Search: discover ready DeFi price oracles on Base under $0.005
GET /v1/search?q=defi+price+oracle&integration_readiness=ready_now&network=eip155%3A8453&max_price_usd=0.005&min_score=50&limit=5
X-Payment: <signed $0.002 USDC>

# Route: get the best endpoint for a task (recommended for agents)
GET /v1/route?task=defi+oracle&budget=0.01&network=eip155%3A8453&min_score=60&limit=3
X-Payment: <signed $0.005 USDC>
→ { "primary": {..., "route_score": 78.5, "accepts": [...]}, "fallbacks": [...], "confidence": "high" }

# Agent search: find endpoints using natural language
GET /v1/agent-search?q=I+need+a+crypto+price+feed+on+Base&limit=10&min_score=50
X-Payment: <signed $0.004 USDC>
→ { "items": [...], "count": 8, "search_method": "vector", "query": "..." }
```

## Optional

- Full agent integration guide: https://x402dash.com/agents/
- Developer API reference: https://x402dash.com/developers/
- Terms and rate limits: https://x402dash.com/terms/