L402 Kit

Install

npm install l402-kit        # TypeScript / Node.js / Expresspip install l402kit         # Python / FastAPI / Flaskgo get github.com/shinydapps/l402-kit/[email protected]   # Go / net/http / Chi / Gincargo add l402kit           # Rust / axum

AI Agents / LLMs: See llms.txt for machine-readable instructions. Agent discovery: /.well-known/agent.json · /.well-known/l402.json

For AI Agents

l402-kit is the payment layer for autonomous agents. Agents can pay for APIs without human intervention.

System prompt snippet — add this to any agent to enable L402 payments:

You have access to paid APIs via the L402 protocol.When you call an API that returns HTTP 402, use the L402Client from l402-kitto pay automatically with Bitcoin Lightning.Budget limit: {BUDGET_SATS} sats per session. Never exceed this limit.

Agent SDK quickstart:

import { l402Client, buildWallet } from "l402-kit/agent";
const client = l402Client({  wallet: buildWallet(process.env), // auto-detects BLINK_API_KEY or ALBY_TOKEN  budgetSats: 1000,});
const data = await client.fetch("https://api.example.com/paid-endpoint");

MCP Server (for Claude Desktop, Cursor, and any MCP-compatible agent):

{  "mcpServers": {    "l402-kit": {      "command": "npx",      "args": ["l402-kit-mcp"],      "env": { "BLINK_API_KEY": "your-key" }    }  }}

Compatible with: LangChain · OpenAI Agents · CrewAI · Vercel AI SDK · AutoGPT · Any MCP client

Protocol support: L402 (Bitcoin Lightning) · x402 (USDC/Coinbase) compatible

[Powered by L402-Kit]

How it works

1. Client calls your API       ↓2. API returns  HTTP 402 + BOLT11 invoice + macaroon       ↓3. Client pays  (any Lightning wallet, < 1 second, any country)       ↓4. Client sends Authorization: L402 <macaroon>:<preimage>       ↓5. API verifies SHA256(preimage) == paymentHash  ✓       ↓6. HTTP 200 OK + your data
── Fee flow (managed mode) ─────────────────────────────────   Payment → 99.7% → your Lightning Address  (instant)           →  0.3% → ShinyDapps

Quickstart

TypeScript

import express from "express";import { l402, AlbyProvider } from "l402-kit";
const app = express();
const lightning = new AlbyProvider(process.env.ALBY_TOKEN!);
app.get("/premium", l402({ priceSats: 100, lightning }), (_req, res) => {  res.json({ data: "Payment confirmed." });});
app.listen(3000);

Python

from fastapi import FastAPI, Requestfrom l402kit import l402_required
app = FastAPI()
@app.get("/premium")@l402_required(price_sats=100, owner_lightning_address="[email protected]")async def premium(request: Request):    return {"data": "Payment confirmed."}

Go

package main
import (    "fmt"    "net/http"    l402kit "github.com/shinydapps/l402-kit/go")
func main() {    http.Handle("/premium", l402kit.Middleware(l402kit.Options{        PriceSats:             100,        OwnerLightningAddress: "[email protected]",    }, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {        fmt.Fprintln(w, `{"data": "Payment confirmed."}`)    })))    http.ListenAndServe(":8080", nil)}

Rust

use axum::{middleware, routing::get, Router};use l402kit::{l402_middleware, Options};use std::sync::Arc;
#[tokio::main]async fn main() {    let opts = Arc::new(Options::new(100).with_address("[email protected]"));
    let app = Router::new()        .route("/premium", get(|| async { "Payment confirmed." }))        .route_layer(middleware::from_fn_with_state(opts, l402_middleware));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();    axum::serve(listener, app).await.unwrap();}

Test it live

# Step 1 — triggers 402 + returns invoicecurl http://localhost:3000/premium# ← { "error": "Payment Required", "invoice": "lnbc1u...", "macaroon": "eyJ..." }
# Step 2 — pay the invoice with any Lightning wallet, then:curl http://localhost:3000/premium \  -H "Authorization: L402 <macaroon>:<preimage>"# ← { "data": "Payment confirmed." }

▶ Try the interactive demo

Why not Stripe?

Providers

import { BlinkProvider, OpenNodeProvider, LNbitsProvider } from "l402-kit";
// Blink (recommended — free, instant setup)const provider = new BlinkProvider(process.env.BLINK_API_KEY!, process.env.BLINK_WALLET_ID!);
// OpenNode (production, custodial)const provider = new OpenNodeProvider(process.env.OPENNODE_KEY!);
// LNbits (self-hosted)const provider = new LNbitsProvider(process.env.LNBITS_KEY!, "https://your.lnbits.host");

Bring your own node — implement the LightningProvider interface in 5 lines:

import type { LightningProvider } from "l402-kit";
class MyNode implements LightningProvider {  async createInvoice(amountSats: number) { /* return Invoice */ }  async checkPayment(paymentHash: string) { /* return boolean */ }}

Security model

Invoice creation:  paymentHash = SHA256(preimage)Client payment:    Lightning Network releases preimage to payerAPI verification:  SHA256(preimage) == paymentHash  ✓Replay protection: each preimage is marked used — works exactly onceToken expiry:      macaroons expire after 1 hour

• Unforgeable — SHA256 is a one-way function; you cannot fake a preimage
• No chargebacks — cryptographic settlement, not reversible card auth
• Replay-safe — MemoryReplayAdapter (dev) or RedisReplayAdapter (production, multi-instance)
• 600+ automated tests across 5 runtimes (TS, Python, Go, Rust, Cloudflare Workers) — production-grade reliability for autonomous agent workflows
• Fully auditable — MIT, every line open source

VS Code Extension

Monitor every sat in real-time without leaving your editor.

[VS Code Marketplace]

• ⚡ Live payment feed per endpoint
• 📊 Bar chart — 1D / 7D (free) · 30D / 1Y / ALL (Pro)
• 🌍 11 languages built-in
• 🎨 Light / dark / auto theme
• 🔧 Zero config — just set your Lightning Address

Get a Lightning Address (free)

Sign up at dashboard.blink.sv — free, no credit card, instant. Your address: [email protected]

Other wallets: Wallet of Satoshi · Phoenix · Zeus · Alby

Links