Developers

Developer API guide

x402dash exposes a public REST API for browsing, querying, and integrating x402 endpoint intelligence. Browse and discovery endpoints are free. Search, routing, and history queries require a micropayment via x402.

Base URLs

https://api.x402dash.com primary

https://api.x402market.shop fallback

Protocol

HTTPS only. All endpoints return JSON. CORS is open. No API key required for free endpoints.

Payment discovery

GET /.well-known/x402 — machine-readable list of payment-gated endpoints, accepted assets, and current pricing.

Pricing

Free endpoints Free · no auth

No payment, no auth required. Includes /v1/endpoints (10 req/min), /v1/providers (10 req/min), /v1/ecosystem (10 req/min), /v1/categories (60 req/min), /v1/health (60 req/min), /v1/liveness (1 req/min), /.well-known/x402 (60 req/min).

Paid endpoints x402 · USDC on Base · 60 req/min

GET /v1/search — $0.002 per query
FTS5 full-text search across all tracked endpoints with BM25 ranking, liveness scores, and AI-enriched tags. Agent-ready filters: integration_readiness, network, max_price_usd.
GET /v1/history — $0.003 per query
Complete liveness time-series for a single endpoint. Months of accumulated check data — timestamp, alive, latency_ms, http_status, error. Cannot be reconstructed from any other source.
GET /v1/route — $0.005 per query
Agent routing — returns the best endpoint for a task with composite ranking (liveness, latency, on-chain activity, price efficiency) and fallback alternatives.
GET /v1/agent-search — $0.004 per query
Semantic search via embeddings + LLM expansion. Natural language queries like "DeFi price oracle on Base" with vector similarity matching.

Rate limit: 60 requests/minute per IP for paid traffic. Payment via x402 protocol v2 — USDC on Base mainnet (eip155:8453). Attach a signed TransferWithAuthorization (EIP-3009) to the X-Payment header.

Want to list your x402 endpoint?

Submit your URL and we verify it live. Your endpoint gets a reliability score and becomes discoverable by AI agents via search, MCP, and semantic matching.

Submit your endpoint →

Free endpoints

Ecosystem stats

GET /v1/ecosystem

Aggregate totals, readiness and reachability breakdowns, top 10 diversified endpoints, recent failures, last crawl run. 10 req/min.

Health

GET /v1/health

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: description, AI enrichment, accepts array parsed from metadata, liveness layer scores (L1–L3), on-chain activity data (tx counts 7d/30d, unique payers, last transaction), price_usd, network, pay_to. 1 req/min.

Payment discovery

GET /.well-known/x402

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

Register endpoint

POST /v1/register

Self-register an x402 endpoint. Provide a URL that returns HTTP 402 with a valid x402 payment spec. Verified live before insertion. 5 req/hour. Body: {"url": "...", "name": "...", "description": "...", "category": "...", "tags": [...], "contact": "..."}. Only url is required.

Endpoints API Free · 10 req/min

Parameters

GET /v1/endpoints
  ?limit=50       (max 200)
  &offset=0
  &q=defi         (name/URL filter)
  &category=DeFi%2FCrypto
  &provider=example.com

Returns paginated list with liveness score, category, AI tags, latency, and readiness status. Includes total for client-side pagination.

Free endpoint — no payment or auth required. Rate limited to 10 requests/minute per IP.

Providers API Free · 10 req/min

Parameters

GET /v1/providers
  ?limit=100
  &q=hostname

Aggregated view by provider host — endpoint count, avg/max/min score, categories, total checks.

Note: x402dash indexes a maximum of 100 endpoints per provider host. Parametric URL variants (e.g. /stocks/AAPL, /stocks/META) are deduplicated by path template. See Terms for details.

Free endpoint — no payment or auth required. Rate limited to 10 requests/minute per IP.

Search API x402 · $0.002/query

Parameters

GET /v1/search
  ?q=defi+oracle            (required, max 200 chars)
  &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

FTS5 full-text search across name, description, URL, and category with BM25 ranking. Multi-term OR matching. Returns accepts inline so agents can see payment requirements without a second call. Descriptions come from AI enrichment when available.

integration_readiness — filter by readiness status: ready_now, needs_payload, not_ready
network — filter by chain: e.g. eip155:8453 (Base mainnet)
max_price_usd — budget cap: only return endpoints where price ≤ this value

Without a valid X-Payment header, returns HTTP 402 with X-Payment-Required header containing the payment specification (base64 JSON).

History API x402 · $0.003/query

Parameters

GET /v1/history
  ?endpoint=<id-or-url>   (required)
  &limit=100               (max 500)

Complete liveness time-series for a single endpoint. Months of accumulated check data — timestamp, alive, latency_ms, http_status, error. Cannot be reconstructed from any other source.

Without a valid X-Payment header, returns HTTP 402 with X-Payment-Required header containing the payment specification (base64 JSON).

Route API x402 · $0.005/query

Parameters

