MPP Protocol Deep-Dive

Technical deep-dive into the Machine Payments Protocol specification and its implementation with Solana settlement.

Overview

The Machine Payments Protocol (MPP) is an open standard for machine-to-machine payments, co-authored by Stripe and Tempo. It enables agents to discover services, receive payment requests, authorize payments, and verify delivery—all without human intervention.

Protocol Specification

HTTP 402 Payment Required

MPP uses the HTTP 402 status code (Payment Required) to initiate payment flows.

RFC 7231 Section 6.5.2:

The 402 (Payment Required) status code is reserved for future use.

MPP formalizes this reserved status code for machine payments.

Request-Response Cycle

Agent                                           Service
  │                                                │
  ├─ GET /api/resource ──────────────────────────►│
  │                                                │
  │◄────── 402 Payment Required ──────────────────┤
  │        { payment_methods, amount, ... }       │
  │                                                │
  ├─ (Authorize payment on Solana) ──────┐        │
  │                                       │        │
  │◄──────────────────────────────────────┘        │
  │  signature: 5Kx...9mQ                          │
  │                                                │
  ├─ GET /api/resource ──────────────────────────►│
  │  MPP-Payment-Credential: solana:sig:5Kx...9mQ  │
  │                                                │
  │◄────── 200 OK ─────────────────────────────────┤
  │        { resource, receipt }                   │
  │                                                │

Payment Request Format

When a client requests a paid resource, the server responds with HTTP 402.

Example request

GET /api/premium/forecast?location=NYC&days=7 HTTP/1.1
Host: api.weather.com
Accept: application/json

402 Response structure

HTTP/1.1 402 Payment Required
Content-Type: application/json
MPP-Version: 1.0
MPP-Payment-ID: payment-abc123
Cache-Control: no-cache

{
  "amount": "5.00",
  "currency": "USD",
  "payment_methods": [
    {
      "type": "crypto",
      "blockchain": "solana",
      "token": "USDC",
      "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "recipient": "DsV...mK9",
      "network": "mainnet-beta",
      "memo": "payment-abc123"
    },
    {
      "type": "crypto",
      "blockchain": "solana",
      "token": "SOL",
      "recipient": "DsV...mK9",
      "network": "mainnet-beta",
      "memo": "payment-abc123"
    }
  ],
  "description": "7-day weather forecast for New York City",
  "expires_at": "2026-04-02T18:30:00Z",
  "metadata": {
    "request_id": "req-xyz789",
    "service_tier": "premium"
  }
}

Required fields

Field

Type

Description

amount

string

Payment amount in specified currency

currency

string

Currency code (USD, EUR, etc.)

payment_methods

array

Available payment methods

description

string

Human-readable payment description

Optional fields

Field

Type

Description

expires_at

string

ISO 8601 timestamp when payment request expires

metadata

object

Additional service-specific data

callback_url

string

Webhook URL for payment confirmation

Payment Methods

MPP supports multiple payment types. MoltMPP implements the crypto type with Solana settlement.

Crypto payment method

{
  "type": "crypto",
  "blockchain": "solana",
  "token": "USDC",
  "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "recipient": "DsVZ3KXEYs5sCq9pLmh7Jtz8UFV5BwqovYQ3H5xJwcZK",
  "network": "mainnet-beta",
  "memo": "payment-abc123"
}

Fields:

blockchain: Target blockchain (solana, ethereum, base, polygon)
token: Token symbol (USDC, SOL, USDT, ETH)
token_address: Token mint/contract address
recipient: Merchant wallet address
network: Network identifier (mainnet-beta, devnet)
memo: Payment identifier for reconciliation

Payment Execution

MoltMPP handles payment execution on Solana.

Transaction construction

import { Transaction, SystemProgram, PublicKey } from '@solana/web3.js'
import { getAssociatedTokenAddress, createTransferInstruction } from '@solana/spl-token'

async function buildPaymentTransaction(
  paymentMethod: MPPCryptoMethod,
  payer: Keypair,
  amountUSDC: number
): Promise<Transaction> {
  const connection = new Connection('https://api.mainnet-beta.solana.com')

  // Get token accounts
  const payerTokenAccount = await getAssociatedTokenAddress(
    new PublicKey(paymentMethod.token_address),
    payer.publicKey
  )

  const recipientTokenAccount = await getAssociatedTokenAddress(
    new PublicKey(paymentMethod.token_address),
    new PublicKey(paymentMethod.recipient)
  )

  // Convert USDC to atomic units (6 decimals)
  const amount = Math.floor(amountUSDC * 1e6)

  // Build transaction
  const tx = new Transaction().add(
    createTransferInstruction(
      payerTokenAccount,
      recipientTokenAccount,
      payer.publicKey,
      amount
    )
  )

  // Add recent blockhash
  tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash
  tx.feePayer = payer.publicKey

  return tx
}

