x402 Protocol

How HTTP-native payments work for paid OptimAI Search requests.

x402 is an open standard for HTTP-native payments. A client requests a resource, the server asks for payment with HTTP 402 Payment Required, the client pays onchain, and the server delivers the resource.

The model does not require accounts, API keys, or long-lived sessions.

For OptimAI Search, the important idea is simple: the HTTP request itself can carry the payment proof. Your app asks for a search, receives a 402 payment challenge when payment is needed, signs the payment, and retries the same resource.

Core concepts

Term	Meaning
Resource	Any HTTP or HTTPS endpoint, such as an API, webpage, or RPC method.
Client	The entity requesting and paying for the resource.
Resource server	The HTTP server gating the resource behind payment.
Facilitator	A server that verifies signatures and settles payments onchain.
Scheme	Logical payment mechanism, such as `exact` for a fixed amount.
Network	Specific blockchain, such as `eip155:8453` for Base mainnet.

Protocol flow

OptimAI paid search flow:

App request -> OptimAI Search API -> 402 payment challenge
             -> app signs payment -> paid retry
             -> decentralized search nodes -> cited answer

Client                    Resource Server              Facilitator
  |                              |                          |
  |---- GET /resource ---------->|                          |
  |                              |                          |
  |<--- 402 + PAYMENT-REQUIRED --|                          |
  |     base64 PaymentRequirements                         |
  |                              |                          |
  |  client picks scheme and network, then signs payload    |
  |                              |                          |
  |---- GET /resource ---------->|                          |
  |     PAYMENT-SIGNATURE: ...   |                          |
  |                              |---- POST /verify ------->|
  |                              |<--- verified ------------|
  |                              |                          |
  |                              |---- POST /settle ------->|
  |                              |                          |--> blockchain
  |                              |<--- Payment Execution ---|
  |                              |     Response             |
  |<--- 200 OK ------------------|                          |
  |     PAYMENT-RESPONSE: ...    |                          |

HTTP headers

Server to client on the 402 response:

PAYMENT-REQUIRED: <base64-encoded PaymentRequirements JSON>

Client to server on the paid retry:

PAYMENT-SIGNATURE: <base64-encoded PaymentPayload JSON>

Server to client on the successful response:

PAYMENT-RESPONSE: <base64-encoded Settlement Response JSON>

Payment requirements

The server sends a payment challenge shaped like:

type PaymentRequirements = {
  scheme: string
  network: string
  maxAmountRequired: string
  resource: string
  description: string
  mimeType: string
  payTo: string
  maxTimeoutSeconds: number
  asset: string
  extra?: object
}

Payment payload

The client retries with a signed payment payload:

type PaymentPayload = {
  scheme: string
  network: string
  payload: object
}

Schemes

exact is the common scheme for a fixed predetermined amount.

It can use:

EIP-3009 transferWithAuthorization for USDC and EURC, which enables gasless payments
Permit2 for generic ERC-20 tokens, which may require a one-time approval

Supported networks

EVM support is available through @x402/evm.

Network	CAIP-2	Mainnet	Testnet
Base	`eip155:8453`	Yes	Base Sepolia
Polygon	`eip155:137`	Yes	Not listed
Arbitrum One	`eip155:42161`	Yes	Not listed
World	`eip155:480`	Yes	World Sepolia
Ethereum	`eip155:1`	Custom	Not listed

Solana support is available through @x402/svm.

Network	CAIP-2
Mainnet	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
Devnet	`solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`

Facilitators

Payment verification and settlement are delegated to a facilitator. A facilitator validates the payment payload and submits settlement onchain.

Common options:

Facilitator	Notes
CDP Facilitator	Coinbase-hosted facilitator for Base, Polygon, Arbitrum, World, and Solana.
x402.org Testnet Facilitator	Free testnet facilitator for Base Sepolia and Solana Devnet.

The facilitator interface is small:

POST /verify
POST /settle

SDKs

TypeScript:

npm install @x402/core @x402/evm @x402/svm @x402/fetch

Python:

pip install x402

Go:

go get github.com/x402-foundation/x402/go

For OptimAI-specific search flows, use the @optimai-network/x402-sdk guide.