Machine Payments Protocol (MPP)

With the wallet set up and funded, AgentPay SDK can also call HTTP APIs that require inline payment.

This page covers the MPP and x402 request flow through agentpay mpp and agentpay x402.

What this page means by API

In this page, an API means a remote HTTP service endpoint, usually a URL such as <MPP_ENDPOINT_URL>, that accepts a request and returns a response.

Examples include:

• a search endpoint

• a scrape endpoint

• a chat completion endpoint

In a normal API flow, the client usually authenticates with an API key.

In an MPP or x402 flow, the endpoint can instead return a machine-readable payment requirement. AgentPay SDK handles that payment step and then retries the original request in the same flow.

Background

Machine Payments Protocol (MPP) is an open standard for machine-to-machine payments via HTTP 402 Payment Required. It was co-developed by Tempo and Stripe.

MPP standardizes a machine-native payment flow for API requests, tool calls, and content instead of relying on custom billing integrations or ordinary API key provisioning.

For the protocol overview, see mpp.dev.

Before you submit

Before any MPP or x402 request, confirm three things:

1. The machine already has a wallet

2. The wallet is funded on the chain required by the service

3. The target endpoint supports MPP or x402

If any of those are unclear, go back to Wallet setup or Funding first.

Submit an MPP request

Use agentpay mpp for MPP-enabled HTTP endpoints:

agentpay mpp <MPP_ENDPOINT_URL>

The URL is required. The rest of the HTTP request controls are optional.

For example:

agentpay mpp <MPP_ENDPOINT_URL> \
  --method POST \
  --header 'Content-Type: application/json' \
  --json-body '{"query":"example request","numResults":5}' \
  --json

The command supports reusable HTTP request controls including:

• --method

• repeatable --header

• --data

• --json-body

• --amount

• --deposit

• --session-state-file

• --close-session

Use --json when you want structured non-streaming output.

How the request works

MPP lets a client request a resource, receive a machine-readable payment challenge, satisfy that challenge, and receive the real response without leaving the original HTTP flow.

MPP is payment-method agnostic at the protocol level. This page covers the AgentPay SDK client path: how agentpay mpp responds to an MPP-enabled endpoint and completes the request.

An MPP request has three main pieces:

• Challenge - the server returns 402 Payment Required and describes the payment requirement in the WWW-Authenticate header

• Credential - the client retries the request with proof that the payment requirement was satisfied

• Receipt - the server returns the requested resource and may include a Payment-Receipt header confirming the response

Typical runtime sequence:

1. The CLI sends the request to the target endpoint

2. The endpoint returns 402 Payment Required with the payment challenge

3. agentpay mpp reads the challenge and determines the amount, token, recipient, and chain required by the service

4. The CLI satisfies the challenge and retries the request with payment proof

5. The service verifies the payment and returns the actual response

Funding

Before using an MPP endpoint, the wallet must already hold the payment asset required by the service challenge on the required chain.

For MPP charge flows:

• the payment chain comes from the server challenge

• AgentPay SDK supports any EVM-compatible network for charge flows

• on Tempo, the CLI uses the Tempo payment path

• on other EVM networks, the CLI uses the corresponding ERC-20 payment path

Tempo mainnet with chain ID 4217 is included in the current AgentPay SDK release.

If the wallet does not hold the required asset or does not have enough balance, the request cannot complete. In that case, go back to Funding first.

Check the amount

agentpay mpp supports two basic amount modes:

• omit --amount when you want the CLI to accept the amount requested by the service challenge

• provide --amount when you want the CLI to verify that the server challenge matches the expected amount before paying

Example with explicit amount verification:

agentpay mpp <MPP_ENDPOINT_URL> \
  --amount 0.005 \
  --method POST \
  --header 'Content-Type: application/json' \
  --json-body '{"input":"example payload"}' \
  --json

Use this when you want the CLI to refuse a request if the challenged amount differs from the amount you expected.

Use session mode on Tempo

For repeated requests on Tempo, agentpay mpp also supports session-style flows.

Session mode is useful when the same workflow will make multiple related requests and you want to reuse session state instead of treating each request as a separate one-shot payment.

This path supports session open, voucher signing, optional --deposit, persisted reuse through --session-state-file, and explicit close through --close-session.

Example:

agentpay mpp <TEMPO_SESSION_ENDPOINT_URL> \
  --deposit 1 \
  --session-state-file ~/.agentpay/tempo-session.json \
  --header 'Content-Type: application/json' \
  --json-body '{"prompt":"hello"}' \
  --json

Related flags:

• --deposit - funds the session

• --session-state-file - persists session state across CLI invocations

• --close-session - closes the saved session and removes the local state when the flow is complete

Session mode is Tempo-only.

Use x402

Use agentpay x402 for x402-protected HTTP endpoints:

agentpay x402 <X402_ENDPOINT_URL>

As with agentpay mpp, the URL is the required part of the command. Other HTTP request controls such as --method, repeatable --header, --data, and --json-body are optional.

agentpay x402 follows the same broad pattern: the server returns a payment requirement, the CLI satisfies it, and the original request is retried automatically.

In the current AgentPay SDK release, agentpay x402 supports exact-payment and EIP-3009 x402 flows.

The distinction in AgentPay SDK terms is simple:

• use agentpay mpp for MPP-enabled endpoints

• use agentpay x402 for x402 payment flows where the server challenge defines the exact payment requirement

Output

Successful MPP responses can include a decoded Payment-Receipt.

In --json mode, AgentPay SDK includes that decoded receipt under payment.receipt when present. Tempo session responses can also include payment.closeReceipt when the close step returns one.

For Tempo session event streams in text mode, the CLI can also handle payment-need-voucher events automatically, including top-up and voucher replenishment when needed.

Operator notes

Keep these constraints in mind:

• all request handling still happens locally on the operator's machine

• the wallet must be funded before the request starts

• --json is best for non-streaming responses

• MPP session mode is supported only on Tempo

For the full workflow sequence, return to Workflows.