Meta

• Author: Facilitator Team
• Requires: Python >=3.11

x402 XRPL Python SDK

This package provides a small, spec‑aligned SDK for working with x402 payments over XRPL in this repository. It is designed to be reusable by both buyer clients (creating PAYMENT-SIGNATURE headers) and seller/resource servers (verifying and settling via a facilitator).

Note: The XRPL exact flow in this repo is the presigned Payment tx blob scheme.

For an overview of the scheme and end-to-end flow, see: app/docs/xrpl-exact/presigned-payment/README.md.

---

Install (PyPI)

Requires Python 3.11+.

pipinstallx402-xrpl

Note: the PyPI name uses a hyphen, but the import name uses an underscore:

importx402_xrpl

---

Quickstart: Buyer Client (requests-style)

If you want the UX of x402_requests(...) (auto-handle 402), use x402_xrpl.clients.requests:

Buyer clients call the protected resource URL and use XRPL RPC plus optional filters. They do not take a facilitator URL.

importrequests
fromxrpl.walletimport Wallet

fromx402_xrpl.clients.requestsimport x402_requests
fromx402_xrpl.clients.baseimport decode_payment_response

XRPL_RPC = "https://s.altnet.rippletest.net:51234/"
RESOURCE_URL = "http://127.0.0.1:8080/xrpl-demo/resource"

wallet = Wallet.from_seed("…demo seed…")

session: requests.Session = x402_requests(
 wallet,
 rpc_url=XRPL_RPC,
 # Optional filters so most users don't write a custom selector:
 network_filter="xrpl:1",
 scheme_filter="exact",
)

resp = session.get(RESOURCE_URL, timeout=180)
print(resp.status_code, resp.text)

if "PAYMENT-RESPONSE" in resp.headers:
 settlement = decode_payment_response(resp.headers["PAYMENT-RESPONSE"])
 print("settled tx:", settlement.get("transaction"))

Quickstart: Protecting a FastAPI Route with require_payment (recommended)

To protect a route (e.g. /ai-news) with XRPL x402 payments using an ergonomic wrapper:

fromfastapiimport FastAPI

fromx402_xrpl.serverimport require_payment

app = FastAPI()

app.middleware("http")(
 require_payment(
 path="/ai-news",
 price="1000", # XRP drops; for IOUs use the XRPL value string (e.g. "1.25")
 pay_to_address="rhaDe3NBxgUSLL12N5Sxpii2xy8vSyXNG6",
 network="xrpl:1",
 asset="XRP",
 facilitator_url="http://127.0.0.1:8011",
 resource="demo:ai-news",
 description="AI news feed (paid)",
 )
)

XRPL SourceTag (analytics)

By default, this SDK issues PaymentRequirements.extra["sourceTag"] = 804681468 and buyer clients will sign XRPL Payment transactions with SourceTag = 804681468 (so XRPL can query/aggregate these payments on-ledger).

To override the tag for your app, pass your own value in extra:

app.middleware("http")(
 require_payment(
 # ...
 extra={"sourceTag": 123},
 )
)

---

IOU notes (non-XRP assets):

• Set reqs.asset to the XRPL currency code (MUST be 3 chars or 40-hex).
• Provide the issuer as reqs.extra["issuer"] (classic address).
• Set reqs.amount to the XRPL issued-currency value string (e.g. "1", "1.25").

For RLUSD, raw payment requirements should use 524C555344000000000000000000000000000000 as reqs.asset and include the issuer in reqs.extra["issuer"].

If you want a human-friendly display string (or an opt-in conversion of a symbol like "RLUSD" into a 40-hex code), use the currency helpers:

fromx402_xrpl.xrpl_currencyimport display_currency_code, resolve_currency_code

asset = "524C555344000000000000000000000000000000"
print(display_currency_code(asset)) # "RLUSD" (best-effort)

# Opt-in convenience (only use if your app has a trusted mapping/intent):
asset_hex = resolve_currency_code("RLUSD", allow_utf8_symbol=True)

Optional X402 Secure / Verifiable Intent

Buyer clients can attach a Verifiable Intent L1-L3 chain through the verifiable_intent_provider seam. When the hosted XRPL Facilitator receives extensions.x402Secure, it calls X402 Secure and Trustline before settlement. Plain XRPL x402 payments without the extension remain on the normal path.

Use RemoteIssuerProvider when the agent cannot hold the Trustline issuer secret. The remote endpoint only issues L1; the SDK still signs L2 with the owner key and L3 with the agent key locally:

fromx402_xrpl.viimport RemoteIssuerProvider, RemoteIssuerSource

provider = RemoteIssuerProvider(
 issuer=RemoteIssuerSource(
 endpoint="https://agent.example/api/vi/issue-l1",
 headers=lambda: {"authorization": f"Bearer {short_lived_issuer_token}"},
 ),
 issue_request={
 "subject": owner_account_ref,
 "ownerPublicJwk": owner_public_jwk,
 "allowedChains": ["xrpl"],
 "allowedAssets": ["XRP"],
 "spendingCeiling": "0.001",
 "validitySeconds": 3600,
 "ownerProof": owner_proof,
 },
 owner_private_jwk=owner_private_jwk,
 owner_kid=owner_kid,
 agent_private_jwk=agent_private_jwk,
 agent_public_jwk=agent_public_jwk,
 agent_kid=agent_kid,
 constraints={"allowed_chains": ["xrpl"], "allowed_assets": ["XRP"], "per_transaction_max": "0.001"},
)

Do not put Trustline API keys, issuer secrets, wallet seeds, owner private keys, or agent private keys into the x402 payment payload.

---

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for aristotle_satoshi from gravatar.com
aristotle_satoshi

Unverified details

These details have not been verified by PyPI

• Download URL: x402_xrpl-0.2.0.tar.gz
• Upload date: Jun 18, 2026
• Size: 34.3 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.2.0 CPython/3.12.9

Hashes for x402_xrpl-0.2.0.tar.gz

Algorithm	Hash digest
SHA256	c2b3f005ab75d812e1f0319c183d06c461c64e75f48de44067a258114d70a55b
MD5	301298dd83cef5675df5c47f67af5af6
BLAKE2b-256	7509ab6e6c27597d98bc7c0f9bbc4d726c3b47852ecedcaa68b7438e37d88418

See more details on using hashes here.

• Download URL: x402_xrpl-0.2.0-py3-none-any.whl
• Upload date: Jun 18, 2026
• Size: 35.8 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.2.0 CPython/3.12.9

Hashes for x402_xrpl-0.2.0-py3-none-any.whl

Algorithm	Hash digest
SHA256	9da9d487ed7c3f589a389068e8f03285212df9b1051a58f0361596177add005a
MD5	331cbbe5e7136ab71c7db0d2e3968f38
BLAKE2b-256	4f22c700b0e08021a2cb2412c9333488916e11865c10d770bb502bf75d5b2dce

See more details on using hashes here.