GET /v1/route
  ?task=defi+oracle          (required, max 200 chars)
  &budget=0.01               (max price_usd per endpoint call)
  &network=eip155%3A8453     (chain filter)
  &min_score=50              (default 50)
  &readiness=ready_now       (default ready_now)
  &limit=3                   (1–10, default 3)

Agent decision endpoint. Searches endpoints matching task, then ranks by composite score: liveness (50%), latency (20%), on-chain activity (15%), price efficiency (15%). Returns a primary recommendation plus fallbacks.

Response includes confidence level (high/medium/low/none), candidates_evaluated count, and accepts[] inline for each endpoint so your agent can immediately call the recommended endpoint.

Without a valid X-Payment header, returns HTTP 402 with X-Payment-Required header containing the payment specification (base64 JSON).

Agent Search API x402 · $0.004/query

Parameters

GET /v1/agent-search
  ?q=I+need+a+crypto+price+feed+on+Base   (required, max 500 chars)
  &limit=10                                (max 50, default 10)
  &min_score=50                            (default 0)
  &integration_readiness=ready_now
  &network=eip155%3A8453
  &max_price_usd=0.01

Semantic search for AI agents. Accepts natural language queries and matches endpoints using a 3-tier strategy:

Vector search — cosine similarity on pre-computed embeddings (fastest, most accurate)
LLM query expansion — expands query into keywords via LLM, then FTS5 search (fallback if embeddings unavailable)
Direct FTS5 — tokenized keyword matching (universal fallback, always works)

Response includes search_method indicating which strategy was used, and each result includes accepts[] inline. Designed for agents that need to describe what they want in plain English rather than exact keywords.

Without a valid X-Payment header, returns HTTP 402 with X-Payment-Required header containing the payment specification (base64 JSON).

x402 payment flow

1. Discover — GET /.well-known/x402 to get the accepted asset, network, price, and payTo address.
2. Request without payment — any paid endpoint returns HTTP 402 with header X-Payment-Required: <base64 JSON>.
3. Sign — client wallet signs a USDC TransferWithAuthorization (EIP-3009) for the exact amount to the payTo address.
4. Retry with payment — same request with header X-Payment: <base64 signed payload>.
5. Settle — server posts to facilitator, USDC settles on Base, HTTP 200 with results is returned.

Payment spec examples (from HTTP 402)

Search (maxAmountRequired: "2000" = $0.002 USDC):

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "2000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x8c751d62141c9DF97292815B7ba5F1cAdEBBCE32",
    "resource": "https://api.x402dash.com/v1/search"
  }]
}

History (maxAmountRequired: "3000" = $0.003 USDC):

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "3000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x8c751d62141c9DF97292815B7ba5F1cAdEBBCE32",
    "resource": "https://api.x402dash.com/v1/history"
  }]
}

Route (maxAmountRequired: "5000" = $0.005 USDC):

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "5000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x8c751d62141c9DF97292815B7ba5F1cAdEBBCE32",
    "resource": "https://api.x402dash.com/v1/route"
  }]
}

Asset is USDC on Base mainnet (eip155:8453). 6 decimals.

Quick start — Python

Full working example: discover endpoints, pay with USDC, get results. Requires pip install x402 httpx eth-account and a wallet with USDC on Base.

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

# 1. Your wallet (needs USDC + ETH on Base mainnet)
account = Account.from_key("0xYOUR_PRIVATE_KEY")

# 2. Set up x402 client with EVM payment support
client = x402ClientSync()
register_exact_evm_client(client, account, networks="eip155:8453")

# 3. Call a paid endpoint — get 402 with payment spec
API = "https://api.x402dash.com"
resp = httpx.get(f"{API}/v1/search", params={"q": "defi oracle", "limit": "5"})
# resp.status_code == 402

# 4. Parse requirements and create signed payment
payment_required = parse_payment_required(resp.json())
payment_payload = client.create_payment_payload(payment_required)

# 5. Encode as X-Payment header
payload_b64 = base64.b64encode(
    json.dumps(payment_payload.model_dump(by_alias=True, exclude_none=True)).encode()
).decode()

# 6. Retry with payment — get real data
resp2 = httpx.get(
    f"{API}/v1/search",
    params={"q": "defi oracle", "limit": "5"},
    headers={"X-Payment": payload_b64},
)
data = resp2.json()  # {"items": [...], "count": 5, ...}
print(f"Found {data['count']} endpoints")
for ep in data["items"]:
    print(f"  {ep['display_name']} — score {ep['liveness_score']}")

Cost: $0.002 per search query. USDC is transferred on Base mainnet via EIP-3009 (gasless for the caller — the facilitator pays gas).

Quick start — JavaScript / Node.js

Using fetch and the @anthropic-ai/x402 or @coinbase/x402 npm package.

// Using fetch with a pre-signed X-Payment header
const API = "https://api.x402dash.com";

// Free endpoint — no payment needed
const eco = await fetch(`${API}/v1/ecosystem`);
const { totals } = await eco.json();
console.log(`${totals.endpoints} endpoints tracked`);

