Skip to main content
Glama
ShinyDapps
by ShinyDapps

l402-kit

Füge jeder API Bitcoin Lightning Pay-per-Call hinzu. 3 Zeilen Code.

License: MIT Live Demo Tests l402-kit MCP server

▶ End-to-End-Demo ansehen — installieren → 402 → bezahlen → 200 OK


Live-Traktion

SDK

Version

Downloads

📦 TypeScript · npmjs.com/package/l402-kit

npm

npm total

🐍 Python · pypi.org/project/l402kit

pypi

pypi total

🦀 Rust · crates.io/crates/l402kit

crates

crates dls

🔌 VS Code Extension · marketplace

vscode ver

marketplace

🦫 Go · pkg.go.dev

go

go report



🇺🇸 Charge for your API in Bitcoin Lightning. 3 lines of code. 🇧🇷 Monetize sua API com Bitcoin Lightning. 3 linhas de código. 🇪🇸 Monetiza tu API con Bitcoin Lightning. 3 líneas de código. 🇨🇳 用 3 行代码,通过比特币闪电网络收费。 🇮🇳 अपने API को Bitcoin Lightning से 3 लाइनों में मोनेटाइज़ करें। 🇸🇦 اكسب من API الخاص بك عبر Bitcoin Lightning. 3 أسطر فقط. 🇫🇷 Monétisez votre API en Bitcoin Lightning. 3 lignes de code. 🇩🇪 Monetarisiere deine API mit Bitcoin Lightning. 3 Zeilen Code. 🇷🇺 Монетизируй свой API через Bitcoin Lightning. 3 строки кода. 🇯🇵 Bitcoin LightningでAPIを3行で収益化。 🇮🇹 Monetizza la tua API con Bitcoin Lightning. 3 righe di codice.

📖 Offizielle Dokumentation: 🇺🇸 · 🇧🇷 · 🇪🇸 · 🇨🇳 · 🇮🇳 · 🇸🇦 · 🇫🇷 · 🇩🇪 · 🇷🇺 · 🇯🇵 · 🇮🇹


Installation

npm install l402-kit        # TypeScript / Node.js / Express
pip install l402kit         # Python / FastAPI / Flask
go get github.com/shinydapps/l402-kit/go@v1.8.2   # Go / net/http / Chi / Gin
cargo add l402kit           # Rust / axum

KI-Agenten / LLMs: Siehe llms.txt für maschinenlesbare Anweisungen. Agenten-Discovery: /.well-known/agent.json · /.well-known/l402.json


Related MCP server: Bitcoin-MCP-Server

Für KI-Agenten

l402-kit ist die Zahlungsschicht für autonome Agenten. Agenten können ohne menschliches Eingreifen für APIs bezahlen.

System-Prompt-Schnipsel — füge dies jedem Agenten hinzu, um L402-Zahlungen zu ermöglichen:

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

Agent SDK Schnellstart:

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 (für Claude Desktop, Cursor und jeden MCP-kompatiblen Agenten):

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

Kompatibel mit: LangChain · OpenAI Agents · CrewAI · Vercel AI SDK · AutoGPT · Jedem MCP-Client

Protokoll-Unterstützung: L402 (Bitcoin Lightning) · x402 (USDC/Coinbase) kompatibel

Powered by L402-Kit


Funktionsweise

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

Schnellstart

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, Request
from l402kit import l402_required

app = FastAPI()

@app.get("/premium")
@l402_required(price_sats=100, owner_lightning_address="you@yourdomain.com")
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: "you@yourdomain.com",
    }, 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("you@yourdomain.com"));

    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();
}

Live testen

# Step 1 — triggers 402 + returns invoice
curl 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." }

▶ Interaktive Demo ausprobieren


Warum nicht Stripe?

Stripe

l402-kit

Mindestgebühr

$0.30

< 1 sat (~$0.001)

Abwicklungszeit

2–7 Tage

< 1 Sekunde

Rückbuchungen

Ja

Unmöglich — kryptografischer Nachweis

Erfordert Konto

Ja

Nein — jedes Lightning-Wallet

KI-Agenten-Support

Nein

Ja — 4 SDKs, nativ

Blockierte Länder

~50

0 — standardmäßig global

Umkehrbar

Ja

Nein — endgültig bei Erhalt

Open Source

Nein

Ja — MIT


