docs: add MPP on Stellar documentation by sagpatil · Pull Request #2327 · stellar/stellar-docs

sagpatil · 2026-03-26T02:26:18Z

Summary

Adds documentation for the Machine Payments Protocol (MPP) on Stellar, mirroring the existing x402 docs at docs/build/apps/x402/.

MPP is an HTTP-native payment protocol that uses the 402 Payment Required status code for machine-to-machine payments. The Stellar implementation via stellar-mpp-sdk settles payments directly on-chain via Soroban SAC transfers — no external facilitator needed.

Files added

File	Description
`docs/build/apps/mpp/_category_.json`	Docusaurus sidebar config
`docs/build/apps/mpp/README.mdx`	Overview: what is MPP, charge vs channel modes, install, examples, learn more
`docs/build/apps/mpp/quickstart-guide.mdx`	Step-by-step server + client tutorial with testnet wallet setup and fee sponsorship option
`docs/build/apps/mpp/channel-guide.mdx`	Off-chain payment channel guide: deploy channel, open, make payments, close and settle

Key differences from x402

No external facilitator — the server verifies and broadcasts directly
Two payment modes: charge (per-request on-chain) and channel (off-chain cumulative commitments)
Optional feePayer sponsored path: client signs only Soroban auth entries; server rebuilds and broadcasts

Adds documentation for the Machine Payments Protocol (MPP) on Stellar, mirroring the existing x402 docs structure at docs/build/apps/x402/. Files added: - docs/build/apps/mpp/_category_.json — Docusaurus sidebar config - docs/build/apps/mpp/README.mdx — Overview: what is MPP, charge vs channel modes, install, examples - docs/build/apps/mpp/quickstart-guide.mdx — Step-by-step server + client tutorial with fee sponsorship - docs/build/apps/mpp/channel-guide.mdx — Off-chain payment channel guide (open, pay, close) MPP uses stellar-mpp-sdk for direct on-chain settlement (no external facilitator), supporting both one-time charge payments and high-frequency off-chain channel commitments.

Copilot

Pull request overview

Adds a new “MPP on Stellar” documentation section under docs/build/apps/mpp/, mirroring the existing x402 docs structure, to explain how to build paid HTTP APIs using MPP with on-chain (charge) and off-chain (channel) settlement on Stellar.

Changes:

Adds an MPP overview page (README.mdx) describing MPP, charge vs channel modes, and links to examples/resources.
Adds a step-by-step quickstart for charge mode with Node.js/Express server + client (quickstart-guide.mdx).
Adds a channel-mode guide including channel server/client setup and settlement/close flow (channel-guide.mdx).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
docs/build/apps/mpp/category.json	Creates the Docusaurus category for the new MPP docs section.
docs/build/apps/mpp/README.mdx	Introduces MPP on Stellar and links to key resources and examples.
docs/build/apps/mpp/quickstart-guide.mdx	Provides a charge-mode quickstart with server/client examples and optional fee sponsorship.
docs/build/apps/mpp/channel-guide.mdx	Documents channel mode flows, setup, and closing/settlement guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-26T02:29:42Z

+      currency: USDC_SAC_TESTNET,
+      network: 'testnet',
+      feePayer: Keypair.fromSecret(process.env.FEE_PAYER_SECRET), // pays tx fees
+    }),


In the sponsored fees snippet, Keypair.fromSecret(process.env.FEE_PAYER_SECRET) will throw if FEE_PAYER_SECRET is unset/empty. For a copy/paste-ready example, add a small guard (similar to the STELLAR_RECIPIENT check above) or show how to export/set FEE_PAYER_SECRET before running.

Copilot · 2026-03-26T02:29:43Z

+  | 402 Payment Required         |
+  | (channel: C..., amount: 0.1) |
+  |<-----------------------------|
+  |                              |
+  | Sign commitment off-chain    |
+  | (cumulative: 0.1 XLM)        |
+  |----------------------------->|


This guide mixes USDC and XLM in the channel flow description (e.g., prerequisites mention an XLM or USDC deposit, but the sequence diagram and pricing comment label commitments as XLM). Since the commitment amount is denominated in the channel’s funded token, consider picking one token for the worked example (e.g., USDC) or explicitly stating that the units follow the channel deposit asset.

Copilot · 2026-03-26T02:29:43Z

