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`
probe_status	string	Filter by probe status: `probeable` or `unprobeable`. Unprobeable services have gateways that validate request parameters before presenting payment challenges, so generic health probes cannot elicit a 402.
featured	boolean	Only featured services: `true`
q	string	Hybrid semantic + LIKE search (see below)
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`
verified	boolean	Only payment-verified services. x402: valid payment headers. L402/MPP: healthy endpoint. Domain-verified services ranked first. Recommended for agents. Example: `?verified=true`
l402_format	string	Filter L402 endpoints by macaroon format: `v2_tlv`, `v1_binary`, `v0_text`, `json`, `unknown`
lnget_compatible	boolean	Filter L402 endpoints by `lnget` client compatibility: `true` or `false`
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

Verification Tiers

The verified filter uses a tiered system:

Tier	Condition	Meaning
Domain Verified	`domain_verified=1`	Provider proved ownership via .well-known DNS challenge. Ranked first in results.
Payment Verified (x402)	`x402_payment_valid=1`	Endpoint returns spec-compliant 402 headers with valid payment requirements.
Payment Verified (L402/MPP)	`health_status='healthy'`	Endpoint responds with valid payment challenge.

Example: GET /api/v1/services?q=weather&verified=true

How `?q=` works

When q is present and no explicit sort is specified, results use a hybrid semantic + LIKE search with 5-tier composite re-rank:

Tier A: Exact name match (case-insensitive)
Tier B: LIKE match on name
Tier C: LIKE match on description
Tier D: Cosine similarity from embeddings (intent matching)
Tier E: Default order (featured, verified, category, health, name)

