x402 basics

What is x402?

x402 is a way for APIs to request payment over HTTP so software can discover a price, pay programmatically, retry the request, and receive structured JSON.

Current production mode: Base mainnet USDC billing beta on primitive402.dev.
status.json is the live source Billing policy Mainnet readiness Mainnet monitoring

The short version

In plain English, x402 turns a paid API call into a clear HTTP flow: request, HTTP 402 Payment Required, pay, retry, structured JSON response.

The first request asks for a paid resource. The API replies with machine-readable payment requirements. An x402-capable client pays, retries with payment information, and then receives the API result.

HTTP 402 Payment Required

HTTP 402 means Payment Required. It has historically been reserved and rarely used on the public web. x402 makes 402 practical for programmatic payments by defining how an API can tell a client what payment is needed before the client retries.

x402 is not the only possible use of HTTP 402, but it is a concrete way to use the status code for machine-to-machine and AI-agent payment flows.

What x402 adds

  • payment amount
  • network
  • asset/token
  • payTo recipient
  • resource URL
  • retry after payment
  • machine-readable payment requirements

Why AI agents care

  • agents can discover tools
  • pay per call
  • avoid subscriptions or API-key setup for every tiny action
  • use structured JSON outputs
  • support agent commerce and paid APIs

Primitive402's role

Primitive402 does not own x402 or the x402 protocol. Primitive402 provides paid microtools that agents can call through x402.

Free /v1 routes exist for development. Paid /x402/v1 routes use Base mainnet USDC in the current production mainnet beta. /status.json is the source of truth for live billing mode, network, and payment asset.

Simple Primitive402 flow

  1. Agent requests a paid Primitive402 route.
  2. Primitive402 returns HTTP 402 with payment requirements.
  3. An x402-capable client pays Base mainnet USDC.
  4. The client retries with payment.
  5. Primitive402 returns structured JSON.

Example Primitive402 tools

safe_fetch_url check_prompt_injection_risk verify_claim_against_source extract_return_policy extract_subscription_terms check_product_fit

Payment and billing caveats

  • HTTP 402 Payment Required challenges are not charged.
  • Successful paid 2xx responses are billable.
  • Low-confidence 200 responses may still be billable because they are valid structured outputs.
  • There are no automatic refunds in beta. Billing issues are manually reviewed.
  • Never send private keys, seed phrases, admin tokens, or secrets.

Read next

x402 technical docs Paid x402 client test Primitive402 tools Billing policy Live status JSON TypeScript SDK x402 pay-per-call APIs

FAQ

Is x402 the same as HTTP 402?

No. HTTP 402 is the Payment Required status code. x402 is a payment protocol pattern that uses HTTP 402 to communicate machine-readable payment requirements for programmatic payments.

Does Primitive402 own x402?

No. Primitive402 does not own x402. Primitive402 uses x402 to expose paid API microtools for agents.

Do humans need to manually pay every request?

No. In normal x402 usage, an x402-capable client handles the payment and retry flow programmatically.

What chain/token does Primitive402 use?

Production paid x402 routes use Base mainnet USDC during the current mainnet beta.

Are 402 challenges charged?

No. HTTP 402 Payment Required challenges are not charged.

Are successful paid 200 responses billable?

Yes. Successful paid 200 responses are 2xx responses and are billable.

Can I try tools for free?

Yes. Free /v1 routes exist for development and testing. Paid production aliases live under /x402/v1.

How does the SDK fit in?

The published @primitive402/sdk helps TypeScript apps call Primitive402 tools and work with structured JSON outputs. See /docs/sdk.