+const mppx = Mppx.create({
+  secretKey: process.env.MPP_SECRET_KEY ?? 'my-channel-secret',
+  methods: [
+    stellar.channel({


This server example also defaults secretKey to a hard-coded value ('my-channel-secret'). To avoid encouraging insecure deployments, prefer requiring MPP_SECRET_KEY to be set (or clearly label the fallback as local-only and not suitable for production).

stellar-jenkins-ci · 2026-03-26T02:36:42Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

stellar-jenkins-ci · 2026-03-27T03:18:36Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

stellar-jenkins-ci · 2026-03-30T20:39:14Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

stellar-jenkins-ci · 2026-03-30T20:46:33Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

stellar-jenkins-ci · 2026-03-30T21:17:41Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

marcelosalloum

LGTM!

💡 Now that we have both MPP and x402, we should nest them under the same "Agentic Payments" umbrella.

marcelosalloum

Some improvements

marcelosalloum · 2026-03-30T23:38:31Z

+```
+Client (Funder)           Server (Recipient)
+  |                              |
+  | [Deploy channel contract     |
+  |  with commitment key + USDC  |
+  |  deposit on-chain]           |
+  |                              |
+  | GET /resource                |
+  |----------------------------->|
+  |                              |
+  | 402 Payment Required         |
+  | (channel: C..., amount: 0.1) |
+  |<-----------------------------|
+  |                              |
+  | Sign commitment off-chain    |
+  | (cumulative: 0.1 USDC)       |
+  |----------------------------->|
+  |                              |
+  | Verify ed25519 sig, 200 OK   |
+  |<-----------------------------|
+  |                              |
+  | GET /resource                |
+  |----------------------------->|
+  |                              |
+  | 402 (cumulative: 0.1 USDC)   |
+  |<-----------------------------|
+  |                              |
+  | Sign commitment              |
+  | (cumulative: 0.2 USDC)       |
+  |----------------------------->|
+  |                              |
+  | Verify, 200 OK               |
+  |<-----------------------------|
+  |                              |
+  | [Server closes channel       |
+  |  when convenient to settle]  |
+```


This flow should cover interactions with the Stellar blockchain

marcelosalloum · 2026-03-30T23:39:27Z

Why is this file called quickstart-guide? It should be called charge-guide

Can we additionally add a flowchart here, like what we have in the channel guide

Great points, updating!

github-actions · 2026-03-31T01:23:52Z

Warning

This change removes routes. The diff of routes is below. Please verify that these changes to the routes are intentional and that redirects are in place if needed. Redirects can be added to nginx/includes/redirects.conf.

diff --git a/routes.txt b/routes.txt
index b6a0cd2e..038abe92 100644
--- a/routes.txt
+++ b/routes.txt
@@ -30,6 +30,10 @@
 /docs/build/apps/ingest-sdk
 /docs/build/apps/ingest-sdk/ingestion-pipeline-code
 /docs/build/apps/ingest-sdk/overview
+/docs/build/agentic-payments
+/docs/build/agentic-payments/mpp
+/docs/build/agentic-payments/mpp/channel-guide
+/docs/build/agentic-payments/mpp/charge-guide
 /docs/build/apps/overview
 /docs/build/apps/swift-payment-app
 /docs/build/apps/wallet
@@ -42,9 +46,9 @@
 /docs/build/apps/wallet/sep6
 /docs/build/apps/wallet/sep7
 /docs/build/apps/wallet/stellar
-/docs/build/apps/x402
-/docs/build/apps/x402/built-on-stellar
-/docs/build/apps/x402/quickstart-guide
+/docs/build/agentic-payments/x402
+/docs/build/agentic-payments/x402/built-on-stellar
+/docs/build/agentic-payments/x402/quickstart-guide
 /docs/build/apps/zk
 /docs/build/guides
 /docs/build/guides/archival

github-actions · 2026-03-31T01:28:25Z

Warning

This change removes routes. The diff of routes is below. Please verify that these changes to the routes are intentional and that redirects are in place if needed. Redirects can be added to nginx/includes/redirects.conf.

diff --git a/routes.txt b/routes.txt
index b6a0cd2e..038abe92 100644
--- a/routes.txt
+++ b/routes.txt
@@ -30,6 +30,10 @@
 /docs/build/apps/ingest-sdk
 /docs/build/apps/ingest-sdk/ingestion-pipeline-code
 /docs/build/apps/ingest-sdk/overview
+/docs/build/agentic-payments
+/docs/build/agentic-payments/mpp
+/docs/build/agentic-payments/mpp/channel-guide
+/docs/build/agentic-payments/mpp/charge-guide
 /docs/build/apps/overview
 /docs/build/apps/swift-payment-app
 /docs/build/apps/wallet
@@ -42,9 +46,9 @@
 /docs/build/apps/wallet/sep6
 /docs/build/apps/wallet/sep7
 /docs/build/apps/wallet/stellar
-/docs/build/apps/x402
-/docs/build/apps/x402/built-on-stellar
-/docs/build/apps/x402/quickstart-guide
+/docs/build/agentic-payments/x402
+/docs/build/agentic-payments/x402/built-on-stellar
+/docs/build/agentic-payments/x402/quickstart-guide
 /docs/build/apps/zk
 /docs/build/guides
 /docs/build/guides/archival

github-actions · 2026-03-31T01:30:05Z

Warning

This change removes routes. The diff of routes is below. Please verify that these changes to the routes are intentional and that redirects are in place if needed. Redirects can be added to nginx/includes/redirects.conf.

diff --git a/routes.txt b/routes.txt
index b6a0cd2e..038abe92 100644
--- a/routes.txt
+++ b/routes.txt
@@ -30,6 +30,10 @@
 /docs/build/apps/ingest-sdk
 /docs/build/apps/ingest-sdk/ingestion-pipeline-code
 /docs/build/apps/ingest-sdk/overview
+/docs/build/agentic-payments
+/docs/build/agentic-payments/mpp
+/docs/build/agentic-payments/mpp/channel-guide
+/docs/build/agentic-payments/mpp/charge-guide
 /docs/build/apps/overview
 /docs/build/apps/swift-payment-app
 /docs/build/apps/wallet
@@ -42,9 +46,9 @@
 /docs/build/apps/wallet/sep6
 /docs/build/apps/wallet/sep7
 /docs/build/apps/wallet/stellar
-/docs/build/apps/x402
-/docs/build/apps/x402/built-on-stellar
-/docs/build/apps/x402/quickstart-guide
+/docs/build/agentic-payments/x402
+/docs/build/agentic-payments/x402/built-on-stellar
+/docs/build/agentic-payments/x402/quickstart-guide
 /docs/build/apps/zk
 /docs/build/guides
 /docs/build/guides/archival

stellar-jenkins-ci · 2026-03-31T01:36:25Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

stellar-jenkins-ci · 2026-03-31T01:42:10Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

github-actions · 2026-03-31T01:43:49Z

Warning

This change removes routes. The diff of routes is below. Please verify that these changes to the routes are intentional and that redirects are in place if needed. Redirects can be added to nginx/includes/redirects.conf.

diff --git a/routes.txt b/routes.txt
index b6a0cd2e..2c19c02e 100644
--- a/routes.txt
+++ b/routes.txt
@@ -2,6 +2,13 @@
 /404.html
 /docs
 /docs/build
+/docs/build/agentic-payments
+/docs/build/agentic-payments/mpp
+/docs/build/agentic-payments/mpp/channel-guide
+/docs/build/agentic-payments/mpp/charge-guide
+/docs/build/agentic-payments/x402
+/docs/build/agentic-payments/x402/built-on-stellar
+/docs/build/agentic-payments/x402/quickstart-guide
 /docs/build/apps
 /docs/build/apps/application-design-considerations
 /docs/build/apps/dapp-frontend
@@ -42,9 +49,6 @@
 /docs/build/apps/wallet/sep6
 /docs/build/apps/wallet/sep7
 /docs/build/apps/wallet/stellar
-/docs/build/apps/x402
-/docs/build/apps/x402/built-on-stellar
-/docs/build/apps/x402/quickstart-guide
 /docs/build/apps/zk
 /docs/build/guides
 /docs/build/guides/archival

stellar-jenkins-ci · 2026-03-31T01:44:09Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

oceans404 · 2026-03-31T01:50:58Z

Docs Previews

stellar-jenkins-ci · 2026-03-31T01:54:14Z

Preview is available here:
http://developers-pr2327.previews.kube001.services.stellar-ops.com

Copilot AI review requested due to automatic review settings March 26, 2026 02:26

Copilot started reviewing on behalf of sagpatil March 26, 2026 02:26 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

docs: address mpp review feedback

420664a

oceans404 added 2 commits March 30, 2026 13:27

update MPP docs with new package names, imports, and terminology

2cf32c2

fix: add MPP routes to routes.txt

04b8064

sagpatil requested review from marcelosalloum and oceans404 March 30, 2026 20:49

dependency fix

f6e37fb

oceans404 approved these changes Mar 30, 2026

View reviewed changes

marcelosalloum approved these changes Mar 30, 2026

View reviewed changes

marcelosalloum reviewed Mar 30, 2026

View reviewed changes

add agentic payments section

834b4ba

add nginx x402 redirects

9184238

no changes to zk

8044c9e

update routes

2de082e

sagpatil merged commit b057ae6 into main Mar 31, 2026
10 checks passed

sagpatil deleted the docs/add-mpp branch March 31, 2026 15:20

zachfedor pushed a commit to zachfedor/stellar-docs that referenced this pull request Jun 18, 2026

docs: add MPP on Stellar documentation (stellar#2327)

b4bc594

Uh oh!

Conversation

sagpatil commented Mar 26, 2026

Summary

Files added

Key differences from x402

Related

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

stellar-jenkins-ci Bot commented Mar 26, 2026

Uh oh!

stellar-jenkins-ci Bot commented Mar 27, 2026

Uh oh!

stellar-jenkins-ci Bot commented Mar 30, 2026

Uh oh!

stellar-jenkins-ci Bot commented Mar 30, 2026

Uh oh!

stellar-jenkins-ci Bot commented Mar 30, 2026

Uh oh!

marcelosalloum left a comment

Choose a reason for hiding this comment

Uh oh!

marcelosalloum left a comment

Choose a reason for hiding this comment

Uh oh!

marcelosalloum Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

marcelosalloum Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

marcelosalloum Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

oceans404 Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

oceans404 Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

stellar-jenkins-ci Bot commented Mar 31, 2026

Uh oh!

stellar-jenkins-ci Bot commented Mar 31, 2026

Uh oh!

github-actions Bot commented Mar 31, 2026

Uh oh!

stellar-jenkins-ci Bot commented Mar 31, 2026

Uh oh!

oceans404 commented Mar 31, 2026

Docs Previews

Uh oh!

stellar-jenkins-ci Bot commented Mar 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels