How x402 Works
Understand the protocol, payment flow, and key concepts behind x402.
The HTTP 402 Status Code
HTTP 402 "Payment Required" was defined in 1999 as part of the HTTP specification, reserved for future use in digital payment systems. After 25 years, x402 finally puts it to work.
When a server returns 402, it signals that the requested resource requires payment. The response includes headers that describe how to make that payment.
HTTP/1.1 402 Payment Required
X-402-Invoice-Id: inv_abc123xyz
X-402-Amount: 0.05
X-402-Pay-To: 0xABC...xyz
X-402-Network: mainnet
X-402-Description: AI Completion APIThe Payment Flow
When an agent makes a request to a paid API, here's what happens:
Initial Request
Agent makes a request to the API endpoint
402 Response
API returns 402 Payment Required with X-402 headers
Quote Request
Agent SDK calls Gateway /quote with the payment details
Policy Check
Gateway checks agent policies (limits, allowed providers, etc.)
Payment Execution
If allowed, Gateway executes MNEE payment and returns proof
Retry with Proof
Agent SDK retries original request with payment proof header
Success
API verifies proof and returns the requested resource
Key Entities
Workspace
An isolated environment containing agents, wallets, and policies. Each workspace has its own MNEE treasury.
Agent
An AI system or application that consumes paid APIs. Each agent has an API key and can have individual spending policies.
Provider
An API that accepts x402 payments. Providers receive MNEE directly to their wallet address.
Treasury
The workspace's MNEE wallet. Agents draw from this balance when making payments.
Policy
Rules that govern agent spending: daily limits, per-request limits, allowed providers, etc.
Invoice
A unique identifier for a payment request, generated by the provider and verified after payment.
About MNEE
MNEE is a USD-backed stablecoin (ERC20) on Ethereum. It provides the payment layer for x402 with several key advantages:
- Fast Settlement — Payments settle in ~12 seconds on Ethereum
- Wide Ecosystem — Built on the most widely adopted smart contract platform
- USD-Backed — 1 MNEE = $1 USD, fully backed and redeemable
- Programmable — Native support for micropayments and automation
Learn more about MNEE at mnee.io
Security Model
Non-Custodial Wallets
Each workspace generates its own MNEE wallet. The private key is encrypted with a key only the workspace controls. The Gateway never has direct access to wallet private keys.
API Key Security
Agent API keys are hashed before storage. The full key is only shown once at creation time. Keys can be rotated or revoked at any time.
Payment Verification
Providers verify payment proofs through the Gateway. Each proof is cryptographically signed and includes the transaction hash for on-chain verification.
Gateway Architecture
Agents
@x402/agent SDK
x402 Gateway
Policy & Payment Engine
Providers
@x402/server SDK