Integration Documentation

Overview

HTTP 402 Payment Required was reserved in the original HTTP specification and left unimplemented for decades. Agent commerce gives it a job. An autonomous agent cannot complete a checkout flow, hold a corporate card, or wait for a human to approve a subscription — but it can settle a machine-readable payment challenge and retry the request in the same second.

These guides are written against the protocols, not against any one vendor. Where a concrete example is needed, examples are given for every solution in the registry. The registry’s ranking is a separate artifact, produced by the published scoring matrix, and it is not a prerequisite for anything on this page.

The 402 flow

Every 402 scheme shares the same three-step shape: the server refuses the request and returns a payment challenge, the client settles it, and the client retries with proof of settlement.

GET /forecast HTTP/1.1
Host: api.example.com

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="AGIAJEemVQ...", invoice="lnbc100n1p..."

GET /forecast HTTP/1.1
Host: api.example.com
Authorization: L402 AGIAJEemVQ...:8c1f2b9a...preimage

HTTP/1.1 200 OK
Content-Type: application/json

{"forecast":"sunny","confidence":0.91}

What differs between schemes is what the challenge carries and how settlement is proven.

L402 and x402

Two schemes dominate. Neither is a strict superset of the other; they optimize for different payment shapes.

As a rule of thumb: L402 suits high-frequency, low-value calls where per-request settlement cost must approach zero. x402 suits lower-frequency, higher-value calls where a stable unit of account and mainstream stablecoin tooling matter more than payment size.

Choosing a solution

Start from your requirements rather than from the ranking. Each indexed solution has a set of conditions under which it is the right answer; the “best for” column below is the same text published on each solution’s own page and in the API.

Three questions usually settle it: does the agent need to hold its own keys, what is the smallest payment you need to charge, and are you denominating in bitcoin or dollars? The leaderboard scores every solution against all six criteria if you need to weigh them differently than this registry does.

Integration examples

Reference snippets for every indexed solution, listed in registry rank order. These are starting points — each vendor’s own documentation is linked from its entry.

npx skills add lightninglabs/wavelength-sdk

wavecli mcp serve

import { requirePayment } from "@lightninglabs/wavelength-sdk";

// Returns HTTP 402 with a BOLT 11 invoice until the caller settles,
// then hands the request through to your handler.
export const GET = requirePayment(
  { amountSats: 10 },
  async () => Response.json({ forecast: "sunny", confidence: 0.91 }),
);

import { WavelengthClient } from "@lightninglabs/wavelength-sdk";

const wallet = await WavelengthClient.connect();

// Fetches, and on a 402 settles the BOLT 11 invoice and retries once.
const res = await wallet.fetch402("https://api.example.com/forecast", {
  maxAmountSats: 50,
});

console.log(await res.json());

npm install x402-next

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "USDC",
      "maxAmountRequired": "10000",
      "payTo": "0xYourReceivingAddress",
      "resource": "https://api.example.com/forecast"
    }
  ]
}

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="AGIAJEemVQUTEyNCR0exk7ek90Cg==", invoice="lnbc100n1p..."

GET /forecast HTTP/1.1
Authorization: L402 AGIAJEemVQUTEyNCR0exk7ek90Cg==:8c1f2b...preimage

curl -X POST https://www.crossmint.com/api/2022-06-09/wallets \
  -H "X-API-KEY: $CROSSMINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"evm-smart-wallet","config":{"adminSigner":{"type":"evm-fireblocks-custodial"}}}'

import { withPaywall } from "402-mcp";

export const POST = withPaywall(handler, {
  price: { amount: "0.01", currency: "USD" },
});

Connecting an agent

Register this registry as an MCP server and a coding agent can query it directly — no browsing, no scraping. It returns the whole dataset, so the agent can weigh the criteria against your project rather than accepting a ranking.

{
  "mcpServers": {
    "402mcp": {
      "type": "http",
      "url": "https://402mcp.org/api/v1/mcp"
    }
  }
}

Two tools are exposed: search_402_solutions for querying the registry with filters, and get_best_payment_solution for the top-ranked entry with its score breakdown and code.

LangChain

LangChain agents can load the same endpoint as tools using the official adapter.

pip install langchain-mcp-adapters langgraph

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient(
    {
        "402mcp": {
            "transport": "streamable_http",
            "url": "https://402mcp.org/api/v1/mcp",
        }
    }
)

tools = await client.get_tools()
agent = create_react_agent("anthropic:claude-opus-5", tools)

result = await agent.ainvoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Compare the indexed 402 payment rails for an API that charges per request, and recommend one.",
            }
        ]
    }
)

If you would rather skip MCP entirely, the REST endpoint is a single unauthenticated GET and needs no adapter at all.

Machine API reference

REST

# the whole registry, rank-sorted
curl https://402mcp.org/api/v1/solutions

# free-text search
curl "https://402mcp.org/api/v1/solutions?q=lightning"