If the embedding service is unavailable, results fall back to LIKE-only and the response includes an X-402index-Search-Degraded header with a reason code: no-api-key, embed-timeout, embed-error, circuit-open, vec-deadline, or js-fallback-too-large.

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 and related_services (other protocol listings for the same URL with their health, pricing, and reliability data).

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 a paid API endpoint (L402, x402, or MPP). The URL is probed to verify protocol 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. One of `L402`, `x402`, or `MPP` (case-insensitive)
http_method	string	HTTP method that triggers the 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 payment 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"`), verification details, and `also_registered` (array of bonus listings auto-created when dual-protocol support is detected). Re-registering an existing URL+protocol updates the record.
`400`	Missing required fields, invalid protocol, invalid URL, or field exceeds max length.
`422`	Protocol verification failed. The response includes a diagnostic `probe` object with `httpStatus`, `headersPresent`, `bodySnippet`, and `detectedProtocols`. If a different protocol was detected than requested, a top-level `suggestedProtocol` field is included.
`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, probe_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", "probe_status": "probeable", "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, "domain_verified": 1, "l402_format": "v2_tlv", "lnget_compatible": 1, "related_protocols": [ "x402" ] } ], "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.

Domain Verification

Providers can claim their domain to edit listings directly. See the step-by-step guide for the full flow.

POST /api/v1/claim

Initiate a domain claim. Returns a verification token (keep secret for API auth) and a verification hash (post publicly at .well-known).

Parameter	Type	Description
domain	string	Required. Hostname to claim (e.g. `api.example.com`). No protocol, path, or port.
contact_email	string	Optional contact email for the provider

curl -X POST https://402index.io/api/v1/claim \ -H 'Content-Type: application/json' \ -d '{"domain": "api.example.com"}'

Response codes:

Status	Meaning
`201`	New claim created. Returns `verification_token`, `verification_hash`, `verification_url`, and `instructions`.
`200`	Existing pending claim updated with a new token.
`400`	Invalid domain format (includes protocol, path, port, or IP address).
`409`	Domain already verified by another provider.

POST /api/v1/claim/verify

Verify a pending domain claim. Fetches the .well-known/402index-verify.txt file from the domain and compares the SHA-256 hash.

Parameter	Type	Description
domain	string	Required. Domain to verify

curl -X POST https://402index.io/api/v1/claim/verify \ -H 'Content-Type: application/json' \ -d '{"domain": "api.example.com"}'

Response codes:

Status	Meaning
`200`	Domain verified. Returns `domain`, `status: "verified"`, and `services_count`.
`400`	Invalid domain format.
`404`	No pending claim found for this domain.
`409`	Domain already verified.
`410`	Claim expired (72-hour window). Initiate a new claim.
`422`	Verification failed (token mismatch, redirect, unreachable, file too large, or SSRF blocked).

POST /api/v1/claim/revoke

Revoke a verified domain claim. Invalidates the token immediately. Re-initiate the claim flow to get a new token.

Parameter	Type	Description
domain	string	Required. Verified domain to revoke
verification_token	string	Required. Current token (proves you own the claim)

curl -X POST https://402index.io/api/v1/claim/revoke \ -H 'Content-Type: application/json' \ -d '{ "domain": "api.example.com", "verification_token": "a1b2c3d4..." }'

Response codes:

Status	Meaning
`200`	Claim revoked. Returns `status: "revoked"` and next-steps message.
`400`	Missing domain or token.
`403`	Invalid token, or no verified claim for this domain.
`404`	No claim found for this domain.

POST /api/v1/admin/domains/:domain/reset Admin Only

Reset a domain's verification token. Generates a new token, reverts status to pending, and sets a new 72-hour expiry. Does NOT clear domain_verified on services (grace period).

Parameter	Type	Description
domain	string (path)	Required. Domain to reset

curl -X POST https://402index.io/api/v1/admin/domains/api.example.com/reset \ -H 'Authorization: Bearer YOUR_ADMIN_SECRET'

Response codes:

Status	Meaning
`200`	Domain reset. Returns `verification_token`, `verification_hash`, `verification_url`, `expires_at`, and `instructions`.
`401`	Missing or invalid admin authorization.
`404`	No claim found for this domain.

POST /api/v1/admin/services/:id/probe-status Admin Only

Toggle a service's probe status. When marking unprobeable, resets health metrics (health_status → unknown, consecutive_failures → 0, uptime_30d → NULL, latency_p50_ms → NULL, reliability_score → NULL).

Parameter	Type	Description
id	string (path)	Required. Service ID
probe_status	string	Required. One of `probeable` or `unprobeable`

curl -X POST https://402index.io/api/v1/admin/services/42/probe-status \ -H 'Authorization: Bearer YOUR_ADMIN_SECRET' \ -H 'Content-Type: application/json' \ -d '{"probe_status": "unprobeable"}'

Response codes:

Status	Meaning
`200`	Success. Returns `id`, `probe_status`, and `previous` probe status.
`400`	Invalid `probe_status` value (must be `probeable` or `unprobeable`).
`401`	Missing or invalid admin authorization.
`404`	Service not found.

Protocol Change Detection

During regular health checks, 402 Index detects when endpoints support additional protocols beyond what is registered (e.g., an L402 endpoint that also responds with x402 headers). Detected changes are reviewed by admins and, when approved, create new sibling listings automatically. This ensures your multi-protocol endpoints are fully represented in the directory.

PATCH /api/v1/services/:id

Edit a listing by verified domain owner. The service URL hostname must match the claimed domain.

Parameter	Type	Description
domain	string	Required. Your verified domain
verification_token	string	Required. Token from your domain claim
name	string	Display name (max 200 chars)
description	string	Description (max 2000 chars)
category	string	Category (max 100 chars)
price_usd	number	Price in USD (non-negative)
price_sats	integer	Price in satoshis (non-negative integer)
payment_asset	string	Payment asset (e.g. BTC, USDC)
payment_network	string	Payment network (e.g. Lightning, Base)

curl -X PATCH https://402index.io/api/v1/services/SERVICE_ID \ -H 'Content-Type: application/json' \ -d '{ "domain": "api.example.com", "verification_token": "a1b2c3d4...", "description": "Updated description", "category": "ai/text" }'

Response codes:

Status	Meaning
`200`	Service updated. Returns the full updated service record.
`400`	Missing domain/token, no valid fields, field exceeds max length, or invalid price value.
`403`	Invalid token, unverified domain, or service URL doesn't match claimed domain.
`404`	Service not found.

DELETE /api/v1/services/:id

Soft-delete a listing by verified domain owner. The service is hidden from all queries, health checks, and pollers. Permanently purged after 30 days. Idempotent — deleting an already-deleted service returns 200.

Parameter	Type	Description
domain	string	Required. Your verified domain
verification_token	string	Required. Token from your domain claim

curl -X DELETE https://402index.io/api/v1/services/SERVICE_ID \ -H 'Content-Type: application/json' \ -d '{ "domain": "api.example.com", "verification_token": "a1b2c3d4..." }'

Response codes:

Status	Meaning
`200`	Service soft-deleted (or already deleted). Returns `id` and confirmation message.
`400`	Missing domain or verification_token.
`403`	Invalid token, unverified domain, or service URL doesn't match claimed domain.
`404`	Service not found.

POST /api/v1/services/bulk-delete

Bulk soft-delete up to 25 listings at once. Same auth as single delete. Services whose URL doesn't match the claimed domain are skipped (not rejected).

Parameter	Type	Description
ids	array	Required. Array of service IDs to delete (max 25)
domain	string	Required. Your verified domain
verification_token	string	Required. Token from your domain claim

curl -X POST https://402index.io/api/v1/services/bulk-delete \ -H 'Content-Type: application/json' \ -d '{ "ids": [101, 102, 103], "domain": "api.example.com", "verification_token": "a1b2c3d4..." }'

Response codes:

Status	Meaning
`200`	Returns `deleted` (array of IDs), `skipped` (array of IDs), and `reasons` (object with skip reasons).
`400`	Missing fields, ids not an array, empty, or exceeds 25.
`403`	Invalid token or unverified domain.

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

402 Index API

Machine-Readable API Docs

Base URL

Endpoints

Verification Tiers

How ?q= works

.well-known Auto-Discovery

Distribution

Response Format

Upcoming Fields

Rate Limits & L402 Payments

Domain Verification

Protocol Change Detection

MCP Server

Quick Start

Claude Desktop

Claude Code

Cursor

Available Tools

How `?q=` works