API Documentation

Programmatic access to the x402 service directory. Free endpoints for browsing, paid search for agents via x402 protocol.

This API is itself an x402 service.

The search endpoint accepts x402 payments on Base mainnet. No API keys needed — agents pay $0.001 per query and get instant results. We practice what we preach.

Base URL

https://x402.direct

Free Endpoints

GET/api/services

Paginated list of all indexed x402 services. Supports filtering by category, network, and trust score.

Parameters

Name	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (max: 100, default: 50)
category	string	Filter by category (ai, image, weather, etc.)
network	string	Filter by network (base-mainnet, polygon, etc.)
sort	string	Sort order: score, newest, price (default: score)
minScore	integer	Minimum ScoutScore (0-100)

cURL

curl "https://x402.direct/api/services?category=ai&sort=score&limit=10"

GET/api/services/:id

Full details for a single service, including all payment options, metadata, and facilitator info.

Parameters

Name	Type	Description
id	integer	Service ID

cURL

curl "https://x402.direct/api/services/42"

GET/api/stats

Ecosystem-level statistics. Total services, providers, facilitators, and network breakdown. Cached for 5 minutes.

cURL

curl "https://x402.direct/api/stats"

Paid Endpoint

GET/api/searchx402 · $0.001

Full-text search across all indexed services. Results ranked by a blend of text relevance and trust score. Protected by x402 — agents pay $0.001 per query on Base mainnet.

Parameters

Name	Type	Description
q	string	Search query (required)
category	string	Filter by category
network	string	Filter by network
maxPrice	string	Max price in atomic units
minScore	integer	Minimum ScoutScore
limit	integer	Max results (default: 20, max: 50)

cURL

# First request returns 402 with payment details
curl -i "https://x402.direct/api/search?q=weather+api"

# After paying via x402 on Base:
curl "https://x402.direct/api/search?q=weather+api" \
  -H "X-402-Payment: <payment_proof>"

Python

import requests

# Step 1: Get payment requirements
resp = requests.get("https://x402.direct/api/search", params={"q": "weather"})
# resp.status_code == 402
# resp.headers contains x402 payment details

# Step 2: Pay on Base and include proof
resp = requests.get(
    "https://x402.direct/api/search",
    params={"q": "weather"},
    headers={"X-402-Payment": payment_proof},
)
results = resp.json()

TypeScript

// Using x402 client library
import { createX402Client } from "x402";

const client = createX402Client({ wallet: agentWallet });

const results = await client.fetch(
  "https://x402.direct/api/search?q=weather+api"
);
// Payment handled automatically by the client

x402 Payment Flow

1
Agent sends GET request to /api/search
No payment attached — just the query
2
Server returns HTTP 402 Payment Required
Response includes: price ($0.001 USDC), network (Base), payTo address, facilitator URL
3
Agent pays on Base via USDC transfer
Gasless via Coinbase Agentic Wallet or standard Base transaction
4
Agent re-sends request with payment proof
Include X-402-Payment header with the proof
5
Server verifies payment and returns results
Facilitator verifies, server responds with search results. Settlement happens after successful response.