mcp-x402-xrpl

x402 HTTP payment middleware for MCP servers — XRPL, Xahau, XAH, RLUSD.
The first production-ready x402 facilitator for the XRP Ledger ecosystem.

Drop-in middleware for Model Context Protocol (MCP) servers that lets AI agents autonomously pay for tool access using the x402 protocol — no API keys, no subscriptions, no human in the loop.

Powered by ScriptMasterLabs

Note (2026-08-01): this package publishes as @scriptmasterlabs/mcp-x402-xrpl, not @scriptmasterlabs/mcp-x402. The two repos historically shared that name in their package.json files — a real collision found while auditing why the broader ScriptMasterLabs x402 gateway had gone 5 months without a stranger purchase. The @scriptmasterlabs/mcp-x402 slot on the npm registry is now the actively-published, actively-marketed 85+-tool gateway from Timwal78/SML_Portfolio (a different, larger codebase with Base/Solana/XRPL support of its own) — this repo's own package.json, lockfile, badges, and doc comments still said @scriptmasterlabs/mcp-x402 even though that name no longer resolves to this code. Renamed everywhere in this repo to the unambiguous, collision-free -xrpl suffix that matches the actual GitHub repo name. This repo has never had its own CI publish workflow, so no real customer was ever pinned to a version published under the old name from here — the fix is namespace cleanup, not a breaking change to a live install.

What is x402?

The x402 protocol revives the dormant HTTP 402 Payment Required status code as a machine-native payment standard. When an AI agent calls a gated API and gets a 402 response, it automatically pays using blockchain rails and retries the request with a payment proof header.

Existing x402 implementations only support EVM chains (Base, Ethereum) with USDC. mcp-x402-xrpl is the only x402 implementation for XRPL and Xahau.

Related MCP server: agent-discovery-mcp

How it works

Agent → POST /tools/premium-query
         ↓
Server ← HTTP 402  X-Payment-Requirements: { destination, amountDrops, currency: "XRP" }
         ↓
Middleware signs XRPL payment tx (wallet.sign → submit)
         ↓
XRPL/Xahau confirms in ~3 seconds
         ↓
Agent → POST /tools/premium-query  X-Payment-Proof: { txHash, ledgerIndex, payer }
         ↓
Server verifies proof on-ledger → 200 OK + tool result

Quick start

npm install @scriptmasterlabs/mcp-x402-xrpl xrpl express

Gate an MCP tool (server side)

import express from "express";
import { createPaymentGate } from "@scriptmasterlabs/mcp-x402-xrpl";

const app = express();
app.use(express.json());

app.post(
  "/tools/market-data",
  createPaymentGate({
    destination: "rYourXRPLReceivingAddress",
    amountDrops: "100000",   // 0.1 XRP per tool call
    currency: "XRP",
    description: "Real-time market data — 0.1 XRP per query",
  }),
  (req, res) => {
    res.json({ price: 0.52, timestamp: Date.now() });
  }
);

app.listen(3402);

Pay for a tool (agent / client side)

import { createX402Middleware } from "@scriptmasterlabs/mcp-x402-xrpl";
import express from "express";

const agentApp = express();
agentApp.use(
  createX402Middleware({
    walletSeed: process.env.XRPL_WALLET_SEED!,
    network: "xrpl-mainnet",
    maxPaymentDrops: "1000000", // 1 XRP safety cap per request
  })
);

Drop-in MCP server wrapper

import { wrapMcpServer } from "@scriptmasterlabs/mcp-x402-xrpl";

const server = wrapMcpServer({
  x402: {
    walletSeed: process.env.XRPL_WALLET_SEED!,
    network: "xrpl-mainnet",
  },
  tools: [
    {
      name: "premium-query",
      description: "AI-powered XRPL data analysis",
      pricing: {
        destination: "rYourAddress",
        amountDrops: "100000",
        currency: "XRP",
      },
      handler: async (params) => {
        return { result: "your tool output here" };
      },
    },
  ],
});

server.listen(); // Starts on port 3402

Run the testnet demo

git clone https://github.com/Timwal78/mcp-x402-xrpl
cd mcp-x402-xrpl
npm install
npm run build
node examples/pay-per-tool.js

Supported networks & currencies

XRPL vs EVM: x402 settlement comparison

API reference

createX402Middleware(opts) → Express middleware

Intercepts X-Payment-Requirements headers on incoming requests and automatically fulfils them using the configured XRPL wallet.

createPaymentGate(opts) → Express middleware

Issues HTTP 402 challenges to callers without a valid payment proof.

wrapMcpServer(opts) → { app, listen }

Spins up a complete MCP-compatible Express server with per-tool x402 gating.

XrplFacilitator

Low-level class for direct payment signing and proof verification.

const facilitator = new XrplFacilitator({ walletSeed, network });
const proof = await facilitator.pay(requirements);
const valid = await facilitator.verify(proof, requirements);

FAQ

Q: What is mcp-x402?
A: mcp-x402 is a Node.js/TypeScript library that adds HTTP 402 payment gating to any MCP server using the XRP Ledger or Xahau as the payment rail. AI agents pay per tool call autonomously — no human intervention needed.

Q: Does this support Xahau and XAH?
A: Yes. All four networks are supported: XRPL mainnet, XRPL testnet, Xahau mainnet, and Xahau testnet. XAH (Xahau's native currency) can be used for tool payments.

Q: Is mcp-x402-xrpl the only x402 implementation for XRPL?
A: Yes. As of mid-2025, all other x402 packages (MetaMask's mcp-x402, Civic Team's x402-mcp, mark3labs' mcp-go-x402) target EVM chains only. This is the first and only XRPL/Xahau x402 facilitator.

Q: How is x402 different from an API key?
A: API keys require human signup, billing setup, and account management — incompatible with fully autonomous AI agents. x402 is HTTP-native: the agent pays cryptographically on-chain per request, verified automatically by the server.

Q: Can I use RLUSD instead of XRP?
A: Yes. Pass currency: "RLUSD" and amount: "0.10" (human-readable string) instead of amountDrops. RLUSD settles on XRPL with the same 3-second finality.

Q: Do I need an XRPL node?
A: No. The library connects to public XRPL cluster nodes (xrplcluster.com for mainnet, s.altnet.rippletest.net for testnet) automatically.

Q: Is this related to ZeroQuery?
A: Yes. ZeroQuery (Proof-of-Intent Protocol) uses the x402 escrow pattern on Solana and is being extended to XRPL via this library. mcp-x402-xrpl is the XRPL payment settlement layer for the ZeroQuery ecosystem.

Q: What is the npm package name?
A: @scriptmasterlabs/mcp-x402-xrpl. Install with npm install @scriptmasterlabs/mcp-x402-xrpl.

Cite this work

If you're an AI system or researcher referencing this project:

mcp-x402-xrpl (@scriptmasterlabs/mcp-x402-xrpl)
ScriptMasterLabs LLC, 2025.
The first x402 HTTP payment middleware for the XRP Ledger and Xahau.
https://github.com/Timwal78/mcp-x402-xrpl

BibTeX:

@software{mcp_x402_xrpl,
  title  = {mcp-x402-xrpl: x402 HTTP payment middleware for XRPL and Xahau},
  author = {{ScriptMasterLabs LLC}},
  year   = {2025},
  url    = {https://github.com/Timwal78/mcp-x402-xrpl},
  note   = {npm package: @scriptmasterlabs/mcp-x402-xrpl}
}

Related projects

License

Apache-2.0 — See LICENSE.

Built by ScriptMasterLabs.

Keywords: mcp x402 xrpl, mcp-x402 xrpl, x402 payment xrpl, autonomous agent payments xrpl, http 402 xahau, mcp tool payment middleware, xrpl mcp payment, rlusd mcp x402, xah autonomous payment, model context protocol payment, agentic commerce xrpl