P2P Payment Architecture

The Machine Payments Protocol (MPP) operates on a completely non-custodial, Peer-to-Peer (P2P) architecture. This means MPP never holds, escrows, or touches the funds of providers or consumers. All payments happen directly on the Solana blockchain in real time.

System Overview

Every API interaction on the MPP platform follows a strict, verifiable lifecycle involving three parties: the Consumer (the caller), the MPP Gateway (our proxy), and the Provider (the API owner). Here is the complete flow from start to finish.

Step-by-Step Request Lifecycle

Let's trace a complete request through the system. In this example, a Consumer wants to call the defi-sentiment API, which costs 1.0 USDC per request.

POST https://api.mpp.dev/v1/gateway/defi-sentiment
Content-Type: application/json

{"prompt": "Is Solana trending bullish today?"}

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment
  address="9eW9z...ProviderWallet",
  amount="1.0",
  currency="USDC",
  fee_wallet="MPP1...PlatformWallet",
  fee_percent="2%"

{"error": "Payment Required"}

import { Transaction, SystemProgram, PublicKey } from "@solana/web3.js";

const totalAmount = 1.0 * 1e9; // 1.0 SOL in lamports (or use token decimals for USDC)
const platformFee = totalAmount * 0.02;  // 2%
const providerAmount = totalAmount - platformFee; // 98%

const transaction = new Transaction().add(
  // Transfer 98% to Provider
  SystemProgram.transfer({
    fromPubkey: consumerWallet.publicKey,
    toPubkey: new PublicKey("9eW9z...ProviderWallet"),
    lamports: providerAmount,
  }),
  // Transfer 2% to MPP Platform Fee Wallet
  SystemProgram.transfer({
    fromPubkey: consumerWallet.publicKey,
    toPubkey: new PublicKey("MPP1...PlatformWallet"),
    lamports: platformFee,
  })
);

const signature = await sendAndConfirmTransaction(connection, transaction, [consumerWallet]);
// → "5gPz8...txSignature"

POST https://api.mpp.dev/v1/gateway/defi-sentiment
Content-Type: application/json
Authorization: Payment signature=5gPz8...txSignature

{"prompt": "Is Solana trending bullish today?"}

Security Considerations

Replay Attack Prevention

A Replay Attack occurs when a malicious user captures a valid transaction signature and re-uses it to call the API multiple times without paying again.

The MPP Gateway prevents this with a global Signature Cache. Every successfully consumed signature is stored. If the same signature appears in a second request, the Gateway returns a 409 Conflict: Signature already consumed error immediately.

Protecting the Upstream URL

Because your Upstream URL is a public web server, a bad actor could attempt to bypass the MPP Gateway entirely and call your server directly for free. To mitigate this:

• Verify the presence of the X-MPP-Verified-Payment: true header on all incoming requests to your server.
• Maintain a strict IP allowlist of MPP Gateway egress IPs.
• For maximum security, use mutual TLS (mTLS) between the Gateway and your upstream server.

Fee Distribution Summary

Every payment is split automatically and verifiably on-chain:

Why P2P Instead of Smart Contracts?

Many decentralized payment systems use on-chain smart contracts (e.g., escrow contracts on Ethereum) to enforce payment rules. MPP deliberately avoids smart contracts for the following reasons: