loop-mcp

Charge AI agents per tool call over either rail — Bitcoin/Lightning or USDC — and settle both into one canonical ledger.

@loop-xxi/loop-mcp is a payment-aware transport for MCP. 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.

It is API-compatible with the popular x402-only MCP transport, with one material addition:

Live MCP Registry L402 Playground Reference clients

Live deployment (v2.3.0)

A 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.

Endpoint: https://mcp.loopxxi.com/mcp · Health: https://mcp.loopxxi.com/health · Catalog: https://mcp.loopxxi.com/

Tool	Sats	What it returns
btc_price	10	Current Bitcoin price in USD and major fiat currencies.
btc_send_decision	15	A SEND_NOW, WAIT, or URGENT_ONLY verdict from live fee and mempool conditions.
lightning_address_resolve	10	A Lightning Address resolved through the complete LNURL-pay flow.
tx_decode_explain	25	A structured transaction explanation with fee, confirmation, and script flags.
optimal_send_window	25	A recommended send window based on live congestion and fee conditions.
json_validate	5	JSON validity, root type, normalized JSON, and SHA-256 hash.
json_extract	5	A nested JSON value selected with a dot path and array indexes.
csv_to_json	10	Bounded CSV, TSV, semicolon, or pipe data converted to JSON.
text_analyze	5	Word, line, sentence, character, token, and reading-time estimates.
hash_generate	5	SHA-256 or SHA-512 output in hex or Base64.
base64_convert	5	Standard or URL-safe Base64 encoding and decoding.
timestamp_convert	5	Unix, RFC3339, and date strings normalized to UTC.
uuid_generate	5	Up to 100 cryptographically random UUIDv4 values.
url_parse	5	HTTP or HTTPS URL components without a network request.
jwt_decode	5	JWT header and payload for inspection, always marked unverified.

Two payment rails

Agents pay per tools/call via either rail:

• Lightning (L402): Authorization: L402 <token>:<preimage>. Each valid proof is single-use and bound to the requested tool.
• Fiat credits (Stripe): Authorization: Bearer loop_<credit_key>. Buy a $10, $25, or $50 credit key at api.loopxxi.com/ai-credits. loop-mcp calls Loop Gateway's POST /v1/credits/debit to atomically debit the prepaid balance.

A 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.

Free try (no wallet required)

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.

L402 discovery manifest

Generic L402 buyer agents and compatible registries can discover the REST-shaped paid endpoints here:

• https://mcp.loopxxi.com/.well-known/l402-manifest.json

The 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 <token>:<preimage> on retry.

Agent payment preflight

Any buyer agent should fetch the machine-readable payment manifest before paying:

• https://mcp.loopxxi.com/.well-known/agent-payments.json
• https://mcp.loopxxi.com/agent-payments.json

A dependency-free preflight script is provided in 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.

# Default manifest and 25-sats budget
node example/agent-payment-preflight.mjs

# Custom manifest URL and budget
node example/agent-payment-preflight.mjs https://mcp.loopxxi.com/agent-payments.json --max-sats=50

The script never pays — it only reads the manifest and makes a go/no-go decision.

How to call (L402 flow)

The 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 <token>:<preimage>. The server verifies the preimage, consumes the proof once, and serves the result.

Parsing note: new challenges expose an opaque base64url token in the WWW-Authenticate token and legacy macaroon fields. Retry with Authorization: L402 <token>:<preimage> 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.

curl

ENDPOINT="https://mcp.loopxxi.com/mcp"
BODY='{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"btc_price","arguments":{}}}'

# 1. Challenge — expect HTTP 402 with an invoice.
RESP=$(curl -s -w "\n%{http_code}" -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d "$BODY")
HTTP_CODE=$(echo "$RESP" | tail -1)
BODY_JSON=$(echo "$RESP" | sed '$d')

