FacilitatorQuickstartXRPL

Quickstart Guide

Get up and running with x402 on XRPL in minutes.

Prerequisites

  • • Python 3.9+
  • • An XRPL wallet (you can create one on XRPL Testnet Faucet)
  • • Basic understanding of HTTP APIs

Set up a FastAPI server that accepts x402 payments. When clients request your protected endpoints, they'll automatically be prompted to pay before accessing the resource.

Step 1: Install dependencies

pip install fastapi uvicorn x402-xrpl python-dotenv

Step 2: Configure environment

Create a .env file with your configuration:

XRPL_FACILITATOR_URL=https://xrpl-facilitator-testnet.t54.ai
XRPL_PAY_TO=rYourWalletAddress  # your wallet address to receive funds
XRPL_PRICE_DROPS=1000           # price in drops (1 XRP = 1,000,000 drops)

Tip: Get a testnet wallet from the XRPL Testnet Faucet

Step 3: Create your server

Create a file called server.py:

server.py
import os
from dotenv import load_dotenv
from fastapi import FastAPI
from x402_xrpl.server import require_payment

load_dotenv()

app = FastAPI()

# Configure the x402 middleware
# This protects specific paths and handles the 402 Payment Required flow.
app.middleware("http")(
    require_payment(
        path="/hello",  # Protect only the /hello endpoint
        price=os.getenv("XRPL_PRICE_DROPS", "1000"),
        pay_to_address=os.getenv("XRPL_PAY_TO"),
        facilitator_url=os.getenv("XRPL_FACILITATOR_URL"),
        network="xrpl:1",  # xrpl:1 = Testnet, xrpl:0 = Mainnet
        asset="XRP",
        description="A paid hello world endpoint",
    )
)

# Protected endpoint - requires payment
@app.get("/hello")
async def hello():
    return {"message": "Hello World! Thanks for the payment."}

# Free endpoint - no payment required
@app.get("/health")
async def health():
    return {"status": "ok"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Step 4: Run the server

python server.py

Try visiting http://localhost:8000/hello. You'll receive a 402 Payment Required response with payment instructions.

Next Step

Learn more about the XRPL Exact payment scheme and how payments are verified and settled.

Go to XRPL Exact Scheme