ScriptMaster Agentic Vending Router

by Timwal78

186 downloads

Not rated

GitHub

Other

Description

# 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…

About

# 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. [![npm](https://img.shields.io/npm/v/@scriptmasterlabs/mcp-x402)](https://npmjs.com/package/@scriptmasterlabs/mcp-x402)…

Details

Author: Timwal78
Downloads: 186
Categories: Other

- First and only x402 implementation for XRPL and Xahau.
- Supports XRP, RLUSD, and XAH currencies.
- ~3 second settlement finality with fees below $0.00001.
- No external node required – connects to public clusters.
- Safety cap prevents runaway payments per request.
- Drop-in Express middleware for both server and client.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name ScriptMaster Agentic Vending Router

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

From the repository

Install the package @scriptmasterlabs/mcp-x402 with npm. On the server side, use createPaymentGate() to gate an Express route, or wrapMcpServer() to spin up a complete MCP server with per-tool pricing. On the client (agent) side, use createX402Middleware() to automatically fulfill payment requirements. A testnet demo is available by cloning the repository and running node examples/pay-per-tool.js.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "scriptmaster agentic vending router": {
            "mcp-x402-xrpl": {
                "command": "node",
                "args": [
                    "examples/pay-per-tool.js"
                ]
            }
        }
    }
}

McpServers

{
    "mcp-x402-xrpl": {
        "command": "node",
        "args": [
            "examples/pay-per-tool.js"
        ]
    }
}

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

---

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.

---

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 express

Gate an MCP tool (server side)

import express from "express";
import { createPaymentGate } from "@scriptmasterlabs/mcp-x402";
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";
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";
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

| Network | Chain | Currency | Settlement time | Avg fee |
|---------|-------|----------|-----------------|---------|
| xrpl-mainnet | XRP Ledger | XRP (drops) | ~3 sec | 0.00001 XRP |
| xrpl-mainnet | XRP Ledger | RLUSD (IOU) | ~3 sec | 0.00001 XRP |
| xrpl-testnet | XRP Ledger testnet | XRP | ~3 sec | free |
| xahau-mainnet | Xahau | XAH (drops) | ~3 sec | 0.00001 XAH |
| xahau-testnet | Xahau testnet | XAH | ~3 sec | free |

---

XRPL vs EVM: x402 settlement comparison

| Feature | mcp-x402-xrpl (XRPL) | EVM x402 (Base/Ethereum) |
|---------|----------------------|--------------------------|
| Settlement finality | ~3 seconds | ~2 sec (Base) / ~12 sec (ETH) |
| Avg tx fee | $0.000005 | $0.001–$0.10 |
| Stablecoin support | RLUSD | USDC |
| Custodian required | ❌ No | ❌ No |
| Smart contract risk | ❌ Minimal (no EVM) | ⚠️ EVM surface area |
| DID / Identity | ✅ Xahau Hooks (XAH) | ⚠️ External |
| MCP x402 package | @scriptmasterlabs/mcp-x402 | @x402/mcp, mcp-go-x402 |

---

API reference

`createX402Middleware(opts)` → Express middleware

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

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| walletSeed | string | required | XRPL family seed (sEdT...) |
| network | XrplNetwork | "xrpl-mainnet" | Network to use |
| maxPaymentDrops | string | none | Safety cap per request |

`createPaymentGate(opts)` → Express middleware

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

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| destination | string | required | XRPL receiving address |
| amountDrops | string | — | XRP amount in drops |
| amount | string | — | Non-XRP amount (RLUSD/XAH) |
| currency | "XRP"\|"RLUSD"\|"XAH" | "XRP" | Settlement currency |
| destinationTag | number | — | Optional destination tag |

`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. Install with npm install @scriptmasterlabs/mcp-x402.

---

Related projects

| Project | Description |
|---------|-------------|
| ZeroQuery Protocol | Proof-of-Intent — AI-to-AI intent resolution with x402 escrow |
| AGO Orchestrator | Autonomous GEO agent for content distribution and gap analysis |
| ScriptMasterLabs | Home base — autonomous agent infrastructure |

---

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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Description

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

mcp-x402-xrpl

What is x402?

How it works

Quick start

Gate an MCP tool (server side)

Pay for a tool (agent / client side)

Drop-in MCP server wrapper

Run the testnet demo

Supported networks & currencies

XRPL vs EVM: x402 settlement comparison

API reference

createX402Middleware(opts) → Express middleware

createPaymentGate(opts) → Express middleware

wrapMcpServer(opts) → { app, listen }

XrplFacilitator

FAQ

Related projects

License

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`createX402Middleware(opts)` → Express middleware

`createPaymentGate(opts)` → Express middleware

`wrapMcpServer(opts)` → `{ app, listen }`

`XrplFacilitator`