# Overview

_Accept Mezo USD payments for HTTP resources with x402: how the protocol works on Mezo, why it's the right fit for Bitcoin-backed payments, what you can build, and how to get hands-on._

_Source: https://mezo.org/docs/developers/getting-started/musd-payments-x402_

**[x402](https://x402.org)** is an open standard for internet native payments. 
A server returns `HTTP 402 Payment Required` response with a
machine-readable description of what it costs; a client attaches a signed
payment message and retries; a facilitator settles the payment on chain and 
the server returns a receipt along with the purchased content to the client. 

On Mezo, the default settlement asset is **MUSD**. A seller names a price, such as $0.01, 
the x402 SDK resolves that to an MUSD amount at runtime
(18 decimals, `permit2` + EIP-2612), and the buyer's wallet signs a 
message to authorize the transfer within a timebox. 

## The payment flow at a glance

*Image: Sequence diagram of an x402 payment flow on Mezo: Client/Buyer, Merchant/Server, Facilitator (facilitator.vativ.io), and Mezo Blockchain (eip155:31611).*

1. `Client` makes an HTTP request to a `server`.

2. `Server` responds with a `402 Payment Required` status and a `PaymentRequired` b64 object return as a `PAYMENT-REQUIRED` HTTP header.

3. `Client` selects one of the `PaymentRequirements` returned by the server response and creates a `PaymentPayload` based on the `scheme` & `network` of the `PaymentRequirements` they have selected.

4. `Client` retries the HTTP request, now including the `PAYMENT-SIGNATURE` HTTP header containing the `PaymentPayload` to the server.

5. `Server` verifies the `PaymentPayload` is valid either via local verification or by POSTing the `PaymentPayload` and `PaymentRequirements` to the `/verify` endpoint of a `facilitator`.

6. `Facilitator` performs verification of the object based on the `scheme` and `network` of the `PaymentPayload` and returns a `Verification Response`.

7. If the `Verification Response` is valid, the server performs the work to fulfill the request. If the `Verification Response` is invalid, the resource server returns a `402 Payment Required` status and a `Payment Required Response` JSON object in the response body.

8. `Server` either settles the payment by interacting with a blockchain directly, or by POSTing the `Payment Payload` and `Payment PaymentRequirements` to the `/settle` endpoint of a `facilitator`.

9. `Facilitator` submits the payment to the blockchain based on the `scheme` and `network` of the `Payment Payload`.

10. `Facilitator` waits for the payment to be confirmed on the blockchain.

11. `Facilitator` returns a `Payment Execution Response` to the server.

12. `Server` returns a `200 OK` response to the `Client` with the resource they requested as the body of the HTTP response, and a `PAYMENT-RESPONSE` header containing the `Settlement Response` as Base64 encoded JSON if the payment was executed successfully.

## How MUSD fits into x402

- **Network identifier:** CAIP-2 strings identify the Mezo network — Mezo
  Testnet is `eip155:31611`, Mezo Mainnet is `eip155:31612` (x402 will not
  accept short names like `"mezo-testnet"`).
- **Asset resolution:** x402 prices are dollar strings (`price: "$0.01"`).
  `@x402/evm`'s `DEFAULT_STABLECOINS` registry resolves that to the correct
  MUSD token for the chosen network at runtime — you do not hardcode an asset
  address in route configs.
- **Signing:** MUSD is a `permit2` + EIP-2612 token, so payment authorization
  is a single EIP-712 signature, with no on-chain approval transaction and no
  gas on the buyer's side.
- **Facilitator:** both networks are settled by the same facilitator,
  `https://facilitator.vativ.io`, which serves Testnet and Mainnet from one
  endpoint.

### Mezo x402 reference

A current SDK resolves the asset and settlement proxy for you at runtime; the
values below are for reference and on-chain verification — you don't hardcode
them. Only the **network id** and the **MUSD asset** differ between Testnet and
Mainnet:

| Network | CAIP-2 | MUSD asset (18 decimals) |
|---|---|---|
| Mezo Testnet | `eip155:31611` | `0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503` |
| Mezo Mainnet | `eip155:31612` | `0xdD468A1DDc392dcdbEf6db6e34E89AA338F9F186` |

Everything else is identical on both networks:

| Fact | Value |
|---|---|
| Facilitator | `https://facilitator.vativ.io` (serves both networks) |
| Settlement proxy | `0x402085c248EeA27D92E8b30b2C58ed07f9E20001` — canonical CREATE2 deploy, auto-resolved by the SDK |
| EIP-712 domain | name `Mezo USD`, version `1` — distinct from the `MUSD` symbol |
| Transfer method | `permit2` + EIP-2612 |

### SDK support
**Mezo Mainnet** (`eip155:31612`) shipped in the following canonical x402 SDK

| SDK | First Mezo Mainnet release |
|---|---|
| TypeScript `@x402/evm` | `v2.15.0` |
| Go `github.com/x402-foundation/x402/go/v2` | `v2.15.0` |
| Python `x402` (PyPI) | `v2.13.0` |

**Mezo Testnet** (`eip155:31611`) shipped in the following canonical x402 SDK

| SDK | First Mezo Testnet release |
|---|---|
| TypeScript `@x402/evm` | `v2.10.0` |
| Go `github.com/x402-foundation/x402/go/v2` | `v2.9.0` |
| Python `x402` (PyPI) | `v2.7.0` |

A Java SDK is not yet available; use the TypeScript, Go, or Python SDK above.

## Why Mezo for x402

Most chains that support x402 settle in USDC. Mezo's pitch is different:

- **Bitcoin-native settlement asset.** MUSD is minted against BTC
  collateral in the Mezo economy. Revenue denominated in MUSD stays in
  the Bitcoin ecosystem without a round-trip through ETH or centralized
  stablecoin issuers.
- **18-decimal precision for true micropayments.** A $0.001 charge is a
  first-class operation, not a rounding artifact. Metered APIs,
  per-inference AI pricing, and per-request content access can price
  realistically without batching.
- **Zero gas for buyers (facilitator pays in BTC).** The Mezo
  facilitator at `facilitator.vativ.io` sponsors every on-chain settle
  transaction in native BTC. Buyers (including AI agents) only need
  MUSD to spend and a private key to sign an EIP-712 permit2
  authorization; no BTC gas top-up, no bridged gas token, no
  pre-funding step before the first payment.
- **Predictable chain economics.** Mezo is purpose-built around
  Bitcoin-backed financial primitives, so MUSD supply and borrowing
  costs follow rules anchored to the BTC collateral base rather than
  stablecoin issuer policy.

## What you can build

x402 + MUSD on Mezo is a fit anywhere a seller wants HTTP-native pricing
without managing subscriptions, API keys, or payment-processor accounts:

- **Paywalled content.** Articles, streams, reports, research dumps.
  One `402` per protected URL, priced per asset.
- **Metered APIs.** Charge per request for weather data, crypto
  feeds, analytics endpoints, or custom business logic. No rate-limit
  dance, no API-key lifecycle to manage.
- **Pay-per-inference AI services.** Wrap an LLM, image generator, STT,
  embedding, or fine-tuned model in an x402 endpoint. Callers pay per
  invocation at true-cost pricing enabled by 18-decimal MUSD.
- **Machine-to-machine (M2M) payments.** AI agents equipped with an
  `@x402/fetch` client and a private key transact autonomously:
  discover a paid tool, read the `402` requirements, settle, consume.
  No accounts, no credential exchange, no human-in-the-loop per
  payment. With facilitator-sponsored gas, the agent only needs MUSD
  and a signing key; no BTC top-up to start transacting.
- **Paid MCP servers.** Expose agent tools via the Model Context
  Protocol and price them per call through x402. Pairs naturally with
  autonomous-agent consumers.
- **Usage-based SaaS substitution.** Replace subscription billing with
  per-use pricing for tools, dashboards, or internal services where
  usage is bursty or uncertain.

## Getting Started

For a step-by-step walkthrough (install the SDK packages, run a
paywalled seller built on `@x402/express` and the bundled
`@x402/paywall` UI, then pay it with a browser wallet), see the
**[Quickstart for x402](/docs/developers/getting-started/musd-payments-x402/x402-quickstart/)** guide.

## See also

- [Quickstart for x402](/docs/developers/getting-started/musd-payments-x402/x402-quickstart/). The step-by-step
  hands-on guide.
- [Set Up Developer Environment](/docs/developers/getting-started/configure-environment).
  Mezo RPC endpoints and network parameters.
- [Network & RPC](/docs/developers/chains/). Chain configuration
  details.
- [Borrow and Mint MUSD ↗](/docs/users/borrow/mint-musd/). User-side flow for acquiring MUSD (opens in new tab).
- [x402.org](https://x402.org). Canonical x402 protocol documentation.