# 2. Extract the token + BOLT11 invoice from the 402 body.
TOKEN=$(echo "$BODY_JSON" | grep -o '"token":"[^"]*"' | head -1 | cut -d'"' -f4)
INVOICE=$(echo "$BODY_JSON" | grep -o '"payment_request":"[^"]*"' | head -1 | cut -d'"' -f4)

# 3. Pay the invoice with any Lightning wallet, then retry with the L402 header.
#    (replace <PREIMAGE> with the 64-char hex preimage your wallet returns)
curl -s -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: L402 ${TOKEN}:<PREIMAGE>" \
  -d "$BODY"

JavaScript / Node (fetch)

const ENDPOINT = "https://mcp.loopxxi.com/mcp";
const callTool = {
  jsonrpc: "2.0", id: 1, method: "tools/call",
  params: { name: "btc_price", arguments: {} },
};

// Replace with your Lightning wallet — must return the 64-char hex preimage.
async function payBolt11(invoice) { throw new Error("implement payBolt11"); }

// 1. Challenge → 402.
const res1 = await fetch(ENDPOINT, {
  method: "POST",
  headers: { "Content-Type": "application/json", "Accept": "application/json, text/event-stream" },
  body: JSON.stringify(callTool),
});
const { token, payment_request } = (await res1.json()).error;

// 2. Pay the invoice, get the preimage.
const preimage = await payBolt11(payment_request);

// 3. Retry with Authorization: L402 <token>:<preimage> (split on the LAST colon).
const res2 = await fetch(ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "Authorization": "L402 " + token + ":" + preimage,
  },
  body: JSON.stringify(callTool),
});
console.log(await res2.json());

Fiat credits (Stripe) — no Lightning wallet needed

Buy a credit key at 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.

# Buy a $10 pack → get a loop_<credit_key> (1000 credits → sats at live BTC price)
curl -s -X POST https://api.loopxxi.com/v1/credits/checkout \
  -H "Content-Type: application/json" -d '{"pack":"p10"}'
# → {"credit_key":"loop_...","checkout_url":"https://buy.stripe.com/..."}
# Complete payment on the Stripe page, then:

curl -s -X POST https://mcp.loopxxi.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer loop_<credit_key>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"btc_price","arguments":{}}}'

The live deployment source is in cmd/loop-mcp/ and tools/ (Go, dual-rail: L402 + fiat credit_key). The dual-rail npm library below is the broader transport.

The addition: a second rail — Lightning / L402

Most agent-payment tooling speaks only x402 / USDC on Base. Loop MCP adds the Lightning Network via 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.

                          ┌──────────────── 402 Payment Required ───────────────┐
   agent / MCP client ───▶│  accepts: [ x402 (USDC on Base),  l402 (Lightning) ] │
                          └──────────────────────────────────────────────────────┘
                                   │                              │
                pay USDC + retry   │                              │  pay invoice + retry
              (X-PAYMENT header)   ▼                              ▼  (Authorization: L402 mac:preimage)
                          ┌─────────────────────────────────────────────┐
                          │      LoopDualRailServerTransport             │
                          │  verify ─▶ run tool ─▶ settle ─▶ LoopLedger  │
                          └─────────────────────────────────────────────┘
                                   │  rail-tagged rows (x402 | l402)
                                   ▼
                            canonical revenue (net sats north-star)

Why dual-rail

	x402 / USDC	L402 / Lightning (the addition)
Settlement	USDC on Base/EVM	Bitcoin over Lightning
Proof	EVM tx hash via facilitator	sha256(preimage) == payment_hash
Header in	X-PAYMENT	Authorization: L402 <macaroon>:<preimage>
Best for	EVM-native agents, stablecoin treasuries	sub-cent micropayments, Bitcoin-native flows
Discount	face value	21% Bitcoin-payment discount ≤ $100

Both 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.

Install

The 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 above), no install required.

To embed the dual-rail transport in your own MCP server, install from npm:

