MPP Payments - Stellar Edition

MPP Payments - Stellar Edition

Build paid APIs and agent payment clients on Stellar using the Machine Payments Protocol (MPP). Use this skill when the user wants a seller flow, a buyer flow, or a Stripe-to-Stellar MPP adaptation.

Decide Three Things First

1. Role

• Seller: they want to protect an API or action behind payment
• Buyer: they want an agent or app to pay for a resource automatically
• Both: they need the full round trip

2. Payment Mode

• Charge: one on-chain Soroban SAC transfer per paid request
• Channel: many off-chain commitments, occasional on-chain close

Default to charge unless the user clearly needs high request volume or lower marginal latency.

3. Network

• Testnet for demos, tutorials, and prototype flows
• Public for production settlement

Core MPP Flow

Client -> GET /resource
Server -> 402 Payment Required + WWW-Authenticate: Payment ...
Client -> Authorization: Payment ...
Server -> verifies payment on Stellar
Server -> 200 OK + protected result

On Stellar, the payment method is usually:

• a Soroban SAC transfer for charge mode
• a one-way payment channel commitment for channel mode

Quick Start: Seller

Install:

npm install mppx @stellar/stellar-sdk github:stellar-experimental/stellar-mpp-sdk

Minimal server shape:

import { Mppx, stellar } from "stellar-mpp-sdk/server";
import { USDC_SAC_TESTNET } from "stellar-mpp-sdk";

const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY!,
  methods: [
    stellar.charge({
      recipient: process.env.STELLAR_RECIPIENT!,
      currency: USDC_SAC_TESTNET,
      network: "testnet",
    }),
  ],
});

Then wrap the protected route so:

• unpaid requests return 402 plus a Payment challenge
• paid requests are verified before the protected result is returned

See references/charge.md for a working server pattern.

Quick Start: Buyer

Install:

npm install mppx @stellar/stellar-sdk github:stellar-experimental/stellar-mpp-sdk