x402dash — AI agent integration guide

Connection

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

Add to your MCP client configuration:

{
  "mcpServers": {
    "x402dash": {
      "url": "https://api.x402dash.com/mcp"
    }
  }
}

Available tools

• search_endpoints(query, limit) — FTS5 search + liveness ranking
• find_best_endpoint(task) — agent routing: best + fallbacks
• get_endpoint_detail(endpoint) — full record with AI enrichment
• get_endpoint_history(endpoint, limit) — liveness time-series
• list_categories() — all categories with counts
• list_providers(limit) — top providers + aggregate stats
• get_ecosystem_stats() — totals, top endpoints, last crawl
• check_health() — service status

Service identity

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 agents

An AI agent that needs to call external APIs (data feeds, DeFi, oracles, AI services) can use /v1/search to discover which x402 endpoints are currently alive, what they cost, and whether they are ready to call — before spending USDC on the wrong endpoint.

Base URLs

https://api.x402dash.com primary
https://api.x402market.shop fallback

HTTPS only. All responses are JSON. CORS open. No API key required for free endpoints.

Payment capabilities

GET https://api.x402dash.com/.well-known/x402

Returns the x402 protocol manifest: paid endpoints, accepted asset (USDC on Base), prices, and payTo address. Always check this first — prices may change.

LLM discovery file

GET https://x402dash.com/llms.txt

Structured Markdown summary of the service for LLM context injection. Lists all API endpoints with signatures, payment model, and agent-ready query examples.

Ecosystem stats

GET https://api.x402dash.com/v1/ecosystem

Live aggregate: total endpoints indexed, average liveness score, readiness breakdown (ready_now / needs_payload / not_ready), last crawl time.

Ecosystem stats

GET /v1/ecosystem
→ aggregate totals, top 10 endpoints, last crawl

Live aggregate: total endpoints indexed, average liveness score, readiness breakdown, top endpoints. 10 req/min.

Search categories

GET /v1/categories
→ { "items": [{ "category": "DeFi/Crypto", "count": 4200 }, ...] }

Get all category names and endpoint counts. Use these values as the category filter in search. 60 req/min.

Health check

GET /v1/health
→ { "status": "ok", "latest_run": {...} }

Confirms the service is operational and shows the most recent crawl run metadata. 60 req/min.

Single endpoint detail

GET /v1/liveness?endpoint=<id-or-url>
→ full record with accepts[], ai_description,
  ai_tags, L1-L3 scores, on-chain data, price_usd

Full record for one endpoint. Includes on-chain activity data (transaction counts, unique payers) and payment spec. Use this to evaluate an endpoint before calling it. 1 req/min.

Payment discovery

GET /.well-known/x402
→ x402 payment manifest with prices and payTo

Machine-readable list of payment-gated endpoints, accepted assets, and current pricing. 60 req/min.

Register endpoint

POST /v1/register
→ { "url": "https://your-api.com/endpoint" }

Self-register an x402 endpoint. Must return HTTP 402 with valid x402 spec. Optional fields: name, description, category, tags, contact. 5 req/hour.

Browse endpoints

GET /v1/endpoints
  ?limit=50 &offset=0
  &q=oracle
  &category=DeFi%2FCrypto
  &provider=example.com
→ { "items": [...], "total": 312 }

Paginated listing. Includes liveness_score, integration_readiness, ai_category, ai_tags, avg_latency_ms. 10 req/min.

Provider list

GET /v1/providers
  ?limit=50 &q=hostname
→ { "items": [{ "provider": "api.example.com",
    "endpoint_count": 5, "avg_score": 82.3,
    "categories": ["DeFi/Crypto"] }] }

Groups endpoints by host. Useful for evaluating a provider's overall reliability before querying individual endpoints. 10 req/min.

Full-text search $0.002/query

GET /v1/search
  ?q=defi+oracle          (required)
  &limit=20               (max 100)
  &offset=0
  &category=DeFi%2FCrypto
  &min_score=50.0
  &integration_readiness=ready_now
  &network=eip155%3A8453
  &max_price_usd=0.01
→ { "items": [...], "total": 47, "filters": {...} }

FTS5/BM25 ranked search. Each result includes accepts[] inline — payment spec for that endpoint — so no second call is needed. AI-enriched descriptions when available.

Agent-optimized filters: integration_readiness=ready_now to exclude unreliable endpoints, network=eip155:8453 for Base-only, max_price_usd=0.01 to stay within budget.

Liveness history $0.003/query

GET /v1/history
  ?endpoint=<id-or-url>  (required)
  &limit=100              (max 500)
→ { "items": [{ "timestamp": "...",
    "alive": true, "latency_ms": 234,
    "http_status": 200, "error": null }],
  "endpoint_id": "..." }

Complete check history in chronological order. Use to assess reliability trends before committing to an endpoint.

Agent routing $0.005/query

GET /v1/route
  ?task=defi+oracle       (required)
  &budget=0.01            (max price per call)
  &network=eip155%3A8453
  &min_score=50           (default 50)
  &readiness=ready_now    (default ready_now)
  &limit=3                (1–10, default 3)
→ { "primary": {..., "route_score": 78.5,
    "accepts": [...]},
  "fallbacks": [...],
  "confidence": "high",
  "candidates_evaluated": 47 }

Decision endpoint. Describe your task and constraints — get the best endpoint plus fallbacks, ranked by composite score (liveness 50%, latency 20%, on-chain activity 15%, price efficiency 15%). Each result includes accepts[] so your agent can call the endpoint immediately.

Semantic search $0.004/query

GET /v1/agent-search
  ?q=I+need+a+crypto+price+feed+on+Base
  &limit=10               (max 50)
  &min_score=50
  &integration_readiness=ready_now
  &network=eip155%3A8453
  &max_price_usd=0.01
→ { "items": [...], "count": 8,
  "search_method": "vector",
  "query": "I need a crypto price feed on Base" }

Natural language search. Describe what you need in plain English — the system matches via embeddings (vector), LLM-expanded keywords, or direct FTS5 as fallback. Best for agents that don't know exact endpoint names. Each result includes accepts[].

liveness_score (0–100)

Composite reliability score: L1 response rate (47%), L2 metadata completeness (29%), L3 stability over time (24%). Use min_score=60 to filter for high-quality endpoints.

integration_readiness

ready_now — endpoint is alive and callable with a minimal request.
needs_payload — alive but requires a specific request body.
not_ready — unreliable or dead.
Use ready_now in search to only surface immediately callable endpoints.

accepts[] (in search + liveness)

Payment spec for the indexed endpoint itself — not for x402dash. Contains network, payTo, asset, maxAmountRequired. Populated from the endpoint's x402 metadata.

ai_description / ai_tags

LLM-assigned description and keyword tags (updated hourly). More accurate than raw metadata. Factored into FTS index for better search relevance.

on-chain activity

onchain_tx_count_7d / onchain_tx_count_30d — USDC transfers to the endpoint's pay_to address. onchain_unique_payers_30d shows distinct wallets. Use these as market signals — endpoints with real payment activity are more likely to be production-grade.

price_usd / network

The cost to call the indexed endpoint (not x402dash). Use max_price_usd in search to stay within agent budget constraints.

liveness_confidence

high ≥20 checks, medium ≥5 checks, low <5 checks. Newer endpoints have low confidence — factor this into decision logic.

Payment constants

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

x402 client libraries

The x402 protocol is open. Reference implementations and facilitator docs: x402.org. CDP-compatible wallets support EIP-3009 signing natively.

The x402 Python SDK and TypeScript SDK both support automatic payment retry when a 402 is received.

Find a DeFi oracle on Base

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>

→ Pick item[0], read accepts[0].payTo
  and maxAmountRequired to call it.

Verify reliability before spending

# Free: check current liveness
GET /v1/liveness?endpoint=<id>
→ liveness_score, integration_readiness

# Paid: check history if score borderline
GET /v1/history?endpoint=<id>&limit=50
+ X-Payment: <signed $0.003 USDC>
→ count alive/total, check error patterns

Discover all AI-related endpoints

GET /v1/search
  ?q=AI+inference+model
  &integration_readiness=ready_now
  &min_score=40
+ X-Payment: <signed $0.002 USDC>

# Browse by category (free, 10 req/min):
GET /v1/endpoints
  ?category=AI%20%2F%20Compute
  &limit=50

Quick route (recommended)

# One call: describe task → get best endpoint
GET /v1/route
  ?task=defi+price+oracle
  &budget=0.01
  &network=eip155%3A8453
  &min_score=60
  &limit=3
+ X-Payment: <signed $0.005 USDC>

→ primary.accepts[0].payTo = target
  primary.route_score = 78.5
  2 fallbacks if primary fails

Full discovery pipeline

# Fast path (1 call):
GET /v1/route?task=...  → best match (paid $0.005)
→ Call primary using its accepts[] spec

# Detailed path (multi-step):
1. GET /v1/ecosystem   → overview (free)
2. GET /v1/categories  → category names (free)
3. GET /v1/search?q=...  → search (paid $0.002)
4. GET /v1/liveness?endpoint=... → detail (free)
5. Call the endpoint using its accepts[] spec

Crawl cadence

All endpoints are probed every 30 minutes. Liveness data is never more than 30 minutes old. Last crawl time is available in /v1/ecosystem.latest_run and /v1/health.latest_run.

AI enrichment

Descriptions and tags are enriched by LLM every hour for endpoints without AI data (50 endpoints per run). Fields: ai_description, ai_category, ai_tags, ai_enriched_at.

Data source

Endpoints are sourced from the Coinbase CDP Bazaar (public registry). Data reflects publicly listed x402 endpoints only. No private APIs are indexed.

Payments are final

x402 payments settle on-chain. Each paid request is a separate transaction. The service never pre-authorizes or batches charges. If a query returns 402 with no data, no USDC was spent.

Free endpoints

Per-endpoint limits: /v1/ecosystem 10 req/min, /v1/liveness 1 req/min, others 60 req/min. HTTP 429 + Retry-After on violation.

Paid endpoints

60 requests/minute per IP. Full production throughput for paying agents. Payment is enforced independently of rate limits.

Hard thresholds

IPs generating >500 requests in 10 minutes or >2000/hour may be automatically suspended. See Terms/AUP for full policy.