MPP Client Wrapper Reference

Purpose

The MPP Client Wrapper lets Hermes pay HTTP 402 Payment Required responses from merchant APIs, enabling per-request API access through the MPP protocol. It wraps multiple MPP client tools so you can choose the one that matches your funded wallet or the merchant's challenge method.

When to Use

Use this tool when a merchant API returns an HTTP 402 response with a www-authenticate header and you want to pay it. Also use it when someone asks to "pay per request", "set up an agent wallet", "use Tempo / Privy / AgentCash", or wants to discover MPP-priced services. If Stripe Link spend produced a Shared Payment Token (SPT) and the agent needs to attach it to the 402 challenge, prefer link-cli mpp pay in that flow.

Capabilities

• Pay HTTP 402 Payment Required responses using the MPP protocol.
• Support multiple MPP client tools: link-cli, Tempo Wallet, Privy Agent CLI, AgentCash, and mppx.
• Automatically handle the 402 challenge/credential dance with mppx.
• Support non-GET methods and request bodies with mppx.
• Inspect a merchant's 402 challenge via curl.
• Verify receipt headers with mppx -v.
• Support zero-amount challenges (proof credential only).

Prerequisites

• Node.js 20+ on PATH.
• A funded wallet (Tempo/Privy/AgentCash) OR an mppx account.
• For Tempo/Privy/AgentCash: follow their respective onboarding skills (fetch their SKILL.md via web_extract).

Procedures

mppx (Fastest Path)

1. Install mppx globally and create an account:

npm install -g mppx
mppx account create

Store credentials as the CLI instructs; do not paste them into a transcript.

2. Probe the URL with curl to confirm the MPP 402 response:

curl -i <url>

Look for a response like:

HTTP/1.1 402 Payment Required
www-authenticate: tempo amount=0.1 currency=...

3. Pay the request:

mppx <url>

4. For non-GET methods or request bodies:

mppx <url> --method POST --data '<json>'

5. Verify the receipt:

mppx <url> -v

Tempo Wallet

1. Fetch the canonical skill from https://tempo.xyz/SKILL.md using web_extract.
2. Run:

tempo wallet login
tempo wallet pay <url>

Privy Agent CLI

1. Fetch the skill from https://agents.privy.io/skill.md using web_extract.
2. Run privy-agent-wallets login and follow the prompts.

AgentCash

1. Fetch the skill from https://agentcash.dev/skill.md using web_extract.
2. Run npx agentcash onboard and follow the prompts.

Parameters

Parameter	Meaning	Required
url	The merchant API endpoint that returns HTTP 402.	Yes
--method	HTTP method for the request (e.g., POST).	No (default GET)
--data	JSON body for the request.	No
-v	Verbose output to inspect receipt headers.	No

Constraints and Caveats

• Gated [linux, macos] while broader payments tooling matures on Windows.
• If the 402 challenge has method="stripe", prefer link-cli mpp pay via the stripe-link-cli skill.
• If the 402 challenge lacks method="stripe", Stripe Link cannot pay it; use mppx or a matching wallet.
• Multiple challenges in the www-authenticate header: link-cli picks tempo, stripe, mppx picks tempo; choose by your funded wallet.
• Zero-amount challenges (e.g., $0.00) work without a funded wallet; do not refuse them as broken.
• Wallet keys never enter the agent context; do not cat or read_file them.
• Server-side MPP (adding HTTP 402 to your own API) is a different skill; point to mpp.dev/quickstart/server and mppx middlewares (mppx/nextjs, mppx/hono, mppx/express, mppx/elysia, mpp-server).
• For Tempo/Privy/AgentCash, follow their respective onboarding skills (fetch SKILL.md via web_extract).
• Default client: if the user has Stripe Link or the challenge has method="stripe", use link-cli mpp pay; else use mppx for one-off calls, Tempo Wallet for persistent spend controls.

Failure Modes

• HTTP 402 without method="stripe" cannot be paid by Stripe Link.
• Multiple challenges may cause wrong client selection if the user's wallet is not funded for the chosen method.
• Wallet keys exposed if the agent reads config files (do not cat/read_file).
• Server-side MPP tasks fail if this skill is used incorrectly.

Verification

Check your mppx installation and account:

mppx --version && mppx account list

Examples

• Probe a URL with curl -i to confirm an MPP 402 response.
• Pay a GET request: mppx <url>
• Pay a POST request with body: mppx <url> --method POST --data '<json>'
• Verify receipt: mppx <url> -v
• Tempo Wallet: tempo wallet login then tempo wallet pay <url>

Additional Notes

• Use mpp decode to inspect challenge or credential data when debugging.
• Always run commands in a terminal environment.
• For zero-amount challenges, the $0.00 value indicates a proof-only credential.