# 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 ``, 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](https://mpp.dev/overview). ## 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](/agentpay-sdk/workflows/wallet-setup.md) or [Funding](/agentpay-sdk/workflows/funding.md) first. ## Submit an MPP request Use `agentpay mpp` for MPP-enabled HTTP endpoints: ```bash agentpay mpp ``` The URL is required. The rest of the HTTP request controls are optional. For example: ```bash agentpay mpp \ --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](/agentpay-sdk/workflows/funding.md) 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: ```bash agentpay mpp \ --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: ```bash agentpay mpp \ --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: ```bash agentpay x402 ``` 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](/agentpay-sdk/workflows.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.worldlibertyfinancial.com/agentpay-sdk/workflows/mpp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.