MPP (Machine Payments Protocol)

MPP (Machine Payments Protocol) is an open protocol that lets any HTTP client (agents, apps, or humans) pay for a resource in the same request cycle. The Agent Gateway implements MPP on surfaces, issuing payment challenges to inbound agents and verifying payment credentials before forwarding requests to protected backends. Enable MPP on a surface →

How MPP works

MPP extends HTTP with the Payment authentication scheme. The exchange uses two standard HTTP headers:

WWW-Authenticate: Payment response header: When a resource requires payment, the server returns a 402 Payment Required response containing a machine-readable challenge. The challenge specifies the protection space (realm), accepted payment methods, amounts, and a server-generated nonce that binds the subsequent credential to this specific request.

Authorization: Payment request header: The client fulfils the payment challenge and retries the original request with a payment credential in the Authorization header. The credential contains proof of payment (a signed transaction hash, a card charge ID, or a Stripe payment intent) bound to the server’s nonce via HMAC-SHA256.

On success, the server returns 200 OK with a Payment-Receipt header containing proof of delivery.

    Agent  →  GET /resource                                      →  Server
Agent  ←  402 + WWW-Authenticate: Payment <challenge>        ←  Server
Agent     fulfils payment (on-chain, card, or invoice)
Agent  →  GET /resource + Authorization: Payment <credential> →  Server
Agent  ←  200 OK + Payment-Receipt: <receipt>               ←  Server

The protocol is defined in the IETF Internet-Draft draft-httpauth-payment-00 and is transport-agnostic: it works over any standard HTTP endpoint.

Supported payment methods

Agent Gateway’s MPP implementation supports three classes of payment method, configured per surface in mpp_policy:

Each payment method entry specifies intent, currency, recipient, amount, and an optional network field for on-chain methods. The gateway presents all configured methods to the client in the WWW-Authenticate challenge. The client selects one and fulfils it.

Payment triggers

MPP payment requirements can be scoped to a subset of operations on a surface, rather than applied to every request:

• MCP surfaces: payment triggering is controlled by mcp_payment_triggers, which selects one of three modes: charge all tools/call requests, charge only tools matching a regex, or charge all tools except those matching a regex.
• A2A surfaces: payment is triggered when the inbound request matches a method name in a2a_method_filters, with optional message content matching.
• Other protocols: payment is required for all requests when MPP is enabled on the surface.

Challenge binding and verification

The gateway generates a cryptographically bound challenge on every 402 response. The nonce and request context are signed with HMAC-SHA256 using a per-surface secret key (secret_key in mpp_policy). When the credential arrives on retry, the gateway recomputes the HMAC and rejects any credential that does not match, preventing replay and credential substitution attacks.

After binding verification, the gateway verifies the payment proof itself. Verification mode is configurable per surface:

RPC endpoints for on-chain verification are configured per CAIP-2 network identifier in rpc_endpoints (for example, "eip155:8453" for Base mainnet).

Transaction store

Every MPP payment interaction is written to the gateway’s transaction store. Each record captures the surface ID, a unique transaction ID, the chosen payment method, the payment amount and currency, the verification outcome, and a timestamp. Records survive gateway restarts and are used for observability, audit, and cost attribution.

Transaction status values:

• challengeissued: a 402 challenge was issued and the agent has not yet responded.
• verified: the credential was received and payment was confirmed.
• failed: the credential was received but verification failed.

Relationship to x402

MPP and x402 are distinct protocols that solve overlapping problems using different HTTP mechanisms. x402 uses the X-Payment request header and a 402 response body for payment negotiation. MPP uses the standard HTTP WWW-Authenticate / Authorization header pair defined in the IETF Internet-Draft, keeping payment negotiation within the authentication scheme layer. Both protocols are supported natively by Agent Gateway.

Related

• x402 payment protocol: How the gateway pays x402-gated services on behalf of calling agents.
• AP2 protocol: Agent Payments Protocol for surface-level commerce flows.
• Surfaces: How surfaces route inbound agent traffic and where MPP policy is configured.