@valeoxrp/x402-xrpl-skill

x402 payments on the XRP Ledger — a skill bundle for AI coding agents plus tiny TypeScript helpers for devs. Accept XRP or RLUSD micropayments via t54.ai's hosted non-custodial facilitator.

For AI agents (Claude Code, Cursor, Codex, etc.)

Install this package and your agent will auto-trigger on XRPL payment tasks — "add x402 to my API on XRPL", "accept RLUSD", "monetize this endpoint in XRP", "build an agent that pays for XRPL APIs".

The agent entry point is SKILL.md. Deeper docs live in references/. Working sellers and buyers live in examples/.

For developers

npm install @valeoxrp/x402-xrpl-skill

Zero runtime dependencies. The package ships a few small helpers plus an optional typed wrapper around the three facilitator endpoints (/supported, /verify, /settle). Actual payer signing, middleware, and transports live in the upstream x402-xrpl and xrpl packages (used by the examples).

Constants and presets

import {
  XRPL_MAINNET,          // "xrpl:0"
  XRPL_TESTNET,          // "xrpl:1"
  XRPL_DEVNET,           // "xrpl:2"
  FACILITATOR_MAINNET_URL,
  TESTNET_FAUCET_URL,
  DEFAULT_SOURCE_TAG,    // 804681468
  RLUSD_CURRENCY_HEX,    // "524C555344000000000000000000000000000000"
  RLUSD_ISSUER_NOTE,
  DROPS_PER_XRP,         // 1_000_000n
  xrpToDrops,
} from "@valeoxrp/x402-xrpl-skill";

const priceInDrops = xrpToDrops("0.01"); // "10000"

Invoice binding (replay protection)

Every XRPL x402 payment must be bound to an invoice ID so it can't be replayed. Two methods are supported; use either one on the payer side, the facilitator checks both.

import {
  invoiceMemoHex,       // Method A: MemoData = HEX(UTF-8(invoiceId))
  invoiceIdSha256,      // Method B: InvoiceID = SHA-256(invoiceId) as hex
  buildInvoiceMemo,     // xrpl.js-shaped Memos array for a Payment tx
} from "@valeoxrp/x402-xrpl-skill";

const memos = buildInvoiceMemo("INV-2026-0001");
const invoiceIdHex = invoiceIdSha256("INV-2026-0001");

Facilitator wrapper

import { x402XrplFacilitator } from "@valeoxrp/x402-xrpl-skill";

const fac = x402XrplFacilitator(); // defaults to t54 mainnet
const { kinds } = await fac.supported();

Constructor takes { url?: string; fetchImpl?: typeof fetch } — override for testnet or to inject a custom fetch.

RLUSD preset

import { RLUSD_CURRENCY_HEX } from "@valeoxrp/x402-xrpl-skill";

const accepted = {
  scheme: "exact",
  network: "xrpl:0",
  asset: RLUSD_CURRENCY_HEX,
  payTo: process.env.PAY_TO!,
  amount: "0.01",
  maxTimeoutSeconds: 600,
  extra: { issuer: process.env.RLUSD_ISSUER! },
};

The issuer is intentionally not hardcoded. Set RLUSD_ISSUER to the current Ripple RLUSD issuing account (confirm at https://ripple.com/rlusd before mainnet use).

What's in the box

x402-xrpl-skill/
├── SKILL.md                       # AI agent entry point
├── README.md                      # this file
├── src/
│   ├── index.ts                   # public exports
│   ├── constants.ts               # networks, URLs, RLUSD preset, drops math
│   ├── facilitator.ts             # typed wrapper around /supported, /verify, /settle
│   ├── invoice.ts                 # memo + InvoiceID binding helpers
│   └── types.ts                   # PaymentRequired, PaymentSignature, PaymentResponse
├── references/
│   ├── quickstart.md              # sellers + buyers in TS and Python
│   ├── scheme.md                  # Exact scheme spec on XRPL (v2 headers)
│   ├── assets.md                  # XRP vs RLUSD vs IOUs, drops math
│   ├── invoice-binding.md         # replay protection, memo vs InvoiceID
│   ├── sentinel.md                # plug into Valeo Sentinel receipts
│   └── troubleshooting.md         # error codes + fixes
└── examples/
    ├── express-seller/            # XRP paid API
    ├── express-seller-rlusd/      # RLUSD paid API
    ├── ts-buyer/                  # x402Fetch client
    └── fastapi-seller/            # Python seller

Links

• Facilitator docs: https://xrpl-x402.t54.ai/docs
• Valeo: https://valeoprotocol.io
• x402 spec: https://x402.org

License

MIT