Payment protocols

​

What problem do these solve?

Both protocols let an agent or script pay for an HTTP-gated resource — an API call, a tool invocation, a dataset — with no human in the loop. A client requests a resource, gets 402 Payment Required, signs a payment credential — a self-contained, signed payment authorization (the x402 spec’s “payment-as-credential”; read it as signed payment, not a login credential) — and retries. Atum settles both the same way underneath, and neither Atum nor your server ever holds the payer’s funds or keys. The difference between them is architectural: who verifies and settles the payment.

​

Which one do you need?

Match whatever protocol the other side of the payment already speaks:

• Paying for a resource? Use the protocol its 402 response speaks.
• Gating a resource? Use the protocol the clients or agents you want to serve already speak.

Building something new with no existing counterparty to match? Use the trade-off below.

​

Facilitated (x402) vs. Direct (MPP)

​

How your payment settles

Whichever protocol you use, Atum settles the payment the same way underneath: a signed request is submitted, independent settlement operators submit price quotes to fulfill it, the gateway selects one, funds move from the source rail into a settlement vault and are delivered on the destination rail, and you get a settlement receipt. You never contact settlement operators directly. For the end-to-end sequence, see the payment lifecycle; for who does what, see network participants.

​

What payers check before signing

Atum’s payer SDKs (@atumlabs/x402-atum-escrow 0.4.0+, @atumlabs/mppx-atum-escrow 0.5.0+) check the merchant’s terms before they sign, and refuse with an AtumEscrowTrustError if either check fails:

• Trusted corridor. The settlement vault (and on x402, payTo), reserver and releaser must be the ones Atum serves for the source chain, and the fulfillment proxy the one it serves for the destination chain. By default these come from GET /v1/defaults on Atum’s production mainnet and testnet gateways. On any other deployment, pass your own trust resolver (for example atumGatewayTrust({ gateways: [...] })), or every payment is refused.
• Bounded spend cap. Both tokens must be listed by that trust source and be the same money (same symbol, or one of pegGroups). The signed source amount may exceed the fulfillment amount by at most maxMarkupBps, 500 (5%) by default.

​

Slow settlement

Both protocols handle a payment that is still settling the same way: the acceptance side reports pending, and the payer re-attempts the same purchase. See When a payment is still settling.

​

Next steps