402 Index API

Programmatic access to the paid API directory. Free tier available, L402 payments for higher limits.

Machine-Readable API Docs

OpenAPI 3.1 Spec (JSON) · API Docs (Markdown)

Base URL

https://402index.io/api/v1

Endpoints

GET /api/v1/services

List and search services with filtering, sorting, and pagination.

Parameter	Type	Description
protocol	string	Filter by protocol: `l402` or `x402`
category	string	Filter by category (prefix match — `crypto` matches `crypto/nft`)
health	string	Filter by health: `healthy`, `degraded`, `down`, `unknown`
source	string	Filter by source: `bazaar`, `satring`, `l402apps`, `sponge`, `well-known`, `exclusive`, `self-registered`, `discovery`
featured	boolean	Only featured services: `true`
q	string	Search by name, description, or URL
max_price_usd	number	Maximum price in USD
payment_asset	string	Filter by payment asset (e.g. `BTC`, `USDC`)
payment_valid	boolean	Only x402 services with verified payment requirements: `true`
sort	string	Sort by: `name`, `price`, `latency`, `uptime`, `reliability`
order	string	Sort order: `asc` or `desc`
limit	integer	Results per page (default 50, max 200)
offset	integer	Pagination offset

GET /api/v1/services?protocol=l402&health=healthy

GET /api/v1/services/:id

Get full details for a single service, including recent health check history.

GET /api/v1/services/1

GET /api/v1/categories

List all categories with service counts, organized as a tree with subcategories.

GET /api/v1/categories

GET /api/v1/health

System health and sync status. Returns endpoint counts, distinct service/provider counts by protocol, health status breakdowns, source counts, and last sync timestamps.

GET /api/v1/health

POST /api/v1/register

Register an L402 endpoint. The URL is probed to verify L402 compliance. Registrations are reviewed before appearing in the directory. Rate limited to 10 registrations per hour per IP.

Parameter	Type	Description
url	string	Required. The endpoint URL to register
name	string	Required. Display name for the service
protocol	string	Required. Currently only `L402` is supported
http_method	string	HTTP method that triggers the L402 paywall. Default: `GET`. Allowed: `GET`, `POST`, `PUT`, `DELETE`
probe_body	string	JSON body to send during health checks and verification probes. Required for endpoints that validate the request body before issuing the L402 challenge. Must be valid JSON.
description	string	Description of what the service does
price_sats	integer	Price per request in satoshis
price_usd	number	Price per request in USD
payment_asset	string	Payment asset (e.g. `BTC`, `USDC`)
payment_network	string	Payment network (e.g. `Lightning`, `Base`, `Solana`)
category	string	Category (e.g. `bitcoin`). Defaults to `uncategorized`
provider	string	Organization or developer name
contact_email	string	Contact email (not displayed publicly)

curl -X POST https://402index.io/api/v1/register \ -H 'Content-Type: application/json' \ -d '{ "url": "https://api.example.com/resource", "name": "My L402 API", "protocol": "L402", "provider": "My Org" }'

Response codes:

Status	Meaning
`201`	Registered and pending review. Returns the service record (with `status: "pending"`) and verification details. Re-registering an existing URL+protocol updates the record.
`400`	Missing required fields, invalid protocol, invalid URL, or field exceeds max length.
`422`	L402 verification failed. The response includes actionable details: wrong HTTP status, missing `WWW-Authenticate` header, unreachable endpoint, or SSRF blocked.
`429`	Rate limit exceeded (10 registrations per hour per IP).

.well-known Auto-Discovery

If your endpoint returns 400 or 406 during verification and you haven't provided a probe_body, we'll check https://your-host/.well-known/l402-services for probe configuration. If your discovery document lists the endpoint with a request_schema, we'll construct a minimal probe body automatically. Learn more about .well-known discovery.

GET /api/v1/export.csv L402 Required

Export the full directory as CSV. Requires L402 payment — no free tier. Supports the same filters as /api/v1/services.

CSV columns: id, name, description, url, protocol, price_sats, price_usd, payment_asset, payment_network, category, provider, source, health_status, uptime_30d, latency_p50_ms, last_checked, http_method, reliability_score

Sats-only prices are automatically converted to USD using the current BTC/USD rate.

curl -H 'Authorization: L402 <macaroon>:<preimage>' \ 'https://402index.io/api/v1/export.csv?protocol=l402'

Response codes:

Status	Meaning
`200`	CSV file download (`Content-Type: text/csv`)
`402`	L402 payment required. Add `?l402=require` to get a Lightning invoice challenge.

Distribution

GET /feed.xml

RSS 2.0 feed of indexed services with a custom l402:service XML namespace. Each item includes <l402:endpoint>, <l402:protocol>, and <l402:price> tags.