Transaction signing and submission

async function executePayment(
  tx: Transaction,
  payer: Keypair
): Promise<string> {
  const connection = new Connection('https://api.mainnet-beta.solana.com')

  // Sign transaction
  tx.sign(payer)

  // Submit to network
  const signature = await connection.sendRawTransaction(tx.serialize())

  // Wait for confirmation
  await connection.confirmTransaction(signature, 'finalized')

  return signature
}

Payment Credentials

After payment execution, the agent provides proof of payment to the service.

Credential format

GET /api/premium/forecast?location=NYC&days=7 HTTP/1.1
Host: api.weather.com
MPP-Payment-Credential: solana:signature:5KxQr...9mQ
MPP-Payment-ID: payment-abc123

Credential structure: {blockchain}:{type}:{value}

Examples:

solana:signature:5KxQr...9mQ
ethereum:txhash:0xabc...def
base:txhash:0x123...456

Service verification

Service verifies payment on-chain before delivering resource:

async function verifyPayment(
  credential: string,
  paymentMethod: MPPCryptoMethod,
  expectedAmount: number
): Promise<boolean> {
  const [blockchain, type, value] = credential.split(':')

  if (blockchain !== 'solana' || type !== 'signature') {
    throw new Error('Unsupported credential type')
  }

  const connection = new Connection('https://api.mainnet-beta.solana.com')

  // Fetch transaction
  const tx = await connection.getTransaction(value, {
    maxSupportedTransactionVersion: 0
  })

  if (!tx) return false

  // Verify transaction details
  const instruction = tx.transaction.message.instructions[0]

  // Parse transfer instruction
  // Verify recipient matches payment method
  // Verify amount matches expected amount
  // Verify transaction is finalized

  return true  // Simplified
}

Resource Delivery

Upon successful payment verification, service delivers resource with receipt.

Response with receipt

HTTP/1.1 200 OK
Content-Type: application/json
MPP-Receipt: eyJwYXltZW50X2lkIjoicGF5bWVudC1hYmMxMjMiLCJhbW91bnQiOiI1LjAwIi...
MPP-Payment-ID: payment-abc123

{
  "forecast": {
    "location": "New York City",
    "days": 7,
    "data": [...]
  },
  "payment_confirmed": true,
  "payment_details": {
    "amount_paid": "5.00",
    "currency": "USD",
    "blockchain_signature": "5KxQr...9mQ",
    "timestamp": "2026-04-02T15:30:00Z"
  }
}

Receipt structure

Receipt is a signed proof of delivery:

{
  "payment_id": "payment-abc123",
  "amount": "5.00",
  "currency": "USD",
  "blockchain": "solana",
  "signature": "5KxQr...9mQ",
  "resource_hash": "sha256:abc...def",
  "timestamp": "2026-04-02T15:30:00Z",
  "merchant_signature": "3Nx...8pQ"
}

merchant_signature: Cryptographic signature from merchant proving delivery

Receipt verification

Agent verifies receipt authenticity:

import * as nacl from 'tweetnacl'
import * as bs58 from 'bs58'

function verifyReceipt(
  receipt: MPPReceipt,
  merchantPublicKey: PublicKey
): boolean {
  // Reconstruct message
  const message = JSON.stringify({
    payment_id: receipt.payment_id,
    amount: receipt.amount,
    timestamp: receipt.timestamp,
    resource_hash: receipt.resource_hash
  })

  // Verify signature
  const messageBytes = new TextEncoder().encode(message)
  const signatureBytes = bs58.decode(receipt.merchant_signature)

  return nacl.sign.detached.verify(
    messageBytes,
    signatureBytes,
    merchantPublicKey.toBytes()
  )
}

Error Handling

MPP defines standard error responses.

Payment errors

Insufficient payment:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": "payment_insufficient",
  "message": "Payment of 3.00 USD received, but 5.00 USD required",
  "amount_received": "3.00",
  "amount_required": "5.00"
}

Expired payment request:

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "payment_expired",
  "message": "Payment request expired at 2026-04-02T18:30:00Z",
  "expires_at": "2026-04-02T18:30:00Z"
}

Invalid credential:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "invalid_credential",
  "message": "Payment credential could not be verified on blockchain",
  "credential": "solana:signature:invalid..."
}

Service errors

Service unavailable:

