Skip to main content
x402 revives the long-dormant HTTP 402 Payment Required status code as a real payment rail for agents. An agent requests a paid resource, gets a machine-readable price, pays, and retries — with no human in the loop and no pre-provisioned API key. Macropay acts as the facilitator: it quotes, verifies, and settles payments by drawing down a payer’s prepaid wallet.
x402 settlement is off by default and enabled per organization (it moves money). The payer must be a Macropay customer of the merchant with a funded prepaid wallet. Turn it on under Settings → Integrations → MCP / x402.

​
The flow

  1. Quote — the merchant asks Macropay for a signed payment requirement and returns it in a 402 body.
  2. Pay — the agent retries with an X-PAYMENT header referencing the quote and its customer id.
  3. Verify / settle — the merchant asks Macropay to verify the payment, then settle it. Settlement draws down the customer’s prepaid wallet and returns a signed proof the merchant keeps.

​
Wire format

Macropay follows the x402 shape, so x402-aware tooling interoperates. The scheme is macropay-wallet on network macropay; asset is the ISO currency (e.g. usd) and amounts are strings of minor units (cents). 402 response body (from POST /v1/x402/quote):
X-PAYMENT header — base64 of:
The quote is stateless and HMAC-signed: verify/settle trust it without a lookup, and any tampering (amount, payTo, resource) or expiry is rejected. Each quote settles at most once (idempotent + replay-safe on quote_id).

​
Endpoints

verify and settle take the same body: { paymentPayload, paymentRequirements }. settle returns { success, error?, proof? }, where proof is a signed receipt (id, quote_id, amount, currency, payer_customer_id, signature, …).

​
Pay from an MCP agent

An agent connected to the Macropay MCP server can build the X-PAYMENT header with the pay_402 tool:
“I got a 402 with quote x402q_abc — pay it as customer cus_123.”
pay_402(quote_id="x402q_abc", customer_id="cus_123") → { x_payment: "…" }. The agent re-requests the resource with X-PAYMENT: <x_payment>; the merchant settles it. (The tool only builds the header — the merchant’s settle call moves the money.)

​
Safety model

  • Off by default, opt-in per org. Settlement is refused unless the merchant has x402_enabled on — and the funds come from a wallet the customer pre-funded.
  • Signed, expiring quotes. Tampered or expired quotes are rejected; replays are blocked by the unique quote_id.
  • Real authorization. Settlement runs through the existing wallet ledger with its InsufficientBalance guard — there is no separate money-movement path.
  • Funded-balance only. v0 draws down a prepaid wallet; an agent can never spend more than its balance.

​
Roadmap

v0 settles against a prepaid wallet held with the merchant. Future work: a Macropay-level wallet usable across merchants, on-chain settlement schemes, and a drop-in @paywall(price=…) middleware that emits the 402 and verifies proofs in a few lines. The MCP agentic-commerce tools (create_checkout, record_usage) and pay_402 are the human-supervised steps toward fully autonomous agent-to-agent payments.