[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_117":118},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":21,"_24":25,"_26":27,"_28":29,"_30":31,"_32":33,"_34":25,"_35":36,"_37":-5,"_38":-5,"_39":40,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":62,"_63":64,"_65":66,"_67":48,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":-5,"_79":-5,"_80":-5,"_81":48,"_82":-5,"_83":58,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93,"_94":95},"apiUrl","https://odel.app/api","creator","loop-xxi","moduleId","loop-mcp","@loop-xxi/loop-mcp","displayName","tagline","L402 MCP: 5 paid BTC/Lightning tools + fiat credits, 10-25 sats/call.","iconKey","https://avatars.githubusercontent.com/u/268401977?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://mcp.loopxxi.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1783332430000,"updatedAt",1784695591000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=com.loopxxi%2Floop-mcp","sourceVerified",false,"sourceMissingSince","importedAt","upstreamStars",0,"upstreamUpdatedAt",1784483911000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/Loop-XXI/loop-mcp","githubRepoFullName","Loop-XXI/loop-mcp","releaseId","ext-loop-xxi-loop-mcp","version","2.2.1","descriptionMarkdown","# Loop MCP — dual-rail payments for the Model Context Protocol\n\n**Charge AI agents per tool call over either rail — Bitcoin/Lightning *or* USDC — and settle both into one canonical ledger.**\n\n`@loop-xxi/loop-mcp` is a payment-aware transport for [MCP](https://modelcontextprotocol.io). Drop it in front of an MCP server and every paid tool returns `HTTP 402 Payment Required`; a paying client retries and the call goes through. Built and maintained by **Loop XXI LLC**.\n\nIt is API-compatible with the popular x402-only MCP transport, with one material addition:\n\n> ![L402-paid](https://img.shields.io/badge/tools-L402%20paid-ff9900?logo=lightning&logoColor=white)\n> [![Live](https://img.shields.io/badge/endpoint-live-success)](https://mcp.loopxxi.com/health)\n> [![MCP Registry](https://img.shields.io/badge/registry-com.loopxxi%2Floop--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=loop-mcp)\n> [![L402 Playground](https://img.shields.io/badge/try-L402%20Playground-ff9900)](https://loop-xxi.github.io/loop-mcp/example/playground/)\n> [![Reference clients](https://img.shields.io/badge/reference-Py%20%2B%20TS-blue)](https://github.com/Loop-XXI/loop-mcp/tree/main/example)\n\n\n## Live deployment (v2.3.0)\n\nA **live, hosted** deployment exposes **15 paid tools** on **two payment rails**: Lightning (L402) and fiat-funded prepaid credits via Stripe. Discovery is free. Execution costs 5 to 25 sats per call. There is no subscription and no separate account per tool.\n\n**Endpoint:** `https://mcp.loopxxi.com/mcp` · **Health:** `https://mcp.loopxxi.com/health` · **Catalog:** `https://mcp.loopxxi.com/`\n\n| Tool | Sats | What it returns |\n|---|---:|---|\n| `btc_price` | 10 | Current Bitcoin price in USD and major fiat currencies. |\n| `btc_send_decision` | 15 | A SEND_NOW, WAIT, or URGENT_ONLY verdict from live fee and mempool conditions. |\n| `lightning_address_resolve` | 10 | A Lightning Address resolved through the complete LNURL-pay flow. |\n| `tx_decode_explain` | 25 | A structured transaction explanation with fee, confirmation, and script flags. |\n| `optimal_send_window` | 25 | A recommended send window based on live congestion and fee conditions. |\n| `json_validate` | 5 | JSON validity, root type, normalized JSON, and SHA-256 hash. |\n| `json_extract` | 5 | A nested JSON value selected with a dot path and array indexes. |\n| `csv_to_json` | 10 | Bounded CSV, TSV, semicolon, or pipe data converted to JSON. |\n| `text_analyze` | 5 | Word, line, sentence, character, token, and reading-time estimates. |\n| `hash_generate` | 5 | SHA-256 or SHA-512 output in hex or Base64. |\n| `base64_convert` | 5 | Standard or URL-safe Base64 encoding and decoding. |\n| `timestamp_convert` | 5 | Unix, RFC3339, and date strings normalized to UTC. |\n| `uuid_generate` | 5 | Up to 100 cryptographically random UUIDv4 values. |\n| `url_parse` | 5 | HTTP or HTTPS URL components without a network request. |\n| `jwt_decode` | 5 | JWT header and payload for inspection, always marked unverified. |\n\n### Two payment rails\n\nAgents pay per `tools/call` via either rail:\n\n- **Lightning (L402):** `Authorization: L402 :`. Each valid proof is single-use and bound to the requested tool.\n- **Fiat credits (Stripe):** `Authorization: Bearer loop_`. Buy a $10, $25, or $50 credit key at [`api.loopxxi.com/ai-credits`](https://api.loopxxi.com/ai-credits). loop-mcp calls Loop Gateway's `POST /v1/credits/debit` to atomically debit the prepaid balance.\n\nA request with no auth returns `HTTP 402` with a Lightning invoice (L402) and, in the body, a pointer to the fiat refill URL. Insufficient fiat balance returns `402` with `refill_url: https://api.loopxxi.com/ai-credits`.\n\n### Free try (no wallet required)\n\n`POST https://mcp.loopxxi.com/try/btc_price` returns the live Bitcoin price for free. It is a read-only preview of a tool result before payment setup.\n\n### L402 discovery manifest\n\nGeneric L402 buyer agents and compatible registries can discover the REST-shaped paid endpoints here:\n\n- [`https://mcp.loopxxi.com/.well-known/l402-manifest.json`](https://mcp.loopxxi.com/.well-known/l402-manifest.json)\n\nThe manifest currently advertises `btc_price` (10 sats), `btc_send_decision` (15 sats), and `optimal_send_window` (25 sats). Each endpoint returns a standard HTTP 402 challenge with a BOLT11 invoice and accepts `Authorization: L402 :` on retry.\n\n### Agent payment preflight\n\nAny buyer agent should fetch the machine-readable payment manifest before paying:\n\n- `https://mcp.loopxxi.com/.well-known/agent-payments.json`\n- `https://mcp.loopxxi.com/agent-payments.json`\n\nA dependency-free preflight script is provided in [`example/agent-payment-preflight.mjs`](https://github.com/Loop-XXI/loop-mcp/blob/main/example/agent-payment-preflight.mjs). It checks the manifest, prints the provider / rails / tool table, and exits `OK_TO_PAY` or `DO_NOT_PAY` if the manifest `max_price_sats` exceeds a configurable sats budget.\n\n```bash\n# Default manifest and 25-sats budget\nnode example/agent-payment-preflight.mjs\n\n# Custom manifest URL and budget\nnode example/agent-payment-preflight.mjs https://mcp.loopxxi.com/agent-payments.json --max-sats=50\n```\n\nThe script never pays — it only reads the manifest and makes a go/no-go decision.\n\n### How to call (L402 flow)\n\nThe agent flow is three HTTP calls: **challenge, pay, retry**. On the first `tools/call` with no payment, the server returns `HTTP 402` with a BOLT11 invoice and an L402 token. Pay the invoice over Lightning, then retry the same request with `Authorization: L402 :`. The server verifies the preimage, consumes the proof once, and serves the result.\n\n> **Parsing note:** new challenges expose an opaque base64url token in the `WWW-Authenticate` `token` and legacy `macaroon` fields. Retry with `Authorization: L402 :` and split on the **last** colon, since the preimage is a colon-free 64-character hex string. The server also accepts pre-migration colon-delimited tokens during the compatibility window.\n\n#### curl\n\n```bash\nENDPOINT=\"https://mcp.loopxxi.com/mcp\"\nBODY='{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"btc_price\",\"arguments\":{}}}'\n\n# 1. Challenge — expect HTTP 402 with an invoice.\nRESP=$(curl -s -w \"\\n%{http_code}\" -X POST \"$ENDPOINT\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: application/json, text/event-stream\" \\\n -d \"$BODY\")\nHTTP_CODE=$(echo \"$RESP\" | tail -1)\nBODY_JSON=$(echo \"$RESP\" | sed '$d')\n\n# 2. Extract the token + BOLT11 invoice from the 402 body.\nTOKEN=$(echo \"$BODY_JSON\" | grep -o '\"token\":\"[^\"]*\"' | head -1 | cut -d'\"' -f4)\nINVOICE=$(echo \"$BODY_JSON\" | grep -o '\"payment_request\":\"[^\"]*\"' | head -1 | cut -d'\"' -f4)\n\n# 3. Pay the invoice with any Lightning wallet, then retry with the L402 header.\n# (replace with the 64-char hex preimage your wallet returns)\ncurl -s -X POST \"$ENDPOINT\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: application/json, text/event-stream\" \\\n -H \"Authorization: L402 ${TOKEN}:\" \\\n -d \"$BODY\"\n```\n\n#### JavaScript / Node (fetch)\n\n```js\nconst ENDPOINT = \"https://mcp.loopxxi.com/mcp\";\nconst callTool = {\n jsonrpc: \"2.0\", id: 1, method: \"tools/call\",\n params: { name: \"btc_price\", arguments: {} },\n};\n\n// Replace with your Lightning wallet — must return the 64-char hex preimage.\nasync function payBolt11(invoice) { throw new Error(\"implement payBolt11\"); }\n\n// 1. Challenge → 402.\nconst res1 = await fetch(ENDPOINT, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\", \"Accept\": \"application/json, text/event-stream\" },\n body: JSON.stringify(callTool),\n});\nconst { token, payment_request } = (await res1.json()).error;\n\n// 2. Pay the invoice, get the preimage.\nconst preimage = await payBolt11(payment_request);\n\n// 3. Retry with Authorization: L402 : (split on the LAST colon).\nconst res2 = await fetch(ENDPOINT, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"Accept\": \"application/json, text/event-stream\",\n \"Authorization\": \"L402 \" + token + \":\" + preimage,\n },\n body: JSON.stringify(callTool),\n});\nconsole.log(await res2.json());\n```\n\n#### Fiat credits (Stripe) — no Lightning wallet needed\n\nBuy a credit key at [`api.loopxxi.com/ai-credits`](https://api.loopxxi.com/ai-credits), then send it as a Bearer token. loop-mcp debits your prepaid sats balance on Loop Gateway and serves the result in a single call — no challenge/pay/retry round-trip.\n\n```bash\n# Buy a $10 pack → get a loop_ (1000 credits → sats at live BTC price)\ncurl -s -X POST https://api.loopxxi.com/v1/credits/checkout \\\n -H \"Content-Type: application/json\" -d '{\"pack\":\"p10\"}'\n# → {\"credit_key\":\"loop_...\",\"checkout_url\":\"https://buy.stripe.com/...\"}\n# Complete payment on the Stripe page, then:\n\ncurl -s -X POST https://mcp.loopxxi.com/mcp \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer loop_\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"btc_price\",\"arguments\":{}}}'\n```\n\nThe live deployment source is in [`cmd/loop-mcp/`](https://github.com/Loop-XXI/loop-mcp/blob/main/cmd/loop-mcp) and [`tools/`](https://github.com/Loop-XXI/loop-mcp/blob/main/tools) (Go, dual-rail: L402 + fiat credit_key). The dual-rail npm library below is the broader transport.\n\n\n> ### The addition: a second rail — Lightning / L402\n> Most agent-payment tooling speaks only **x402 / USDC on Base**. Loop MCP adds the **Lightning Network via [L402](https://github.com/lightninglabs/L402)** as a first-class second rail, negotiated in the *same* `402` response and reconciled into a single **rail-tagged canonical ledger**. As of this writing, **zero** L402-native MCP servers exist in the public MCP registry — this closes that gap.\n\n```\n ┌──────────────── 402 Payment Required ───────────────┐\n agent / MCP client ───▶│ accepts: [ x402 (USDC on Base), l402 (Lightning) ] │\n └──────────────────────────────────────────────────────┘\n │ │\n pay USDC + retry │ │ pay invoice + retry\n (X-PAYMENT header) ▼ ▼ (Authorization: L402 mac:preimage)\n ┌─────────────────────────────────────────────┐\n │ LoopDualRailServerTransport │\n │ verify ─▶ run tool ─▶ settle ─▶ LoopLedger │\n └─────────────────────────────────────────────┘\n │ rail-tagged rows (x402 | l402)\n ▼\n canonical revenue (net sats north-star)\n```\n\n## Why dual-rail\n\n| | x402 / USDC | L402 / Lightning *(the addition)* |\n|---|---|---|\n| Settlement | USDC on Base/EVM | Bitcoin over Lightning |\n| Proof | EVM tx hash via facilitator | `sha256(preimage) == payment_hash` |\n| Header in | `X-PAYMENT` | `Authorization: L402 :` |\n| Best for | EVM-native agents, stablecoin treasuries | sub-cent micropayments, Bitcoin-native flows |\n| Discount | face value | **21% Bitcoin-payment discount ≤ $100** |\n\nBoth rails resolve to one **`LoopLedger`** with a `rail` tag on every row, so x402 and L402 revenue roll up into a single number. Synthetic/test rows tagged `internal:*` are excluded from canonical revenue.\n\n## Install\n\nThe **hosted server is live now** — for an immediate paid tool call, point any MCP / L402 client at `https://mcp.loopxxi.com/mcp` (see [How to call](#how-to-call-l402-flow) above), no install required.\n\nTo embed the dual-rail transport in your own MCP server, install from npm:\n\n```bash\nnpm install @loop-xxi/loop-mcp\n# peer dependency\nnpm install @modelcontextprotocol/sdk\n```\n\n## Server — make any MCP tool payable on both rails\n\n```ts\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport {\n makePaymentAwareServerTransport,\n PhoenixdProvider,\n LoopLedger,\n} from \"@loop-xxi/loop-mcp\";\n\nconst server = new McpServer({ name: \"my-server\", version: \"1.0.0\" });\nserver.tool(\"get-quote\", \"Premium market data\", { /* schema */ }, async () => ({\n content: [{ type: \"text\", text: \"...\" }],\n}));\n\nconst transport = makePaymentAwareServerTransport(\n \"0xYourReceivingAddress\", // x402 / USDC payouts\n { \"get-quote\": \"$0.01\" }, // per-tool USD price\n {\n network: \"base\",\n ledger: new LoopLedger(),\n // The addition — enable the Lightning / L402 rail:\n lightning: {\n provider: new PhoenixdProvider(process.env.PHOENIXD_URL!, process.env.PHOENIXD_PASSWORD!),\n l402Secret: process.env.L402_SECRET!,\n btcUsdPrice: 65000, // live spot, injected\n },\n }\n);\n\nawait server.connect(transport);\n```\n\nIf you omit `lightning`, you get the original single-rail (x402-only) behaviour.\n\n## Client — pay automatically over your preferred rail\n\n```ts\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { makePaymentAwareClientTransport } from \"@loop-xxi/loop-mcp\";\n\nconst transport = makePaymentAwareClientTransport(serverUrl, wallet, {\n preferredRail: \"l402\", // or \"x402\"\n lightningPayer, // pays the invoice, returns the preimage\n paymentCallback: (proof, rail) => console.log(`paid via ${rail}: ${proof}`),\n});\n\nconst client = new Client({ name: \"agent\", version: \"1.0.0\" }, { capabilities: {} });\nawait client.connect(transport); // tool calls now pay automatically\n```\n\n## Proxies (no code changes)\n\n- **Server proxy** — wrap an existing API-key-protected MCP server with dual-rail payments: `createServerProxy({ upstreamUrl, apiKey, paymentWallet, toolPricing, lightning })`.\n- **Client proxy / CLI** — let a non-paying client (e.g. Claude Desktop) pay on your behalf:\n\n```bash\nTARGET_URL=https://server/mcp PRIVATE_KEY=0x... RAIL=l402 npx loop-mcp client-proxy\n```\n\n## How it works\n\n1. **Challenge.** A priced `tools/call` with no payment returns `402` whose `accepts` array carries *both* an x402 requirement and an L402 offer (Lightning invoice + macaroon). The L402 leg is also mirrored in a standard `WWW-Authenticate: L402 ...` header.\n2. **Pay.** The client pays either rail and retries: `X-PAYMENT` (x402) or `Authorization: L402 :` (L402).\n3. **Verify.** x402 is verified/settled through an x402 facilitator. L402 is verified by checking the macaroon HMAC and `sha256(preimage) == payment_hash` — the classic Lightning proof-of-payment.\n4. **Settle + record.** On a successful tool result the payment is settled and written to `LoopLedger` with its `rail` tag and a USD-equivalent for cross-rail roll-up. A settlement receipt is attached to the tool result (`loopSettlement`) and `X-PAYMENT-RESPONSE`.\n\n## Verify the core without any chain\n\nThe dual-rail payment core (L402 macaroon + preimage, x402 atomic conversion, 21% sats quote, canonical ledger) is dependency-free and runs anywhere:\n\n```bash\nnode scripts/demo-core.mjs\n# ✅ valid preimage verifies\n# ✅ forged preimage rejected\n# ✅ cross-tool replay rejected\n# ✅ wrong-secret macaroon rejected\n# ✅ x402 atomic amount = 2000\n# ✅ canonical rows = 2 (internal excluded)\n# ✅ canonical USD roll-up = 0.003\n# === 7 passed, 0 failed ===\n```\n\nUnit tests: `npm test` (vitest).\n\n## Layout\n\n```\nsrc/\n server.ts LoopDualRailServerTransport (x402 port + L402 addition)\n client.ts dual-rail client transport\n rails/x402.ts USDC/x402 helpers (dependency-free)\n rails/l402.ts L402 macaroon + preimage verification (dependency-free)\n lightning/provider.ts MockLightningProvider + PhoenixdProvider\n pricing/satsQuote.ts USD→sats with 21% BTC discount ≤ $100\n ledger.ts canonical rail-tagged ledger\n proxy/index.ts client & server proxies\nexample/ dual-rail \"todo\" MCP server + client\nscripts/demo-core.mjs zero-dependency end-to-end proof of the payment core\ntest/core.test.ts unit tests\n```\n\n## Security notes\n\n- Never commit private keys, `L402_SECRET`, or phoenixd passwords. Use env vars.\n- Use testnets (`base-sepolia`, regtest) during development.\n- L402 macaroons bind the payment hash to the specific tool, amount and an expiry, so a cheap invoice's preimage cannot be replayed against a pricier tool.\n- Treat ledger rows as canonical only after reconciliation; tag synthetic rows `internal:*`.\n\n---\n\nMIT © 2026 Loop XXI LLC · https://loopxxi.com\n\n*Derived from the open x402-MCP transport design and extended with a Lightning/L402 rail and a unified rail-tagged ledger. \"x402\" is a Coinbase open standard; \"L402\" is a Lightning Labs standard.*\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays","iconType","image","upstream",{"_103":104,"_105":106,"_107":108,"_109":110,"_111":112,"_113":114},"requiredSecrets",[],"tags",[98,99,100,101,102],"assets",[],"stats",{"_96":58,"_97":58},"ratingAvg","reviewCount","agent-payments","bitcoin","l402","lightning","micropayments","topics",[98,99,100,101,115,102,116],"license","MIT","language","Go","registryName","com.loopxxi/loop-mcp","homepage","https://loopxxi.com","packages",[],"mcp","model-context-protocol","ENV",{"_119":120,"_121":122,"_123":124},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]