x402 Protocol

developer2026-11-16

On this page

The x402 protocol lets an HTTP client pay for a resource in the same request cycle. The server answers with status 402 Payment Required and lists the price. It also names the accepted network and the asset to pay in. The client signs a payment and retries the request with proof attached. The server verifies the payment, then returns the response.

How the x402 request cycle works

The client sends a normal HTTP request. The server replies with status 402 when the resource costs money. The response body describes what the client must pay.

  • The client reads the price, the accepted network, and the payee address.
  • The client signs a payment authorization with a wallet key.
  • The client retries the same request and attaches the signed payment.
  • The server checks the payment, settles it, and returns the resource.

The public specification and examples live at https://www.x402.org. Read them before you write a client, because field names can change between versions.

Test a 402 response by hand

Send a request to a paid endpoint without any payment attached. Read the status line of the response. A 402 status confirms that the endpoint requires payment.

Then read the body. The body names the price, the network, and the payee. Compare those fields with your expectations before you write any signing code.

Why agents need x402 for paid tools

An agent that calls a paid API stops at the first 402 response. The agent code then needs a wallet, a signer, and retry logic. Each team builds these parts again.

A gateway moves that work out of the agent. The agent calls one MCP tool. The gateway handles the 402 handshake with the upstream provider and returns the result. The agent receives a normal tool response.

Give your agent paid MCP tools for research, data lookup, and code search. Each call carries a price, so the agent needs a spend limit.

Set spend limits before the first paid call

Set limits in code, not in the prompt. A model can ignore a rule written in text, but a client check always runs.

  • Cap the amount per call and per session.
  • Allow only known payee addresses.
  • Compare the amount in the 402 body with your cap before signing.
  • Log each payment next to the request ID.

A single call costs between 0 and 29.99 in USD terms, depending on the tool. Prices vary by provider, so read the price from the 402 response instead of a cached table.

What x402 does not cover

x402 handles payment for one request. It does not authenticate the user, authorize the action, or limit how often a provider gets called. Pair it with API keys or OAuth where those controls matter.

Settlement speed and fees depend on the network the server chooses. Check each network before you accept a payment.

This guide does not cover refunds. Plan for paid calls where the payment settles but the upstream request fails afterward.

Start with a paid tool call

Connect your agent to the gateway and choose a tool. The first call that returns 402 shows the exact price. Get the endpoint and keys from the connect page.

Keep the first run small. One call with a low cap shows the full cycle from the 402 response to the final result.

Live pricing — developer

Price per call, developer tools Horizontal bar chart of the price per call and the cache-hit price, in US dollars, for 12 developer tools. The same values are in the table below the chart. Price per call Cache-hit price $0.0 $0.0005 $0.001 Usage Time SeriesUsage Time Series $0.0 $0.0 Per-Tool Usage BreakdownPer-Tool Usage Breakdown $0.0 $0.0 Usage SummaryUsage Summary $0.0 $0.0 Discover ToolsDiscover Tools $0.0 $0.0 Batch Tool CallsBatch Tool Calls $0.0 $0.0 Tool Quality MetricsTool Quality Metrics $0.0 $0.0 Tool Quality RankingsTool Quality Rankings $0.0 $0.0 List Programming LanguagesList Programming Languages $0.001 $0.0001 Check CVE ID Reservation Stat…Check CVE ID Reservation Status $0.001 $0.0001 Security Advisories (deps.dev)Security Advisories (deps.dev) $0.001 $0.0001 Dependency Tree (deps.dev)Dependency Tree (deps.dev) $0.001 $0.0001 Package Info (deps.dev)Package Info (deps.dev) $0.001 $0.0001 US dollars per call
Price per call for developer tools, cheapest first.

Data source: live tool catalog snapshot, fetched 2026-11-16.

Chart data as a table
ToolPrice per callCache-hit price
Usage Time Series$0.0$0.0
Per-Tool Usage Breakdown$0.0$0.0
Usage Summary$0.0$0.0
Discover Tools$0.0$0.0
Batch Tool Calls$0.0$0.0
Tool Quality Metrics$0.0$0.0
Tool Quality Rankings$0.0$0.0
List Programming Languages$0.001$0.0001
Check CVE ID Reservation Status$0.001$0.0001
Security Advisories (deps.dev)$0.001$0.0001
Dependency Tree (deps.dev)$0.001$0.0001
Package Info (deps.dev)$0.001$0.0001
ToolProviderPrice/callCache-hit
Usage Time Seriesaccount$0$0
Per-Tool Usage Breakdownaccount$0$0
Usage Summaryaccount$0$0
Discover Toolsapibase$0$0
Batch Tool Callsplatform$0$0
Tool Quality Metricsplatform$0$0
Tool Quality Rankingsplatform$0$0
List Programming Languagesjudge0$0.001$0.0001
Check CVE ID Reservation Statuscve-mitre$0.001$0.0001
Security Advisories (deps.dev)depsdev$0.001$0.0001
Dependency Tree (deps.dev)depsdev$0.001$0.0001
Package Info (deps.dev)depsdev$0.001$0.0001

Connect via MCP

How a tool call worksAn AI agent sends a tool call to the APIbase gateway. The gateway checks payment, calls the provider API, and returns the JSON result to the agent.Your agentAPIbase gatewayProvider API1. tool call2. paid call3. JSON result flows back to the agent
Diagram: the path of one tool call.

Data source: gateway design, no measured values.

$ curl -X POST https://apibase.pro/api/v1/tools/account.timeseries/call \
  -H "Content-Type: application/json" -d '{"params": {}}'

FAQ

Is x402 the same as an API key?

No. An API key identifies the caller to the service. x402 attaches a payment to a single request. Many setups use both, so the service knows who calls and gets paid for each call.

What does the server return when payment is missing?

The server returns HTTP status 402 Payment Required. The response body lists the price, the accepted network, and the payee address that the client must use.

Which currency does x402 use?

The 402 body names the asset the server accepts, such as USDC. Check https://www.x402.org for the current rules on supported assets.

Does an agent need a wallet to use x402?

The paying side needs a wallet key that can sign the payment. A gateway can hold that key and run the handshake, so the agent code stays free of signing logic.

  1. STEP 1/2 Connect your MCP client
  2. STEP 2/2 Browse the full catalog

Written with AI assistance from APIbase's published documentation and public data; checked automatically against them. Corrections: https://apibase.pro/

Published: 2026-11-16Source: live apibase.pro catalog snapshot