01
FAILURE MODE
Spend is unbounded.
API keys are payment-blind. A leaked credential runs an inference loop for the entire billing cycle before anyone notices. Limits are bolted on. Damage is uncapped.
L402 / LIGHTNING / MAINNET
MCP + CLI
IN BUILD
Machines
pay machines
API keys were built for humans. AI agents are not human. Plannt is the Bitcoin-native access control layer for autonomous agents. Every request, a Lightning invoice. Every payment, a single-use credential.
01/THE PREMISE
02
FAILURE MODE
Symmetric, long-lived secret.
The same string that authenticates gets checked into a config file, pasted into a Slack thread, baked into a Docker image. API keys leak by default.
03
FAILURE MODE
Billing is bolted on.
Billing happens out-of-band, after the fact, against an invoice the agent never saw and never agreed to. Machines should not need an accountant.
∞
02/THE PROTOCOL / FIVE STEPS
01
Agent requests a protected endpoint. No credentials sent.
GET /v1/data Authorization: (none)
02
Server responds 402 with a BOLT11 invoice and a macaroon.
402 Payment Required invoice: lnbc1u1... macaroon: AgEDLn...
03
Agent pays the invoice over Lightning. Preimage returned as proof.
→ lightning.pay()
← preimage: a3f9...b21e
04
Agent retries with
Authorization: L402 macaroon:preimage.GET /v1/data Authorization: L402 macaroon:preimage
05
Server verifies
HMAC(root_key, payment_hash) == macaroon_id. Access granted. Token spent.200 OK
{ message: "Access granted." }
⚡
03/THE GATE / REFERENCE IMPLEMENTATION
METHOD
PATH
DESCRIPTION
PRICE
GET
/v1/data
Issues a 402 with invoice + macaroon. Paid retry returns the payload
100sats
GET
/status
Health check
public
∞
04/QUICK START / THREE STROKES
$ git clone https://github.com/HashRails/plannt-api $ cd plannt-api && npm install && node index.js $ curl -i localhost:3000/v1/data # no credentials. no headers. # the request itself is the trigger.
HTTP/1.1 402 Payment Required content-type: application/json { "error": "Payment Required", "macaroon": "AgEDLn...", "invoice": "lnbc1u1p..." }
$ curl -i localhost:3000/v1/data \ -H "Authorization: L402 <mac>:<preimage>" HTTP/1.1 200 OK { "message": "Access granted to protected Plannt data." }
⚡
05/WHY THIS IS SECURE
Credentials are ephemeral.
The credential is generated, used, and consumed inside a single request cycle. It exists for less than a second.
Tokens are single-use.
Every token expires the moment it verifies. The replay window is zero. The idle window is zero.
Every request is pre-paid.
Each call requires a discrete Lightning invoice settled before access. Spend is capped at the cost of one request.
Verification is stateless.
Pure cryptography. HMAC(root_key, payment_hash) == macaroon_id. Stateless. Horizontal. Fast.
∞
06/IN DEVELOPMENT / MCP + CLI
IN BUILD
NEXT
Plannt MCP
A Model Context Protocol server that lets Claude, Cursor, and any MCP-compatible agent call Plannt-gated endpoints natively. No middleware. No glue code. The agent discovers, pays, and verifies in a single tool call.
$claude mcp add plannt
IN BUILD
NEXT
Plannt CLI
A single-binary command-line client. Pay an L402 invoice from your terminal,
retry the request with the resulting credential, and pipe the response into
whatever you would pipe a curl response into. The fastest way to feel the protocol.
$plannt get https://your-app.fly.dev/v1/data
SEE THE ROADMAP→
v1.0.0 / OPEN SOURCE / MIT
Build something a machine can pay for.
The repo is open. The gate runs on any LND node. Start in the terminal you already have open.