A practical MPP skill for AI agents on Stellar.
Build paid APIs, agent payment clients, and Stripe-to-Stellar machine payment flows with MPP, Soroban SAC transfers, and optional one-way channels.
Built by ASG Card as a community-facing companion to our earlier Stellar x402 work.
This repo is for builders who want to understand or ship Machine Payments Protocol (MPP) flows on Stellar without starting from a blank page.
One install. Your AI agent learns how to:
- build payment-gated APIs with
WWW-Authenticate: Payment - build agent clients that answer
402 Payment Requiredautomatically - use Soroban SAC transfers for one-time MPP charges
- reason about one-way channels for higher-frequency payments
- adapt an existing Stripe MPP mental model to Stellar MPP
In practical terms, this repo gives the user:
- a reusable AI skill they can install into Codex, Claude Code, Cursor, Windsurf, or Gemini
- a seller example they can run locally
- a buyer example they can run locally
- focused references for charge mode, channel mode, and package choices
- guardrails for replay protection, side-effect safety, and settlement design
MPP on Stellar is still early. Most builders have to piece the flow together from protocol docs, SDK internals, and scattered examples.
This repo compresses that work into something runnable.
Use it if you are:
- building a paid API and want a clean first implementation
- building an agent that should pay for resources automatically
- evaluating whether charge or channel mode is the right fit
- coming from Stripe MPP and need a credible path onto Stellar
- teaching an LLM-powered coding agent how to scaffold these flows correctly
stellar-mpp-payments-skill/
├── .cursorrules # Cursor / Windsurf hook
├── install.sh # One-command installer
├── examples/
│ ├── stellar-mpp-server/ # Seller example: payment-gated API
│ └── stellar-mpp-client/ # Buyer example: automatic 402 payment client
└── stellar-mpp-payments/
├── SKILL.md # Main skill and decision tree
└── references/
├── charge.md # One payment per request
├── channel.md # Off-chain commitment flow
├── packages.md # Package matrix and install guidance
└── stripe-interop.md # Stripe MPP -> Stellar MPP migration notes
- Install the skill.
- Run the server example.
- Run the client example.
- Watch a real
402 -> Payment -> verified responseflow. - Decide whether to keep building with charge mode or move to channel mode.
curl -sSL https://raw.githubusercontent.com/ASGCompute/stellar-mpp-payments-skill/main/install.sh | bashThe installer copies the stellar-mpp-payments skill into Claude Code, Codex, Cursor/Windsurf, or Gemini locations.
git clone https://github.com/ASGCompute/stellar-mpp-payments-skill.git
mkdir -p ~/.claude/skills
cp -r stellar-mpp-payments-skill/stellar-mpp-payments ~/.claude/skills/git clone https://github.com/ASGCompute/stellar-mpp-payments-skill.git
mkdir -p ~/.codex/skills
cp -r stellar-mpp-payments-skill/stellar-mpp-payments ~/.codex/skills/git clone https://github.com/ASGCompute/stellar-mpp-payments-skill.git
cp stellar-mpp-payments-skill/.cursorrules ./
cp -r stellar-mpp-payments-skill/stellar-mpp-payments ./git clone https://github.com/ASGCompute/stellar-mpp-payments-skill.git
mkdir -p ~/.gemini/skills
cp -r stellar-mpp-payments-skill/stellar-mpp-payments ~/.gemini/skills/Two ready-to-run projects live in examples/.
A small Express API that charges 0.01 USDC per request on Stellar testnet.
cd examples/stellar-mpp-server
npm install
npm run devA Node client that catches a 402 challenge, signs the Stellar payment, and retries automatically.
cd examples/stellar-mpp-client
npm install
npm startThe skill teaches a simple decision tree:
User asks about MPP / paid APIs / machine payments on Stellar
│
├─ Are you the SELLER or BUYER?
│ ├─ Seller -> protect an API or action behind payment
│ └─ Buyer -> automatically pay for a resource
│
├─ Which PAYMENT MODE?
│ ├─ Charge -> one on-chain SAC transfer per request
│ └─ Channel -> many off-chain commitments, occasional close
│
├─ Which NETWORK?
│ ├─ Testnet -> demos, pilots, first integrations
│ └─ Public -> production settlement
│
└─ Are you MIGRATING FROM STRIPE MPP?
├─ No -> use normal Stellar MPP setup
└─ Yes -> preserve protocol shape, swap settlement rail
It is a small packaging layer that helps both humans and AI coding agents do the right thing faster:
- the skill tells the model how to reason about the task
- the references keep protocol and implementation choices organized
- the examples give runnable code, not just theory
- the installer makes adoption low-friction
This repo is the MPP companion to the earlier Stellar x402 community asset.
x402-payments-skillteaches x402 on Stellarstellar-mpp-payments-skillteaches MPP on Stellar
The protocol ergonomics overlap, but the implementation model differs:
- x402 centers on x402 challenge/accept flows and facilitator-style settlement
- MPP centers on the
Paymentauth scheme and method-specific credentials - this repo adds explicit guidance for charge vs channel and Stripe-to-Stellar migration
After completing a pilot that combined Stellar settlement, MPP flows, and Stripe-style machine payment concepts, we packaged the useful parts into a public community asset.
This repo is meant to save other teams time:
- start with a working skill instead of blank docs
- see a clean seller/client split
- understand when to choose charge vs channel mode
- avoid obvious replay and side-effect mistakes
Apache-2.0. It stays permissive, but is a better fit for a public developer integration asset because it includes an explicit patent grant.