L402 Gate Example

Minimal MCP server showing @powforge/mcp-l402-gate in action.

One tool, bitcoin_data, fetches current BTC/USD price plus recommended mempool fees from mempool.space. Each call is gated by:

1. An L402 Lightning invoice (the caller pays sats per call).
2. A Depth-of-Identity score lookup against the public PowForge oracle. Below the threshold, paying does not get you through.

L402 alone proves a caller paid. L402 + DoI proves they paid and carry a per-pubkey reputation that survives across sessions and costs irreversible work to fake. That second half is the part most MCP billing kits skip.

Quickstart

git clone https://github.com/zekebuilds-lab/mcp-l402-gate-example
cd mcp-l402-gate-example
cp .env.example .env       # fill in GATE_HMAC_SECRET and LNBits creds
npm install
npm start

Server logs the tool URL and oracle on boot. Default port is 3100.

Test it with curl

First call has no auth, so the gate returns a 402 with an invoice:

curl -i -X POST http://localhost:3100/tools/bitcoin_data \
  -H 'Content-Type: application/json' \
  -H 'X-Caller-Pubkey: 02a1b2c3...your-hex-pubkey' \
  -d '{}'

Expected response:

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="...", invoice="lnbc1..."
Content-Type: application/json

{
  "error": "payment required",
  "macaroon": "...",
  "invoice": "lnbc1...",
  "payment_hash": "..."
}

Pay the invoice field (any LN wallet), capture the preimage, then retry:

curl -i -X POST http://localhost:3100/tools/bitcoin_data \
  -H 'Content-Type: application/json' \
  -H 'X-Caller-Pubkey: 02a1b2c3...your-hex-pubkey' \
  -H 'Authorization: L402 <macaroon>:<preimage>' \
  -d '{}'

You get back the BTC price, mempool fee estimates, and the caller's DoI score.

The manifest is also exposed for MCP clients that introspect tool catalogs:

curl http://localhost:3100/manifest.json

Configuration

Variable	Description	Required	Default
GATE_HMAC_SECRET	HMAC key for signing L402 macaroons. Generate with openssl rand -hex 32.	yes	-
LNBITS_URL	Your LNBits instance base URL.	yes	-
LNBITS_INVOICE_KEY	LNBits invoice/read key. Never use the admin key.	yes	-
ORACLE_URL	DoI oracle base URL.	no	https://identity.powforge.dev
PORT	HTTP port.	no	3100
SATS_AMOUNT	Sats charged per call.	no	1
MIN_SCORE	Minimum DoI composite score to pass the gate. 0 disables identity gating.	no	0

DoI score thresholds

These are the same buckets the oracle returns as rank. Pick the one that matches how expensive a wrong call is:

MIN_SCORE	Rank	Fits
0	unknown	Pure paywall. Identity does not matter.
10	emerging	First-call abuse hurts. Sensible default for most public MCP tools.
40	active	The tool burns real GPU or has expensive side effects.
100	established	Compliance-sensitive or single-tenant SaaS-style endpoints.
200	trusted	High-trust admin tooling.

How the gate works

Without the gate, a 402 + macaroon flow proves the caller paid 10 sats. A fresh attacker wallet pays the same 10 sats. That is fine wire format and weak abuse control.

@powforge/mcp-l402-gate keeps the L402 invoice and adds a second check: when the macaroon verifies, the gate calls the DoI oracle for the caller's pubkey, gets back a Schnorr-signed score, and compares to MIN_SCORE. The score is composed from observable irreversible work across four dimensions (social, access, vouch, economic), so a fresh sybil cannot grind it in a minute.

The full failure-mode table is in @powforge/mcp-l402-gate README.

Files

• server.js - the MCP server, ~110 lines.
• .env.example - copy to .env and fill in.
• package.json - depends on express and @powforge/mcp-l402-gate.

Links

• npm: @powforge/mcp-l402-gate
• Docs and pricing: powforge.dev/mcp
• Public DoI oracle: identity.powforge.dev

License

MIT.