Open XRPL MPP Stack¶

Hosted docs for the XRPL-first MPP HTTP stack:

xrpl-mpp-core
xrpl-mpp-facilitator
xrpl-mpp-middleware
xrpl-mpp-client
xrpl-mpp-payer

Start Here¶

If you want to see a real payment succeed on XRPL Testnet, go straight to the Testnet XRP quickstart.

That flow uses:

python -m devtools.quickstart to generate reusable Testnet wallets and .env.quickstart
docker compose --env-file .env.quickstart up --build to run the facilitator, merchant, and Redis
docker compose --env-file .env.quickstart --profile demo run --rm buyer to trigger the paid request

The quickstart probes public XRPL Testnet RPC servers and writes the first healthy endpoint into .env.quickstart as XRPL_RPC_URL. Override that selection with XRPL_TESTNET_RPC_URL or python -m devtools.quickstart --xrpl-rpc-url ... when you want to pin a specific provider.

Guides By Goal¶

Understand the stack layout: Architecture Overview
Protect seller routes: Seller Integration
Build or operate a buyer: Buyer Integration
Choose the right environment settings: Deployment Modes
Run XRP, RLUSD, or USDC demos: Run Demo Variants

Package Chooser¶

Pick the package for the role you are building. Most integrators start with xrpl-mpp-middleware on the seller side or xrpl-mpp-client on the buyer side, then add xrpl-mpp-facilitator as the settlement service.

Package	Install	Use when
Core	`pip install xrpl-mpp-core`	You need the shared MPP models, codecs, and XRPL asset helpers directly.
Facilitator	`pip install xrpl-mpp-facilitator`	You are running the FastAPI settlement service behind protected seller routes.
Middleware	`pip install xrpl-mpp-middleware`	You are protecting ASGI or FastAPI routes that should return `402` until paid.
Client	`pip install xrpl-mpp-client`	You are building a buyer that signs XRPL payments and retries MPP challenges automatically.
Payer	`pip install xrpl-mpp-payer`	You want a turnkey buyer CLI, local proxy, receipts, or MCP support for agents.

If you want the shortest path to a working stack, read the middleware guide, the client guide, then run the Testnet XRP quickstart.

Install Commands¶

pip install xrpl-mpp-core
pip install xrpl-mpp-facilitator
pip install xrpl-mpp-middleware
pip install xrpl-mpp-client
pip install xrpl-mpp-payer

Full AI agent support:

pip install "xrpl-mpp-payer[mcp]"
xrpl-mpp skill install
xrpl-mpp mcp
claude mcp add xrpl-mpp-payer -- xrpl-mpp mcp

Comparison Table¶

Package	Runs where	Main entry points	Depends on facilitator	Optional extras
`xrpl-mpp-core`	Shared library code	`PaymentChallenge`, `PaymentCredential`, `PaymentReceipt`, header codecs, XRPL asset helpers	No	None
`xrpl-mpp-facilitator`	Seller infrastructure or service tier	`create_app(...)`, `xrpl_mpp_facilitator.main:app`, `xrpl-mpp-facilitator`	It is the facilitator	None
`xrpl-mpp-middleware`	Seller app	`PaymentMiddlewareASGI`, `require_payment(...)`, `require_session(...)`, `XRPLFacilitatorClient`	Yes	None
`xrpl-mpp-client`	Buyer app or integration test harness	`XRPLPaymentSigner`, `XRPLPaymentTransport`, `wrap_httpx_with_mpp_payment(...)`	Yes, against a protected seller route	None
`xrpl-mpp-payer`	Buyer operator or local agent runtime	`xrpl-mpp`, `pay_with_mpp(...)`, `XRPLPayer`, bundled skill, stdio MCP server	Yes, against a protected seller route	`[mcp]`

Beyond XRP¶

The primary quickstart is XRP on Testnet for the fastest real success path.

When you switch the demo to issued assets, the merchant uses PRICE_* variables and the buyer uses PAYMENT_ASSET. The quickstart wallet cache keeps one shared merchant wallet plus dedicated buyer wallets for XRP, RLUSD, and USDC, so the derived env files can run in parallel without sharing one signing account.

RLUSD Demo Config¶

Generate a derived env file:

python -m devtools.demo_env --asset rlusd

Then restart the stack and rerun the buyer:

docker compose --env-file .env.quickstart.rlusd up --build
docker compose --env-file .env.quickstart.rlusd --profile demo run --rm buyer

Use the RLUSD guide for faucet setup, trustline details, and claim recovery behavior.

USDC Demo Config¶

Generate a derived env file:

python -m devtools.demo_env --asset usdc

Then restart the stack and rerun the buyer:

docker compose --env-file .env.quickstart.usdc up --build
docker compose --env-file .env.quickstart.usdc --profile demo run --rm buyer

Use the USDC guide for the Circle faucet flow and sweep behavior.

Configuration At A Glance¶

The full environment reference lives in Configuration. For the common local stack, the important knobs are:

MY_DESTINATION_ADDRESS for the merchant settlement wallet
FACILITATOR_BEARER_TOKEN for middleware-to-facilitator auth in single_token mode
REDIS_URL for replay protection and session state
MPP_CHALLENGE_SECRET for binding MPP challenges to the protected request
NETWORK_ID, XRPL_NETWORK, and XRPL_RPC_URL for the XRPL network you are targeting
PRICE_* and PAYMENT_ASSET for demo pricing and issued-asset examples

What The Stack Does¶

This MPP-native stack exposes the current facilitator contract:

GET /health
GET /supported
POST /charge
POST /session

The middleware emits WWW-Authenticate: Payment, buyers retry with Authorization: Payment, and successful responses include Payment-Receipt.

The request lifecycle is documented in Payment Flow. The exact wire format is documented in Header Contract. Replay protection, bounded ledger freshness, and session-state behavior are documented in Replay And Freshness. Integration guidance for MPP-native sellers and buyers lives in Seller Integration, Buyer Integration, and MPP HTTP Integration.