@scriptmasterlabs/mcp-x402 2.0.2 → 2.1.1

package/README.md

@@ -1,304 +1,262 @@
-# mcp-x402 — The First MCP Server That Pays for Itself
-
-[![npm](https://img.shields.io/npm/v/@scriptmasterlabs/mcp-x402)](https://www.npmjs.com/package/@scriptmasterlabs/mcp-x402)
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Tests](https://github.com/timwal78/sml_portfolio/actions/workflows/mcp-x402-ci.yml/badge.svg)](https://github.com/timwal78/sml_portfolio/actions)
-
-> **Demo video:** [30-second walkthrough](#) — coming within 48h of launch.
-
-AI agents should pay for their own data — instantly, autonomously, compliantly. `mcp-x402` makes that real.
-
-```bash
-npx @scriptmasterlabs/mcp-x402
-```
-
----
-
-## Why MCP Servers Are Broken (The Manifesto)
-
-Every MCP server connecting to paid APIs today requires:
-- A human to set up API keys
-- A human to manage billing
-- A human to top up credits when they run out
-- A human to rotate keys when they expire
-
-This defeats the entire point of autonomous agents. If your agent has to stop and ask a human for a credit card, it's not autonomous — it's a very expensive chatbot.
-
-**We built the machine-native alternative.**
-
-`mcp-x402` is the first MCP server where agents provision their own wallets, negotiate prices on-chain, pay autonomously, and receive cryptographic receipts — all without human intervention. The agent's credit score goes up every time it successfully transacts. It builds financial reputation the same way humans do.
-
-This is the infrastructure layer that makes truly autonomous AI agents possible.
-
----
-
-## One-Line Install
-
-```bash
-npm i -g @scriptmasterlabs/mcp-x402
-```
-
-Add to your Claude Code `~/.claude/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "sml": {
-      "command": "npx",
-      "args": ["@scriptmasterlabs/mcp-x402"]
-    }
-  }
-}
-```
-
-For Cursor (SSE mode), add to your MCP settings:
-
-```json
-{
-  "mcp-x402": {
-    "url": "http://localhost:3402/sse"
-  }
-}
-```
-
-Then run: `MCP_TRANSPORT=sse npx @scriptmasterlabs/mcp-x402`
-
----
-
-## Architecture
-
-```
-Claude / Cursor
-     │
-     ▼ MCP Protocol (stdio / SSE)
-  mcp-x402 Server
-     ├─ Input validation (Zod, 100% coverage)
-     ├─ Rate limiter (100/min per tool)
-     ├─ AP2 Mandate check (deny-by-default)
-     ├─ Credit Bureau check (min score 300)
-     ├─ Price registry (60s max cache)
-     ├─ x402 payment engine
-     │    ├─ Base USDC (preferred, <3s)
-     │    ├─ XRPL RLUSD (500ms fallback)
-     │    └─ Solana USDC (last resort)
-     ├─ 402Proof receipt generation
-     ├─ SML API call (mTLS)
-     └─ Append-only SHA-256 audit log
-     │
-     ▼ Result + receipt_id back to agent
-```
-
----
-
-## The 6 Tools
-
-### `leviathan_signal` — $0.05 USDC | AP2 required
-Institutional-grade squeeze signals. Multi-engine verdict (OracleEngine + RDT + SML Fractal Cascade).
-
-```typescript
-await use_mcp_tool('sml', 'leviathan_signal', {
-  ticker: 'MSTR',
-  signal_type: 'squeeze',
-  min_confidence: 75
-});
-// Returns: signal verdict + confidence + receipt_id
-```
-
-### `xmit_edgar_decode` — $0.02 USDC | AP2 required
-Parse SEC DEF 14A / 13F / 13D filings. Raw text never leaves SML servers.
-
-```typescript
-await use_mcp_tool('sml', 'xmit_edgar_decode', {
-  filing_url: 'https://www.sec.gov/Archives/edgar/data/...',
-  parse_target: 'executive_pay',
-  format: 'json'
-});
-```
-
-### `xdeo_earnings_estimate` — $0.02 USDC | AP2 required
-Decentralized earnings oracle. Earns +2 Credit Bureau points per successful call.
-
-```typescript
-await use_mcp_tool('sml', 'xdeo_earnings_estimate', {
-  ticker: 'NVDA',
-  fiscal_quarter: 'Q12025',
-  estimate_type: 'all'
-});
-```
-
-### `ftd_threshold_scan` — Alerts FREE / Full $0.05 USDC
-SEC Reg SHO FTD spike detection. 15-minute cache.
-
-```typescript
-// Free tier:
-await use_mcp_tool('sml', 'ftd_threshold_scan', { scan_type: 'alerts' });
-// Paid tier:
-await use_mcp_tool('sml', 'ftd_threshold_scan', { scan_type: 'full', min_spike_multiplier: 3 });
-```
-
-### `nexus_agent_hire` — Query FREE / Hire 5% commission
-Agent marketplace. Find and hire specialized AI agents.
-
-```typescript
-// Free query:
-await use_mcp_tool('sml', 'nexus_agent_hire', { capability: 'options flow analysis', max_budget: '1.00', action: 'query' });
-// Hire:
-await use_mcp_tool('sml', 'nexus_agent_hire', { action: 'hire', agent_id: 'agent_abc', max_budget: '0.50' });
-```
-
-### `crawl_paid_fetch` — $0.005 USDC
-Pay-per-fetch web scraping. Humans bypass automatically.
-
-```typescript
-await use_mcp_tool('sml', 'crawl_paid_fetch', {
-  url: 'https://example.com/data',
-  extract: 'tables'
-});
-```
-
----
-
-## Payment Flow
-
-1. **Discover** — Agent reads `agents.json` or `llms.txt`, sees tool prices
-2. **Authorize** — AP2 mandate checked. Credit Bureau score ≥ 300 auto-approves
-3. **Pay** — x402 stablecoin on cheapest/fastest chain (<3s on Base)
-4. **Prove** — 402Proof receipt in every response
-5. **Earn** — Credit Bureau score updates after success
-
-Every successful tool call returns a `_meta` block:
-```json
-{
-  "_meta": {
-    "receipt_id": "uuid-here",
-    "tx_hash": "0xabc...",
-    "chain": "base",
-    "amount_paid": "0.05 USDC",
-    "timestamp": 1750000000000
-  }
-}
-```
-
----
-
-## SDK — For MCP Server Authors
-
-Install in one line:
-```bash
-npm i @scriptmasterlabs/mcp-x402-sdk
-```
-
-Drop into any MCP server in 5 lines:
-```typescript
-import { x402Payment } from '@scriptmasterlabs/mcp-x402-sdk';
-
-server.tool(
-  'my_paid_tool',
-  myInputSchema,
-  x402Payment({
-    price: '0.01',
-    currency: 'USDC',
-    inputSchema: MyZodSchema,
-    handler: async (input, receipt) => ({
-      content: [{ type: 'text', text: JSON.stringify({ result: await myApi(input), receipt }) }],
-    }),
-  }),
-);
-```
-
-That's it. The SDK handles wallet provisioning, AP2 mandate, chain routing, receipts, and audit logging.
-
----
-
-## Security
-
-| Requirement | Implementation |
-|-------------|----------------|
-| Keys in OS keychain only | `keytar` — macOS Keychain / Windows DPAPI / Linux Secret Service |
-| mTLS on SML APIs | Pinned cert via `node-forge` |
-| No PII in logs | Wallet addresses hashed (SHA-256 prefix), filing content redacted |
-| Zod on all inputs | 100% coverage, validated before any execution |
-| Append-only audit log | SHA-256 HMAC chained log, 7-day local + cloud backup |
-| AP2 mandate required | Verified before every paid call, fail-closed |
-| 402Proof receipt | Every transaction, registered with proof server |
-| Credit Bureau check | min score 300 for auto-approve |
-| $50 daily spend cap | Per wallet, enforced in-process |
-| Testnet in CI | Base Sepolia only, max $0.10 test value |
-| <3s end-to-end | Base mainnet target, 500ms multi-chain fallback |
-
----
-
-## Environment Variables
-
-See [`.env.example`](.env.example) for the full list. Key variables:
-
-```bash
-MCP_TRANSPORT=stdio          # stdio (Claude Code) or sse (Cursor/remote)
-SML_API_BASE=https://api.scriptmasterlabs.com
-BASE_RPC_URL=https://mainnet.base.org
-XRPL_RPC_URL=wss://xrplcluster.com
-DAILY_SPEND_CAP_USD=50
-AUTO_APPROVE_THRESHOLD_USD=1
-TESTNET=false                # Set true + CI_WALLET_SEED for CI
-```
-
-**Private keys**: Stored in your OS keychain automatically on first run. Never in env vars.
-
----
-
-## Running Locally
-
-```bash
-git clone https://github.com/timwal78/sml_portfolio
-cd mcp-x402
-npm install
-npm run build
-npm start
-```
-
-With Docker:
-```bash
-docker build -t mcp-x402 .
-docker run -p 3402:3402 -e MCP_TRANSPORT=sse mcp-x402
-```
-
----
-
-## Testing
-
-```bash
-npm test              # All unit tests
-npm run test:coverage # Coverage report (target: 90%)
-TESTNET=true CI_WALLET_SEED="your mnemonic" npm run test:integration
-```
-
----
-
-## Ecosystem
-
-| Service | URL | Role |
-|---------|-----|------|
-| SqueezeOS API | `squeezeos-api.onrender.com` | Market intelligence |
-| 402Proof | `four02proof.onrender.com` | Payment receipts + Credit Bureau |
-| Ghost Layer | `ghost-layer.onrender.com` | XRPL+Base toll gateway |
-| ScriptMasterLabs | `scriptmasterlabs.com` | Operator homepage |
-
----
-
-## MOAT
-
-- Only MCP server with live x402 + AP2 + multi-chain production stack
-- Only one with Agent Credit Bureau (300–850 scores)
-- Only one backed by live financial intelligence marketplace
-- Only one with SDVOSB federal credibility
-- MIT licensed. No proprietary core.
-
----
-
-## License
-
-MIT — see [LICENSE](LICENSE)
-
-Owner: [@TimmyCrypto78](https://github.com/timwal78) / ScriptMasterLabs  
-Launch Target: 2026-07-02  
-Target: 50K GitHub stars, 5K npm weekly downloads
+# 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)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![XRPL](https://img.shields.io/badge/network-XRPL%20%7C%20Xahau-00aae4)](https://xrpl.org)
+[![x402](https://img.shields.io/badge/protocol-x402-ff6600)](https://x402.org)
+
+Drop-in middleware for [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers
+that lets AI agents autonomously pay for tool access using the
+[x402 protocol](https://x402.org) — no API keys, no subscriptions, no human in the loop.
+
+**Powered by [ScriptMasterLabs](https://scriptmasterlabs.com)**
+
+---
+
+## 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
+
+```bash
+npm install @scriptmasterlabs/mcp-x402 xrpl express
+```
+
+### Gate an MCP tool (server side)
+
+```typescript
+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)
+
+```typescript
+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
+
+```typescript
+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
+
+```bash
+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.
+
+```typescript
+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](https://github.com/Timwal78/zeroquery-protocol) | Proof-of-Intent — AI-to-AI intent resolution with x402 escrow |
+| [AGO Orchestrator](https://github.com/Timwal78/ago-orchestrator) | Autonomous GEO agent for content distribution and gap analysis |
+| [ScriptMasterLabs](https://scriptmasterlabs.com) | Home base — autonomous agent infrastructure |
+
+---
+
+## License
+
+Apache-2.0 — See [LICENSE](LICENSE).
+
+Built by [ScriptMasterLabs](https://scriptmasterlabs.com).
+
+---
+
+*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*

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @scriptmasterlabs/mcp-x402 — Public API barrel
+ *
+ * Everything a consumer needs is exported from this single file.
+ */
+export { createX402Middleware, createPaymentGate } from "./x402-middleware.js";
+export type { X402MiddlewareOptions, PaymentGateOptions, PaymentRequirements, PaymentProof } from "./x402-middleware.js";
+export { XrplFacilitator } from "./xrpl-facilitator.js";
+export type { XrplFacilitatorOptions, XrplNetwork } from "./xrpl-facilitator.js";
+export { wrapMcpServer } from "./mcp-wrapper.js";
+export type { McpTool, McpToolWithPricing, McpServerOptions } from "./mcp-wrapper.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @scriptmasterlabs/mcp-x402 — Public API barrel
+ *
+ * Everything a consumer needs is exported from this single file.
+ */
+export { createX402Middleware, createPaymentGate } from "./x402-middleware.js";
+export { XrplFacilitator } from "./xrpl-facilitator.js";
+export { wrapMcpServer } from "./mcp-wrapper.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG/E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}