Skip to content

Guided Quickstart: Testnet XRP

This is the fastest real end-to-end path:

  1. generate or reuse XRPL Testnet wallets
  2. write a local .env.quickstart file
  3. run the facilitator and merchant with Docker Compose
  4. have the buyer example pay for a protected route with XRP

Prerequisites

  • Python 3.12
  • Docker Desktop or Docker Engine with Compose
  • outbound network access to XRPL Testnet

Setup

Create a virtualenv and install the repo dependencies:

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

Generate the quickstart env file:

python -m devtools.quickstart

If you need to pin the Testnet RPC used during wallet generation, either export XRPL_TESTNET_RPC_URL first or pass --xrpl-rpc-url https://your-testnet-rpc.example/.

That command:

  • creates or reuses a cached shared merchant wallet plus dedicated buyer wallets for XRP, RLUSD, and USDC
  • writes .env.quickstart
  • auto-selects a healthy public XRPL Testnet RPC and writes it into .env.quickstart as XRPL_RPC_URL
  • prints the merchant address, the XRP buyer address, redacted secret previews, and the exact next commands

The generated file contains secrets and is ignored by git. Do not commit it.

Run The Stack

Start the facilitator, merchant, and Redis:

docker compose --env-file .env.quickstart up --build

In a second terminal, trigger the paid request:

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

Expected output:

status=200
{"message":"premium content unlocked", ...}

Full AI Agent Support

Once the quickstart stack is running, you can use the payer package as a local agent bridge:

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

Claude Desktop can register it directly:

claude mcp add xrpl-mpp-payer -- xrpl-mpp mcp

That lets local agents call pay_url directly instead of shelling out to a buyer script.

What Happened

  • the merchant challenged the first request with 402 Payment Required
  • the buyer decoded WWW-Authenticate: Payment, signed an exact XRP payment, and retried once
  • the facilitator verified and settled the presigned transaction
  • the middleware injected request.state.mpp_payment and returned the protected content

Useful Files

  • .env.quickstart
  • .live-test-wallets/xrpl-testnet-wallets.json
  • examples/merchant_fastapi/app.py
  • examples/buyer_httpx.py

Clean Up

Stop the stack with Ctrl+C, or run:

docker compose --env-file .env.quickstart down

You can reuse .env.quickstart and the cached wallets the next time you run the demo. The derived .env.quickstart.rlusd and .env.quickstart.usdc files will each use their own buyer wallet seed, so the three demo variants can sign in parallel without sequence-number contention.

Next Steps

  • Generate .env.quickstart.rlusd with python -m devtools.demo_env --asset rlusd
  • Generate .env.quickstart.usdc with python -m devtools.demo_env --asset usdc
  • Follow the RLUSD guide
  • Follow the USDC guide
  • Read Payment Flow