@erudite-intelligence/x402-xrp

x402 Payment Protocol V2 — XRP Ledger Network Plugin

The first x402 V2 implementation for XRP Ledger (XRPL), enabling signed Payment transactions for AI agents and web services.

Built by Erudite Intelligence LLC.

Overview

This package implements the exact payment scheme for XRP Ledger using native XRP Payment transactions. It provides client-side payment creation, server-side verification with 14 security checks, and settlement via transaction submission.

Key features:

• Native XRP payments (drops as the atomic unit, 1 XRP = 1,000,000 drops)
• Signed transaction blobs — strongest trust model (facilitator cannot modify any parameter)
• Client pays transaction fees (embedded in the signed transaction)
• Supports mainnet, testnet, and devnet
• CAIP-2 network identifiers (xrpl:0, xrpl:1, xrpl:2)
• JSON-RPC API client (Ripple public nodes)
• 127 tests across 3 test suites including adversarial and round-trip testing
• Ed25519 and secp256k1 signature verification

Payment support: This package supports native XRP payments only. IOU (issued currency) payments are not supported.

Installation

npm install @erudite-intelligence/x402-xrp

Quick Start

Client: Create a Payment

import { createPayment, encodePaymentHeader } from "@erudite-intelligence/x402-xrp";

const payment = await createPayment({
  seed: "sEdT...",           // XRP seed (s...)
  to: "rMerchantAddr...",    // Merchant's classic address
  amount: "1000000",         // 1 XRP in drops
  network: "testnet",
});

// Send as X-PAYMENT header
const header = encodePaymentHeader(payment);
fetch(resourceUrl, {
  headers: { "X-PAYMENT": header },
});

Client: Pay from a 402 Response

import { payFor, encodePaymentHeader } from "@erudite-intelligence/x402-xrp";

const paymentRequired = await response.json();

const payment = await payFor(paymentRequired, "sEdT...");
if (payment) {
  const header = encodePaymentHeader(payment);
  // Retry the request with payment
}

Server: Verify a Payment

import { verifyPayment } from "@erudite-intelligence/x402-xrp";

const result = await verifyPayment(
  paymentPayload,        // from X-PAYMENT header
  "rMerchantAddr...",    // expected payTo
  "1000000",             // expected amount in drops
  "xrpl:1",              // CAIP-2 network (testnet)
  { network: "testnet" },
);

if (result.isValid) {
  console.log(`Payment verified from ${result.payer}`);
  console.log(`Amount: ${result.details.amount} drops`);
  console.log(`Fee: ${result.details.fee} drops`);
} else {
  console.log(`Rejected: ${result.invalidReason} - ${result.invalidMessage}`);
}

Server: Settle (Submit) a Payment

import { settlePayment } from "@erudite-intelligence/x402-xrp";

const result = await settlePayment(
  paymentPayload,
  "xrpl:1",
  { network: "testnet" },
);

if (result.success) {
  console.log(`Settled: ${result.transaction}`);
} else {
  console.log(`Failed: ${result.errorReason}`);
}

Register with x402 Facilitator

import { registerExactXrpScheme } from "@erudite-intelligence/x402-xrp";

registerExactXrpScheme(facilitatorServer, {
  network: "mainnet",
  maxFee: "1000000", // 1 XRP max fee
});

Networks

| Network | CAIP-2 Identifier | WebSocket URL | |---------|------------------|---------------| | Mainnet | xrpl:0 | wss://xrplcluster.com | | Testnet | xrpl:1 | wss://s.altnet.rippletest.net:51233 | | Devnet | xrpl:2 | wss://s.devnet.rippletest.net:51233 |

Verification Checks

The server performs 14 verification checks on every signed transaction:

1. tx_blob format — valid hex, decodable by ripple-binary-codec
2. TransactionType — must be "Payment"
3. Cryptographic signature — ECDSA (secp256k1) or EdDSA (Ed25519) verification via xrpl.js
4. SigningPubKey → Account — derived address must match the Account field
5. Destination match — must match the expected merchant address
6. Amount match — exact drops comparison (no partial payments)
7. Flag enforcement — tfPartialPayment and tfLimitQuality MUST NOT be set
8. Fee sanity — within configurable min/max bounds
9. Account balance — sufficient to cover amount + fee + reserve (on-chain)
10. Sequence validity — matches account's current sequence (on-chain)
11. LastLedgerSequence — not already expired (on-chain)
12. Network match — CAIP-2 identifier matches expected network
13. Replay protection — txHash not already settled
14. Amount type — must be native XRP string, not IOU object

Trust Model

XRP signed transactions have a strong trust model for x402:

• Client constructs and fully signs the Payment transaction
• Facilitator cannot modify any parameter (Account, Destination, Amount, Fee, etc.)
• Any modification invalidates the signature
• Facilitator can only submit or discard — nothing else

Configuration

interface XrpSchemeConfig {
  network?: "mainnet" | "testnet" | "devnet";
  wsUrl?: string;          // custom WebSocket URL
  rpcUrl?: string;         // custom JSON-RPC URL
  maxFee?: string;         // max fee in drops (default: 1000000)
  minFee?: string;         // min fee in drops (default: 10)
  timeout?: number;        // ms (default: 30000)
  allowOfflineVerification?: boolean; // skip on-chain checks
}

API Client

The package includes a JSON-RPC API client for XRP Ledger nodes:

import {
  getAccountInfo,
  getTransactionStatus,
  getServerInfo,
  getRecommendedFee,
  submitTransaction,
  getCurrentLedgerIndex,
} from "@erudite-intelligence/x402-xrp";

const info = await getAccountInfo("rAddr...", { network: "testnet" });
// Returns: { address, balance, sequence, exists, flags, ownerCount }

const fee = await getRecommendedFee({ network: "testnet" });
// Returns: fee string in drops

const ledger = await getCurrentLedgerIndex({ network: "testnet" });
// Returns: current validated ledger index

Testing

npm test
# Runs 3 test suites:
#   verify.test.js           - 31 core verification tests
#   adversarial.test.js      - 43 adversarial/attack tests
#   client-roundtrip.test.js - 53 client + round-trip tests
# Total: 127 tests

Related Packages

• @erudite-intelligence/x402-btc — x402 V2 for Bitcoin (PSBT-based)
• @erudite-intelligence/x402-tron — x402 for Tron (TRC-20 USDT)
• @erudite-intelligence/x402-tron-v2 — x402 V2 for Tron

License

MIT — Erudite Intelligence LLC