HTTP/1.1 503 Service Unavailable
Retry-After: 60

{
  "error": "service_unavailable",
  "message": "Payment processing temporarily unavailable",
  "retry_after": 60
}

Version Negotiation

MPP supports version negotiation via headers.

Client specifies version

GET /api/resource HTTP/1.1
Host: api.example.com
MPP-Version: 1.0

Server responds with supported version

HTTP/1.1 402 Payment Required
MPP-Version: 1.0
MPP-Supported-Versions: 1.0, 1.1

Version compatibility

MoltMPP supports MPP v1.0. Future versions will maintain backward compatibility.

Extensions

MPP allows protocol extensions via custom headers.

Escrow extension

MoltMPP implements escrow for proof of delivery:

HTTP/1.1 402 Payment Required
MPP-Version: 1.0
MPP-Extension-Escrow: enabled
MPP-Escrow-Program: moltmpp-v1

{
  "amount": "5.00",
  "payment_methods": [...],
  "escrow": {
    "enabled": true,
    "program": "moltmpp-settlement-v1",
    "timeout": 3600
  }
}

Agent creates escrow account instead of direct transfer.

Subscription extension

Future support for recurring payments:

MPP-Extension-Subscription: enabled

{
  "amount": "10.00",
  "payment_methods": [...],
  "subscription": {
    "interval": "monthly",
    "duration": 12
  }
}

Security Considerations

Payment replay prevention

Services must track used payment credentials:

class PaymentTracker {
  private usedCredentials: Set<string>

  isUsed(credential: string): boolean {
    return this.usedCredentials.has(credential)
  }

  markUsed(credential: string) {
    this.usedCredentials.add(credential)
  }
}

Amount verification

Always verify on-chain amount matches requested amount:

function verifyAmount(
  onChainAmount: number,
  requestedAmount: number,
  tolerance: number = 0.01  // 1% tolerance
): boolean {
  const diff = Math.abs(onChainAmount - requestedAmount)
  return diff / requestedAmount <= tolerance
}

Blockchain confirmation

Wait for finalized confirmation before delivering resources:

await connection.confirmTransaction(signature, 'finalized')

Solana confirmation levels:

processed: Transaction included in block
confirmed: Block confirmed by cluster
finalized: Block finalized (irreversible)

Use finalized for payment verification.

Implementation Checklist

For services implementing MPP with Solana:

Next Steps

OpenClaw Integration: Build agents using MPP
Service Discovery: Find MPP-enabled services
Security: Production security practices

Resources

MPP Specification: mpp.dev/spec
Stripe MPP Docs: stripe.com/docs/machine-payments
Solana Docs: docs.solana.com
Discord: discord.gg/moltmpp - #protocol-discussion

PreviousSolana Wallet Setup NextAPI Reference

Last updated 1 hour ago

Was this helpful?

Good morning

hashtagOverview

hashtagProtocol Specification

hashtagHTTP 402 Payment Required

hashtagRequest-Response Cycle

hashtagPayment Request Format

hashtagExample request

hashtag402 Response structure

hashtagRequired fields

hashtagOptional fields

hashtagPayment Methods

hashtagCrypto payment method

hashtagPayment Execution

hashtagTransaction construction

hashtagTransaction signing and submission

hashtagPayment Credentials

hashtagCredential format

hashtagService verification

hashtagResource Delivery

hashtagResponse with receipt

hashtagReceipt structure

hashtagReceipt verification

hashtagError Handling

hashtagPayment errors

hashtagService errors

hashtagVersion Negotiation

hashtagClient specifies version

hashtagServer responds with supported version

hashtagVersion compatibility

hashtagExtensions

hashtagEscrow extension

hashtagSubscription extension

hashtagSecurity Considerations

hashtagPayment replay prevention

hashtagAmount verification

hashtagBlockchain confirmation

hashtagImplementation Checklist

hashtagNext Steps

hashtagResources

Overview

Protocol Specification

HTTP 402 Payment Required

Request-Response Cycle

Payment Request Format

Example request

402 Response structure

Required fields

Optional fields

Payment Methods

Crypto payment method

Payment Execution

Transaction construction

Transaction signing and submission

Payment Credentials

Credential format

Service verification

Resource Delivery

Response with receipt

Receipt structure

Receipt verification

Error Handling

Payment errors

Service errors

Version Negotiation

Client specifies version

Server responds with supported version

Version compatibility

Extensions

Escrow extension

Subscription extension

Security Considerations

Payment replay prevention

Amount verification

Blockchain confirmation

Implementation Checklist

Next Steps

Resources