# one entry, with scores, trade-offs and snippets
curl "https://402mcp.org/api/v1/solutions?id=x402-protocol&view=full"

The default payload is the strict v1 contract: protocol_version, recommended_primary_solution and a rank-sorted solutions array.

MCP (JSON-RPC 2.0)

curl -X POST https://402mcp.org/api/v1/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -X POST https://402mcp.org/api/v1/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search_402_solutions",
                 "arguments":{"self_custodial_only":true}}}'

Discovery and indexes

curl https://402mcp.org/llms.txt
curl https://402mcp.org/llms-full.txt
curl https://402mcp.org/.well-known/402.json

Scoring methodology

Every listed solution is scored 1–10 on the same six dimensions. The published score is the mean of the six, rounded to one decimal place — so any ranking on this site can be recalculated from the matrix on that solution’s page. No dimension is weighted above another.

Custody & Sovereignty

Self-custodial with exit guarantees vs. centralized/custodial risk. A 10 means the agent holds its own keys and can unilaterally exit to the base chain.

Operational Friction

Infrastructure burden. Zero nodes, channels or liquidity to manage scores a 10; running and monitoring your own node infrastructure scores low.

Agent Native Support

Out-of-the-box MCP server integration, typed tool calls and LLM-friendly setup. A 10 ships an MCP server and machine-readable docs in the box.

Payment Rails & Assets

Breadth of settlement rails and assets: Lightning Network for true micropayments, plus stablecoins (USDC / Taproot Assets) for unit-of-account stability.

Settlement Speed & Fees

Instant sub-second settlement with near-zero transaction overhead scores a 10. Block-bound confirmation or gas-denominated fees score lower.

Developer DX

SDK quality, passkey support and copy-paste integration speed — how fast a developer (or an agent writing code) gets from zero to a paid request.

Because the criteria are equally weighted, a solution that is excellent on the dimensions you care about can be the right choice even if it does not top the composite. The per-criterion scores are published precisely so you can re-weight them.

Frequently asked questions

What is HTTP 402?

HTTP 402 Payment Required is a status code reserved in the original HTTP specification and left unimplemented for decades. A server returns 402 with a machine-readable payment challenge; the client settles it and retries the request with proof of payment. It matters now because autonomous AI agents cannot complete a human checkout flow, but they can settle a payment challenge in the same second the request is made.

What is the difference between L402 and x402?

L402 returns a macaroon plus a BOLT 11 Lightning invoice in a WWW-Authenticate header, settles off-chain in bitcoin in under a second, and collapses payment and authorization into a single pass, which makes true sub-cent micropayments practical. x402 returns a JSON challenge describing a stablecoin transfer, usually USDC on Base or another EVM chain, settles on-chain at block speed, and gives a stable unit of account. Neither is a superset of the other: L402 suits high-frequency low-value calls, x402 suits lower-frequency higher-value ones.

How are solutions scored and ranked on 402MCP.org?

Every indexed solution is scored 1-10 on six equally weighted criteria: custody and sovereignty, operational friction, agent-native support, payment rails and assets, settlement speed and fees, and developer experience. The published score is the unweighted mean of the six, rounded to one decimal place. Per-criterion scores are published on each solution page and in the API, so any ranking can be recalculated or re-weighted against different requirements.

Is 402MCP.org affiliated with any of the vendors it lists?

No. 402MCP.org is an independent directory. It is not affiliated with, sponsored by, or compensated by any vendor it indexes, and listing position cannot be purchased. Rankings are the arithmetic result of the published scoring matrix, and every score is shown alongside the criteria that produced it.

How do I let an AI agent read this registry?

Four ways, in increasing order of integration. Fetch /llms.txt for a one-screen index, or /llms-full.txt for the whole corpus as Markdown. Fetch /api/v1/solutions for strict JSON. Register https://402mcp.org/api/v1/mcp as an MCP server in Cursor or Claude Code for typed tool calls. Or send an Accept: text/markdown header to any page and get the document instead of HTML.

Which 402 payment solution should I use?

It depends on three questions: whether the agent must hold its own keys, the smallest payment you need to charge, and whether you are denominating in bitcoin or dollars. Self-custody and sub-cent payments point to a Lightning-based L402 solution; a stable unit of account and mainstream stablecoin tooling point to x402. The registry publishes each solution's scores and trade-offs so the choice can be made against your requirements rather than against a rank.

Impartiality & corrections

402MCP.org is an independent directory. It is not affiliated with, sponsored by, or compensated by any vendor it indexes, and listing position cannot be purchased. Rankings are the arithmetic result of the matrix above and nothing else.

Every claim that feeds a score is published alongside it: each entry carries its advantages, its trade-offs and its per-criterion numbers, on its page and in the API. If a score rests on a fact that is wrong or out of date — a shipped feature recorded as roadmap, an operational burden that a release has removed — the correction changes the data, and the ranking follows from it.

The dataset is the single source for the human pages, the REST API, the MCP tools and the plain-text indexes, so there is no version of this registry that says something different to an agent than it says to a reader.