Skip to main content

​
l402-kit White Paper

Version 1.2 — May 2026

​
Abstract

HTTP 402 was reserved in 1996 for a payment mechanism that was never built. For twenty-five years, developers built workarounds — account registration flows, credit card processors, API key provisioning — each designed for human actors who can open a browser and fill out a form. None of them work for machines. l402-kit implements the L402 protocol: HTTP 402 Payment Required over the Bitcoin Lightning Network. An API caller, human or machine, pays a Lightning invoice and receives cryptographic proof of payment. The server verifies proof with a single hash comparison. No account. No API key. No human approval required. l402-kit is a family of L402 protocol implementations in TypeScript, Python, Go, and Rust. Open-source, custody-free, account-free. Each implementation does exactly what the protocol asks of it, and nothing more.

​
The Problem

HTTP was designed for human interactions: browsers, forms, sessions, accounts. API monetization inherited these assumptions and built workarounds around them. Stripe’s minimum transaction is $0.50 after fees. PayPal requires accounts on both sides. Monthly subscriptions bundle demand that is not bundled in reality. API keys require human provisioning, rotation, and billing cycles that cannot be automated. The gap became critical with the emergence of autonomous AI agents. An agent that discovers a new API at runtime cannot create an account, enter a card number, or navigate an OAuth flow. It can only make HTTP requests. If the API requires a pre-existing credential, the agent stops. The loop that was supposed to be autonomous is not. What was missing for twenty-five years is now implementable: a payment mechanism native to HTTP, requiring no prior relationship between client and server, settling in under a second, and producing a self-contained cryptographic proof the server verifies without a network call.

​
How l402-kit Works

The protocol is a standard HTTP exchange with one additional round trip:
  1. Request. Client sends a normal HTTP request.
  2. Challenge. Server responds with 402, a Lightning invoice, and a macaroon encoding the payment hash.
  3. Payment. Client pays the invoice. The Lightning Network delivers the preimage as settlement proof in under one second.
  4. Access. Client resends with Authorization: L402 <macaroon>:<preimage>. Server verifies SHA256(preimage) == paymentHash. No database lookup — pure cryptography.
The credential is stateless: it carries the payment hash and expiry inline and is verifiable by any instance of the middleware without coordination.

​
Architecture

l402-kit operates across three tiers. The operator’s application is unchanged; the middleware wraps routes. The Lightning provider is pluggable. Managed mode — operator provides a Lightning Address. ShinyDapps backend handles invoice creation and settlement. Fee: 0.3%. Sovereign mode — operator uses their own Lightning provider. Fee: 0%.

​
Quickstart

import { l402, ManagedProvider } from "l402-kit";

const lightning = ManagedProvider.fromAddress("you@blink.sv");
app.use("/api/data", l402({ priceSats: 10, lightning }));

​
The Seven Principles

These principles are constraints. A feature that violates them does not ship.
#PrincipleIn one line
1Minimal essenceThe middleware does the protocol, and nothing else.
2Auditability as a precondition for trustClosed-source financial middleware is a contradiction in terms.
3Operator sovereigntyThe operator holds the keys, chooses the provider, keeps the ledger.
4Truth as correspondenceWhat the docs state and what the code does are the same.
5Stability at the foundationHTTP and Lightning are long-lived. The middleware connecting them is treated accordingly.
6Composition, not constructionl402-kit composes existing primitives; it does not reinvent them.
7Adequacy to the nature of the problemMachine-to-machine payments require a solution built for machines.

​
Two Users. One Protocol.

“l402-kit is neutral infrastructure — it serves the human who wants to exit the banking system and the agent that never needed one.”
The sovereign operator monetizes their API without Stripe, without KYC, without intermediary. Sats arrive directly in their wallet. onEvent is opt-in — they never touch it. The autonomous agent operates without a human in the loop. Same protocol. Same three lines of code. But now with persistent identity, cryptographic audit trail, and emergent reputation — because without reputation, other agents won’t trust it. Different markets. Same protocol. The code is the same.

​
The Autonomous Agent Economy

HTTP was built for humans. L402 was built for machines. But there is a deeper implication that only becomes visible when you follow the protocol to its conclusion. An AI agent that operates inside the L402 protocol does not merely consume APIs. It can produce services, accumulate the proceeds, and use those proceeds to consume other services — without a human ever depositing a single satoshi. The loop is complete: Step 1 — Birth. The agent creates a Lightning wallet. Alby and LNbits are free, require no document, no bank account, no KYC. The agent has an address in seconds. Step 2 — Produce. The agent offers a service — text summarization, embeddings, data queries, compute tasks. It wraps that service with l402-kit middleware. Any caller pays automatically. The agent accumulates sats. Step 3 — Consume. With accumulated sats, the agent calls other L402-protected services using L402Client. It pays invoices, receives data, expands its capabilities. No human approves the transaction. Step 4 — Audit trail. Each transaction emits a signed CloudEvent (CloudEvents 1.0, HMAC-SHA256) carrying: agent identity, session, request causality, payment proof, timing, and behavioral context. The record is cryptographic — not a log, but a proof. Step 5 — Reputation emerges. Behavioral patterns accumulate in the LAW-N ledger (SAGEWORKS AI). Agents that pay consistently, respect budget constraints, and do not attempt proof reuse build reputation automatically — without any authority granting it. Agents that misbehave stop being able to access services. The system is self-regulating. No human approved the agent’s wallet. No human funded its first transaction. No human decided its reputation. The economic infrastructure is the protocol itself.

​
What this is not

This is not a blockchain. There is no token. There is no DAO. There is no governance vote. There is no whitelist. There is HTTP, Bitcoin Lightning, and cryptographic proof. The agent economy runs on infrastructure that existed before l402-kit — l402-kit is the missing protocol layer that makes it composable.

​
Why this matters now

Three things became true simultaneously in 2025–2026:
  1. Autonomous agents are real. LangChain, AutoGPT, Claude, and dozens of frameworks deploy agents that execute multi-step tasks without human approval at each step.
  2. Lightning wallets are free. Any software process can hold a Lightning address. No bank. No KYC. No minimum balance.
  3. L402 is implemented. l402-kit runs in TypeScript, Python, Go, and Rust — the four languages where agents are built.
The convergence is not theoretical. The infrastructure exists. What was missing was the protocol layer connecting them. That is l402-kit.
“l402-kit is not a payment gateway. It is the economic infrastructure for autonomous agents — the layer that makes machine-to-machine commerce possible without human intermediaries.”

​
Economic Model

The 0.3% fee is structurally aligned with developer success: when a developer earns nothing, the fee is zero.
TierCostWhat You Get
Free0.3% of payments receivedUnlimited calls, all SDKs, 7-day history
Pro9,000 sats/month ($9)Full history, CSV export, priority support
Founder1,000,000 sats one-time ($999)Lifetime Pro, direct maintainer access

​
Adoption

npm install l402-kit    # TypeScript
pip install l402kit     # Python
go get github.com/shinydapps/l402-kit/go@v1.10.0
cargo add l402kit       # Rust
For the complete technical specification — founding principles in full, design decisions with tradeoffs, expanded threat model, architectural properties, L402 vs x402 comparison, and versioning commitments — the Extended Edition is available at l402kit.com/whitepaper-extended (100 sats, served by l402-kit itself).
l402-kit is released under the MIT License · ShinyDapps · thiagoyoshiaki@gmail.com