x402-xrpl

x402-xrpl

TypeScript SDK for x402 v2 payments over XRPL using the exact presigned Payment tx blob scheme from this repository.

This package is intended to mirror the ergonomics of the Python SDK (x402_xrpl/) so developers can easily build:

• Express x402-protected resource servers
• TypeScript buyer clients that automatically handle HTTP 402 Payment Required

Install

npm install x402-xrpl

If you are building a resource server:

npm install express

Express resource server

import express from "express";
import { requirePayment } from "x402-xrpl/express";

const app = express();

app.use(
  requirePayment({
    path: "/ai-news",
    price: "1000", // XRP drops; for IOUs use the XRPL value string (e.g. "1.25")
    payToAddress: "rhaDe3NBxgUSLL12N5Sxpii2xy8vSyXNG6",
    network: "xrpl:1",
    asset: "XRP",
    facilitatorUrl: "http://127.0.0.1:8011",
    resource: "demo:ai-news",
    description: "AI news feed (paid)",
  }),
);

app.get("/ai-news", (_req, res) => res.json({ ok: true }));

app.listen(8080, () => console.log("listening on http://127.0.0.1:8080"));

XRPL SourceTag (analytics)

By default, this SDK issues extra.sourceTag = 804681468 in the 402 accepts[] requirements, 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, set extra.sourceTag:

app.use(
  requirePayment({
    // ...
    extra: { sourceTag: 123 },
  }),
);

IOU notes (non-XRP assets)

• Set asset to a canonical XRPL currency code: 3 chars or 40-hex.
  • A symbol like RLUSD must be provided as its 40-hex currency code, unless you explicitly opt into UTF-8 encoding using the currency helpers.
• Provide the issuer as issuer or extra.issuer.
• Set price to the IOU value string (e.g. "1", "1.25").

Buyer client (fetch wrapper)

x402Fetch implements the standard x402 flow:

• Make request
• If 402 with accepts[], select a PaymentRequirements
• Build PAYMENT-SIGNATURE
• Retry once

import { x402Fetch } from "x402-xrpl";
import { Wallet } from "xrpl";

const wallet = Wallet.fromSeed(process.env.XRPL_SEED!);

const fetchPaid = x402Fetch({
  wallet,
  network: "xrpl:1",
  // Optional: override the default public WS endpoint
  // wsUrl: "wss://s.altnet.rippletest.net:51233",
});

const resp = await fetchPaid("http://127.0.0.1:8080/ai-news");
console.log(resp.status, await resp.text());

Local development

From this package directory:

npm install
npm run build
npm test