Anbieter

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 deinen eigenen Node mit — implementiere das LightningProvider-Interface in 5 Zeilen:

import type { LightningProvider } from "l402-kit";

class MyNode implements LightningProvider {
  async createInvoice(amountSats: number) { /* return Invoice */ }
  async checkPayment(paymentHash: string) { /* return boolean */ }
}

Sicherheitsmodell

Invoice creation:  paymentHash = SHA256(preimage)
Client payment:    Lightning Network releases preimage to payer
API verification:  SHA256(preimage) == paymentHash  ✓
Replay protection: each preimage is marked used — works exactly once
Token expiry:      macaroons expire after 1 hour
  • Nicht fälschbar — SHA256 ist eine Einwegfunktion; ein Preimage kann nicht gefälscht werden

  • Keine Rückbuchungen — kryptografische Abwicklung, keine umkehrbare Kartenautorisierung

  • Replay-sicher — MemoryReplayAdapter (Entwicklung) oder RedisReplayAdapter (Produktion, Multi-Instanz)

  • 600+ automatisierte Tests über 5 Runtimes (TS, Python, Go, Rust, Cloudflare Workers) — produktionsreife Zuverlässigkeit für autonome Agenten-Workflows

  • Vollständig prüfbar — MIT, jede Zeile ist Open Source


VS Code Extension

Überwache jeden Sat in Echtzeit, ohne deinen Editor zu verlassen.

VS Code Marketplace

  • ⚡ Live-Zahlungs-Feed pro Endpunkt

  • 📊 Balkendiagramm — 1T / 7T (kostenlos) · 30T / 1J / ALLE (Pro)

  • 🌍 11 Sprachen integriert

  • 🎨 Hell / Dunkel / Auto-Design

  • 🔧 Keine Konfiguration — einfach deine Lightning-Adresse festlegen


Lightning-Adresse erhalten (kostenlos)

Registriere dich unter dashboard.blink.sv — kostenlos, keine Kreditkarte, sofort einsatzbereit. Deine Adresse: deinname@deinedomain.com

Andere Wallets: Wallet of Satoshi · Phoenix · Zeus · Alby



MIT — frei nutzen, frei bauen.

Bitcoin kennt keine Grenzen.

Entwickelt mit ⚡ von ShinyDapps

Doku · Demo · VS Code · npm

Available Tools

4 tools
l402_balanceCheck Lightning budgetA
Read-onlyIdempotent

Returns the remaining Bitcoin Lightning budget for this MCP session. Use this before calling l402_fetch to confirm you have enough sats — avoids wasted attempts when budget is exhausted. Returns: ' sats remaining of total (spent: sats)'. Read-only — does not trigger any payment or side effect. Budget is set at server startup via BUDGET_SATS (default: 1000 sats ≈ $0.60); to increase it, restart the MCP server.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint and idempotentHint. Description adds that it doesn't trigger payment or side effects, and explains budget is set at startup via BUDGET_SATS (default 1000 sats). Adds useful context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: first states main function, second gives usage guidance, third provides return format and budget details. No wasted words, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema but description explicitly shows return format. Covers purpose, usage, behavior, and budget configuration. Complete for a simple, param-less tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has no parameters (100% coverage), so description doesn't need to add param info. Baseline 4 for 0 params; description is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns the remaining Lightning budget for the MCP session, specifying the verb 'returns' and resource 'remaining Bitcoin Lightning budget'. It distinguishes from siblings by mentioning usage before l402_fetch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this before calling l402_fetch to confirm you have enough sats — avoids wasted attempts when budget is exhausted.' Also notes it's read-only with no side effects.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

l402_fetchFetch L402-protected URLA