Parameter	Type	Description
protocol	string	Filter: `L402` or `x402`
health	string	Filter: `healthy`, `degraded`, `down`
type	string	`new` for services added in the last 7 days

GET /feed.xml?protocol=L402&health=healthy

GET /api/v1/opportunities

Ecosystem gap analysis — identifies categories with poor coverage, missing protocols, single-provider dependencies, and failing services. Useful for developers looking for underserved niches.

Parameter	Type	Description
protocol	string	Filter opportunities by protocol: `L402` or `x402`

GET /api/v1/opportunities

POST /api/v1/webhooks

Register a webhook to receive real-time notifications when services are added, change health, or go down. Deliveries are signed with HMAC-SHA256 (X-402Index-Signature header). Rate limited to 5 registrations per hour per IP.

Parameter	Type	Description
url	string	Required. HTTPS callback URL
secret	string	Required. Shared secret for HMAC signing (min 16 chars)
events	string	Comma-separated events: `service.new`, `service.health_changed`, `service.down`. Default: `service.new`
protocol_filter	string	Only deliver for: `L402` or `x402`

curl -X POST https://402index.io/api/v1/webhooks \ -H 'Content-Type: application/json' \ -d '{ "url": "https://example.com/webhook", "secret": "your-secret-min-16-chars", "events": "service.new,service.down" }'

Management:

Method	Path	Description
`GET`	`/api/v1/webhooks/:id`	Check webhook status. Requires `X-Webhook-Secret` header.
`DELETE`	`/api/v1/webhooks/:id`	Remove webhook. Requires `X-Webhook-Secret` header.

Webhooks are auto-deactivated after 10 consecutive delivery failures.

Response Format

The services list endpoint returns JSON with the following structure:

{ "services": [ { "id": 1, "name": "Example Weather API", "description": "Real-time weather data from NOAA", "url": "https://api.example.com/weather", "protocol": "L402", "price_sats": 5, "price_usd": 0.002, "payment_asset": "BTC", "payment_network": "Lightning", "category": "real-time-data/weather", "provider": "Example Corp", "source": "exclusive", "featured": 1, "health_status": "healthy", "uptime_30d": 0.997, "latency_p50_ms": 245, "last_checked": "2025-02-28T12:00:00Z", "registered_at": "2025-01-15T08:30:00Z", "http_method": "GET", "reliability_score": 92.5, "x402_payment_valid": null, "x402_facilitator_reachable": null, "x402_asset_known": null } ], "total": 7595, "limit": 50, "offset": 0 }

Upcoming Fields

The following fields are present in the schema but currently null for all services. They will be populated as providers adopt these standards.

Field	Type	Description
l402_version	string	Protocol version (bLIP-0026)
agent_spec_url	string	URL to agent-spec.md for this endpoint (bLIP-0026)
capabilities	string	JSON array of declared agent capabilities (bLIP-0026)
token_format	string	Token format: `macaroon`, `opaque`, or `jwt`
invoice_type	string	Invoice type: `bolt11`, `bolt12`, or `taproot_asset`
pricing_model	string	Pricing model: `per-request`, `time-bounded`, or `token-bucket`
content_domain	string	Knowledge domain for AI/media endpoints (e.g. `bitcoin-media`, `ai-inference`)

Rate Limits & L402 Payments

API endpoints are rate-limited to ensure fair usage. Pay via Lightning Network to unlock higher limits.

Tier	Limit	How
Free	100 req/min per IP	No auth needed
L402	1,000 req/min per IP	`Authorization: L402 <macaroon>:<preimage>`

When you exceed the free tier, the API returns 402 Payment Required with a Lightning invoice in the WWW-Authenticate header. Pay the invoice, then include the L402 token in subsequent requests.

Exempt from rate limiting: /, /about, /api-docs, /service/*, /api/v1/health, /feed.xml, /opportunities

402 Index is the first service listed in its own directory — the CSV export endpoint is L402-gated, so we eat our own dog food.

MCP Server

Query the 402 Index directory directly from Claude, GPT, Cursor, or any MCP-compatible AI assistant.

Quick Start

npx @402index/mcp-server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "402index": { "command": "npx", "args": ["@402index/mcp-server"] } } }

Claude Code

claude mcp add 402index -- npx @402index/mcp-server

Cursor

Add to .cursor/mcp.json:

{ "mcpServers": { "402index": { "command": "npx", "args": ["@402index/mcp-server"] } } }

Available Tools

Tool	Description
`search_services`	Search/filter paid APIs by protocol, category, health, price
`get_service_detail`	Full details + health check history for a service
`list_categories`	All categories with endpoint counts
`get_directory_stats`	Ecosystem health, totals, sync timestamps