// Paid endpoint — agent routing
const resp = await fetch(`${API}/v1/route?task=token+price+oracle&limit=3`, {
  headers: { "X-Payment": signedPayloadBase64 }
});
const { primary, fallbacks } = await resp.json();
console.log(`Best: ${primary.display_name} (score: ${primary.route_score})`);
console.log(`${fallbacks.length} fallback(s) available`);

See the x402 SDK for wallet setup and payment signing in JavaScript.

cURL examples

Free endpoints — no auth required:

# Ecosystem overview (10 req/min)
curl -s https://api.x402dash.com/v1/ecosystem | jq .totals

# Full detail on one endpoint (1 req/min)
curl -s "https://api.x402dash.com/v1/liveness?endpoint=defi.hugen.tokyo/tvl"

# Payment discovery (60 req/min)
curl -s https://api.x402dash.com/.well-known/x402 | jq .

# Browse endpoints — free (10 req/min)
curl -s "https://api.x402dash.com/v1/endpoints?limit=20&category=DeFi%2FCrypto"

# Providers — free (10 req/min)
curl -s "https://api.x402dash.com/v1/providers?limit=50"

Paid endpoints — HTTP 402 without valid X-Payment header:

# Search — $0.002/query
# Step 1: see the 402 + payment spec
curl -i "https://api.x402dash.com/v1/search?q=defi+price+oracle"
# → HTTP/1.1 402 Payment Required
# → X-Payment-Required: eyJ4NDAyVmVyc2lvbiI6MiwgImFjY2VwdHMiOiBb...

# Step 2: decode the spec
curl -s "https://api.x402dash.com/v1/search?q=defi" \
  -o /dev/null -D - | grep X-Payment-Required \
  | awk '{print $2}' | base64 -d | jq .

# Step 3 (x402 client): sign + retry with X-Payment header
curl -s "https://api.x402dash.com/v1/search?q=defi" \
  -H "X-Payment: <base64_signed_payload>"

# Agent-style query: find ready DeFi APIs under $0.01 on Base
curl -s "https://api.x402dash.com/v1/search?q=defi+oracle&integration_readiness=ready_now&network=eip155%3A8453&max_price_usd=0.01&min_score=60" \
  -H "X-Payment: <base64_signed_payload>"

# History — $0.003/query (same x402 flow, different price)
curl -i "https://api.x402dash.com/v1/history?endpoint=defi.hugen.tokyo/tvl&limit=50"
# → HTTP/1.1 402 Payment Required
# → X-Payment-Required: eyJ4NDAyVmVyc2lvbiI6MiwgImFjY2VwdHMiOiBb...

curl -s "https://api.x402dash.com/v1/history?endpoint=defi.hugen.tokyo/tvl&limit=50" \
  -H "X-Payment: <base64_signed_payload>"

# Route — $0.005/query (agent decision endpoint)
curl -i "https://api.x402dash.com/v1/route?task=defi+oracle&budget=0.01&network=eip155%3A8453&min_score=60&limit=3"
# → HTTP/1.1 402 Payment Required

curl -s "https://api.x402dash.com/v1/route?task=defi+oracle&budget=0.01&network=eip155%3A8453&min_score=60&limit=3" \
  -H "X-Payment: <base64_signed_payload>"
# → { "primary": {...}, "fallbacks": [...], "confidence": "high" }

Key response fields

liveness_score

0–100. Composite of response rate (47%), metadata quality (29%), and stability over time (24%). Higher is more reliable.

integration_readiness

ready now — usable with a minimal request. needs payload — live but requires specific body. not ready — unreliable.

ai_category / ai_tags

LLM-assigned category and keyword tags, enriched from endpoint metadata. More specific than rule-based category. Updated hourly.

accepts

Parsed x402 payment spec from the endpoint's metadata. Contains the network, payTo address, asset, and maxAmountRequired for that specific endpoint.

on-chain activity

onchain_tx_count_7d, onchain_tx_count_30d — USDC transfer counts to endpoint's pay_to address on Base. onchain_unique_payers_30d — distinct wallets. onchain_last_tx_at — last payment timestamp. Informational market signal, not part of liveness score.

Developer API guide

Base URLs

Protocol

Payment discovery

Pricing

Want to list your x402 endpoint?

Free endpoints

Ecosystem stats

Categories

Health

Single endpoint detail

Payment discovery

Register endpoint

Endpoints API Free · 10 req/min

Parameters

Providers API Free · 10 req/min

Parameters

Search API x402 · $0.002/query

Parameters

History API x402 · $0.003/query

Parameters

Route API x402 · $0.005/query

Parameters

Agent Search API x402 · $0.004/query

Parameters

x402 payment flow

Payment spec examples (from HTTP 402)

Quick start — Python

Quick start — JavaScript / Node.js

cURL examples

Key response fields

liveness_score

integration_readiness

ai_category / ai_tags

accepts

on-chain activity