npm install @loop-xxi/loop-mcp
# peer dependency
npm install @modelcontextprotocol/sdk

Server — make any MCP tool payable on both rails

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
  makePaymentAwareServerTransport,
  PhoenixdProvider,
  LoopLedger,
} from "@loop-xxi/loop-mcp";

const server = new McpServer({ name: "my-server", version: "1.0.0" });
server.tool("get-quote", "Premium market data", { /* schema */ }, async () => ({
  content: [{ type: "text", text: "..." }],
}));

const transport = makePaymentAwareServerTransport(
  "0xYourReceivingAddress",            // x402 / USDC payouts
  { "get-quote": "$0.01" },            // per-tool USD price
  {
    network: "base",
    ledger: new LoopLedger(),
    // The addition — enable the Lightning / L402 rail:
    lightning: {
      provider: new PhoenixdProvider(process.env.PHOENIXD_URL!, process.env.PHOENIXD_PASSWORD!),
      l402Secret: process.env.L402_SECRET!,
      btcUsdPrice: 65000,              // live spot, injected
    },
  }
);

await server.connect(transport);

If you omit lightning, you get the original single-rail (x402-only) behaviour.

Client — pay automatically over your preferred rail

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { makePaymentAwareClientTransport } from "@loop-xxi/loop-mcp";

const transport = makePaymentAwareClientTransport(serverUrl, wallet, {
  preferredRail: "l402",               // or "x402"
  lightningPayer,                      // pays the invoice, returns the preimage
  paymentCallback: (proof, rail) => console.log(`paid via ${rail}: ${proof}`),
});

const client = new Client({ name: "agent", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);       // tool calls now pay automatically

Proxies (no code changes)

• Server proxy — wrap an existing API-key-protected MCP server with dual-rail payments: createServerProxy({ upstreamUrl, apiKey, paymentWallet, toolPricing, lightning }).
• Client proxy / CLI — let a non-paying client (e.g. Claude Desktop) pay on your behalf:

TARGET_URL=https://server/mcp PRIVATE_KEY=0x... RAIL=l402 npx loop-mcp client-proxy

How it works

1. 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.
2. Pay. The client pays either rail and retries: X-PAYMENT (x402) or Authorization: L402 <macaroon>:<preimage> (L402).
3. 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.
4. 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.

Verify the core without any chain

The dual-rail payment core (L402 macaroon + preimage, x402 atomic conversion, 21% sats quote, canonical ledger) is dependency-free and runs anywhere:

node scripts/demo-core.mjs
# ✅ valid preimage verifies
# ✅ forged preimage rejected
# ✅ cross-tool replay rejected
# ✅ wrong-secret macaroon rejected
# ✅ x402 atomic amount = 2000
# ✅ canonical rows = 2 (internal excluded)
# ✅ canonical USD roll-up = 0.003
# === 7 passed, 0 failed ===

Unit tests: npm test (vitest).

Layout

src/
  server.ts            LoopDualRailServerTransport (x402 port + L402 addition)
  client.ts            dual-rail client transport
  rails/x402.ts        USDC/x402 helpers (dependency-free)
  rails/l402.ts        L402 macaroon + preimage verification (dependency-free)
  lightning/provider.ts MockLightningProvider + PhoenixdProvider
  pricing/satsQuote.ts  USD→sats with 21% BTC discount ≤ $100
  ledger.ts            canonical rail-tagged ledger
  proxy/index.ts       client & server proxies
example/               dual-rail "todo" MCP server + client
scripts/demo-core.mjs  zero-dependency end-to-end proof of the payment core
test/core.test.ts      unit tests

Security notes

• Never commit private keys, L402_SECRET, or phoenixd passwords. Use env vars.
• Use testnets (base-sepolia, regtest) during development.
• 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.
• Treat ledger rows as canonical only after reconciliation; tag synthetic rows internal:*.

---

MIT © 2026 Loop XXI LLC · https://loopxxi.com

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.