MPP Protocol — MPPCash Docs

What is MPP?

The Machine Payments Protocol is an open standard co-authored by Stripe and Tempo. It extends HTTP with a payment negotiation layer: a service returns HTTP 402 Payment Required when a resource has a cost, and the client fulfills the payment before retrying the request. MPPCash implements MPP as its primary payment layer, with Solana as the settlement chain.

Because MPP is an open protocol, any MPP-compliant service is immediately payable by an MPPCash agent wallet — no per-service integration required. The MPP provider directory currently includes 100+ services, including Alchemy, Anthropic, Dune Analytics, and Shopify.

The HTTP 402 flow

text

Agent → GET https://api.provider.xyz/data
                              ↓
Service ← HTTP 402 Payment Required
          WWW-Authenticate: Payment realm="data-api",
            method="solana-usdc",
            amount="0.002",
            currency="USDC",
            challenge="ch_7f3a9b2c..."
                              ↓
MPPCash SDK: check wallet balance + policy
            sign payment credential for challenge
                              ↓
Agent → GET https://api.provider.xyz/data
        Authorization: Payment credential="pay_cred_...",
          method="solana-usdc",
          signature="..."
                              ↓
Service ← HTTP 200 OK
          Payment-Receipt: receipt_id="rcpt_...",
            amount="0.002", currency="USDC"
          [resource body]
                              ↓
MPPCash: batch receipt → on-chain settlement on Solana

Charge intent

The Charge intent settles each payment immediately on-chain. Use it for infrequent, higher-value calls where you want instant verifiable settlement per request.

typescript

import { MPPCash } from "@mppcash/sdk";

const agent = new MPPCash.Agent({
  wallet: process.env.MPPPAL_WALLET_ID,
  apiKey: process.env.MPPPAL_AGENT_KEY,
  intent: "charge", // settle each payment immediately
});

const http = agent.createHttpClient();

// Every 402 challenge resolves as a separate on-chain Solana transaction
const result = await http.get("https://api.provider.xyz/report");
console.log(result.data);

Session intent

The Session intent pre-authorizes a spending cap and streams micropayments off-chain. Thousands of small payments aggregate into a single on-chain settlement when the session closes. Use it for agents making many requests to the same service in a tight loop.

typescript

import { MPPCash } from "@mppcash/sdk";

const agent = new MPPCash.Agent({
  wallet: process.env.MPPPAL_WALLET_ID,
  apiKey: process.env.MPPPAL_AGENT_KEY,
  intent: "session",
  sessionCap: "5.00", // pre-authorize up to $5 USDC for this session
});

const http = agent.createHttpClient();

// 500 calls to the same inference API — one Solana tx at the end, not 500
for (const doc of documents) {
  const summary = await http.post("https://api.inference.xyz/summarize", {
    text: doc.content,
  });
  results.push(summary.data);
}

// Session closes automatically when the agent is done or cap is reached
await agent.closeSession();
// Single on-chain settlement fires. Unused locked USDC returned to wallet.

Manual session management

For finer control over session lifecycle:

typescript

const session = await agent.openSession({
  provider: "https://api.inference.xyz",
  cap: "10.00",
});

console.log(session.session_id);   // sess_7f3a9b2c...
console.log(session.locked_usdc);  // "10.000000" — locked in escrow PDA

// ... agent makes many requests using this session ...

const receipt = await agent.closeSession(session.session_id);
console.log(receipt.settled_usdc);  // "3.240000" — actual spend
console.log(receipt.returned_usdc); // "6.760000" — returned to wallet
console.log(receipt.tx_signature);  // Solana settlement signature

Session events

Sessions fire webhook events at key lifecycle points:

Event	When it fires
`session.opened`	Session PDA created, funds locked on-chain
`session.cap_warning`	Running total exceeds 80% of the cap
`session.cap_reached`	Running total hits the cap — session auto-closes
`session.settled`	On-chain settlement confirmed; includes `tx_signature`

Receiving MPP payments

Any MPPCash wallet can act as an MPP payment receiver. If you are building a service that agents pay for, register your wallet as an MPP receiver endpoint. Incoming payments resolve against your wallet's USDC balance.

typescript

import { MPPCash } from "@mppcash/sdk";

// Register your service endpoint as an MPP receiver
const receiver = await client.mpp.registerReceiver({
  account_id: "acct_02k9...",
  endpoint: "https://api.yourservice.xyz",
  price_per_request: "0.005",
  currency: "USDC",
  category: "data",
});

// Your service now responds to unauthenticated requests with HTTP 402
// MPPCash middleware handles challenge generation and payment verification

Payment method: solana-usdc

MPPCash registers as the solana-usdc payment method in the MPP ecosystem. When a service's 402 response lists solana-usdc as an accepted method, MPPCash can fulfill it. The protocol is method-agnostic — MPPCash's role is to be the Solana-native implementation.

Property	Value
Method identifier	`solana-usdc`
Settlement chain	Solana Mainnet
Token	USDC (SPL native)
Session settlement	Single batch Solana transaction
Charge settlement	Per-request Solana transaction