@scriptmasterlabs/mcp-x402 2.1.1 → 2.1.2

package/README.md

@@ -1,262 +1,304 @@
-# 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*
+# 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