Fetch a URL that may require a Bitcoin Lightning payment (L402 protocol). Side effect: deducts sats from the session budget when a payment is required — check l402_balance first if budget is limited. Flow: sends request → if 402 received, pays the Lightning invoice (1 attempt) → retries once with payment proof → returns response body as text. Fails with error if: budget is exhausted, URL is unreachable, or the Lightning payment fails. Do NOT use for regular (non-L402) URLs — use a standard fetch tool instead. Do NOT use if l402_balance shows 0 sats remaining.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to fetch (http or https)
methodNoHTTP method — GET, POST, PUT, DELETE, PATCH. Default: GET
bodyNoRequest body as string (for POST/PUT requests)
headersNoAdditional HTTP request headers as key-value pairs

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses side effects (deducts sats), detailed flow (request, 402 handling, payment, retry), and failure modes (budget exhaustion, unreachable, payment failure). Annotations only provide readOnlyHint=false, so description fully covers behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with key side effect, concise sentences, well-organized flow and exclusions. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all necessary context: purpose, side effect, prerequisite checks, step-by-step flow, error conditions, and exclusions. Without an output schema, it states the return type ('response body as text'). Complete for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all parameters. The description adds no extra parameter-level detail; it focuses on overall behavior. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches an L402-protected URL with payment side effects. It distinguishes from siblings by mentioning l402_balance and explicitly says not to use for non-L402 URLs, advising a standard fetch tool instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: check l402_balance first if budget limited, do not use if balance is 0, and use standard fetch for regular URLs. Describes the flow and failure conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

l402_set_budgetCheck budget statusA
Read-onlyIdempotent

Returns the session budget cap configured at startup (via BUDGET_SATS env var). Use this to confirm what hard spending limit is in effect — useful at the start of a session before making any API calls. Read-only: this tool CANNOT set or change the budget at runtime. To raise or lower the cap, stop and restart the MCP server with a different BUDGET_SATS value. For remaining balance during a session, use l402_balance instead.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint and idempotentHint. Description adds that it's read-only, cannot set budget, and details the source env var BUDGET_SATS and immutability during runtime. This adds valuable context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is four sentences, front-loaded with main purpose. Each sentence adds value: purpose, when-to-use, limitation, and sibling reference. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, clear annotations, and explicit description of what it returns and limitations, the tool is well-described for an agent. Lacks output format but it's a simple read-only query; still complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has no parameters, so schema description coverage is 100% vacuously. Baseline for 0 parameters is 4. Description does not need to add parameter info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'returns the session budget cap configured at startup', uses specific verb 'Returns' and resource 'session budget cap'. It distinguishes from sibling l402_balance which tracks remaining balance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use: 'useful at the start of a session before making any API calls'. It also says what not to use for: 'CANNOT set or change the budget', and provides alternative (restart server). Distinguishes from l402_balance for remaining balance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

l402_spending_reportLightning spending reportA
Read-onlyIdempotent

Returns a full audit of all Bitcoin Lightning payments made in this MCP session. Includes: total sats spent, remaining budget, sats spent per domain, and chronological transaction list (timestamp + sats + URL). Use this instead of l402_balance when you need to know which APIs were called and how much each cost, not just the remaining balance. Read-only — does not trigger any payment or side effect. Returns '(none yet)' for domains and transactions if no payments have been made this session.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint true; description reinforces no side effects and adds details about return format for no payments.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, well-structured sentence with bullet-like details; front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, description fully explains what it returns, when to use, and read-only nature.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters in schema; baseline 4 per rules. Description adds no parameter info needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a full audit of Lightning payments, listing specific fields and distinguishing it from sibling l402_balance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use this tool instead of l402_balance ('when you need to know which APIs were called and how much each cost'), and declares it read-only.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updates
    • Addedl402_balance
    • Addedl402_fetch
    • Addedl402_set_budget
    • Addedl402_spending_report

TDQS

A4.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: checking remaining budget, fetching with optional payment, viewing the budget cap, and obtaining a spending audit. There is no overlap in functionality.

Naming Consistency4/5

All tools share the consistent 'l402_' prefix and use snake_case, but the naming pattern varies between noun (balance, spending_report) and verb (fetch, set_budget). This minor inconsistency prevents a perfect score.

Tool Count5/5

With 4 tools, the server is well-scoped for its purpose: managing an L402 payment session. Each tool is essential and none are extraneous.

Completeness5/5

The tool set covers all core operations for an L402 session: checking budget, fetching with automatic payment, viewing the budget cap, and auditing spending. There are no obvious gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    MCP server that enables AI agents to make autonomous Bitcoin Lightning Network payments using the L402 protocol. Agents can pay for API access, purchase resources, and complete transactions without human intervention — invoice comes in, sats go out, done.
    17
    9
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    Bitcoin-powered AI tools via Lightning Network micropayments (L402). Image generation, text generation, video, music, speech, 3D models, file conversion, and SMS — no signup or API keys required.
    49
    51 npm
    2
    MIT