🔒 local402

Lokale Ein-Befehl-Paywall für KI-Agenten

Verwandle jeden lokalen Server in Sekundenschnelle in eine zahlbare Ressource. Perfekt zum Testen von Agenten, die bezahlen müssen, bevor sie auf deine API oder dein MCP-Tool zugreifen können.

npx local402 --target http://localhost:3000 --price 0.001

Was ist das?

local402 setzt eine x402-artige HTTP 402 Payment Required-Paywall vor beliebige lokale HTTP-Server oder MCP-Tools — mit einem einzigen Befehl, null Konfiguration und ohne Blockchain.

Anfragen ohne Bezahlung erhalten ein sauberes 402. Anfragen, die „bezahlen“, werden direkt an deinen echten Server weitergeleitet. Das war's.

Es läuft standardmäßig im vollständig simulierten Modus: keine Wallets, kein Gas, keine externen Dienste, kein Warten. Nur sofortige, deterministische 402-Antworten, gegen die du lokal entwickeln und testen kannst.

agent ──▶  local402 (402 paywall)  ──▶  your server
             │
             └── no payment? → 402 Payment Required
                 paid?       → proxied response ✅

Related MCP server: 402-mcp

💸 Warum local402?

Agenten lernen, für Dinge zu bezahlen — API-Aufrufe, Tool-Aufrufe, Daten, Rechenleistung. Das x402-Protokoll macht HTTP-native Zahlungen Realität. Aber es gibt eine Lücke:

Wie testest du einen zahlenden Agenten, ohne echtes Geld auszugeben, ein Wallet aufzusetzen oder einen ganzen Payment-Stack zu verdrahten — und das jedes Mal?

Du willst keinen Facilitator bereitstellen und ein Testnet-Wallet aufladen, nur um zu prüfen, dass dein Agent eine 402 bemerkt und es mit Zahlung erneut versucht. Du willst eine Paywall, die du mit einem einzigen Befehl hochziehen und genauso schnell wieder abreißen kannst.

Das ist local402.

Verwende es, um:

• ✅ Testen, dass dein KI-Agent 402 verarbeitet und es mit einem x-payment-Header erneut versucht

• ✅ Eine „Pay-per-Call“-API oder ein MCP-Tool demonstrieren, ohne eine Chain zu berühren

• ✅ x402-Clientlogik offline, im Flugzeug oder in CI entwickeln

• ✅ Preise prototypisieren, bevor du dich auf echte Abrechnung festlegst

⚡ Schnellstart

Du musst es nicht einmal installieren.

# 1. Have any local server running (your API, MCP tool, whatever)
#    e.g. something on http://localhost:3000

# 2. Put a paywall in front of it
npx local402 --target http://localhost:3000 --price 0.001

local402 lauscht jetzt auf http://localhost:4020 und bewacht deinen Server.

# ❌ No payment → 402 Payment Required
curl -i http://localhost:4020/

# ✅ "Pay" → request is proxied to your real server
curl -i http://localhost:4020/ -H "x-payment: simulated"

Richte deinen Agenten auf http://localhost:4020 statt auf deinen echten Server aus und sieh zu, wie er lernt zu bezahlen. 🎉

🛠 Verwendung

local402 --target <url> [options]

Die Regel

• Kein x-payment-Header → 402 Payment Required (mit einem hilfreichen JSON-Body + Headern).

• Mit x-payment: simulated (oder paid) → die Anfrage wird an --target weitergeleitet und die echte Antwort kommt unverändert zurück.

Im simulierten Modus wird jeder nicht-leere x-payment-Wert akzeptiert — simulated und paid sind nur die kanonischen.

Beispiele

# Guard an MCP tool on a custom port, charge 0.01
local402 --target http://localhost:8787 --port 9000 --price 0.01

# Free status check — always open, never paywalled
curl http://localhost:4020/__local402

🔍 So funktioniert es

local402 ist ein winziger Reverse-Proxy mit einer Überzeugung: erst bezahlen, dann durchreichen.

                        ┌──────────────────────────────┐
                        │           local402            │
                        │        :4020 (paywall)        │
   ┌─────────┐          │                               │          ┌──────────────┐
   │  agent  │ ───────▶ │  x-payment header present?    │          │ your server  │
   │ / curl  │          │                               │          │  :3000       │
   └─────────┘          │   NO  ─▶ 402 Payment Required │          └──────────────┘
        ▲               │                               │                 ▲
        │               │   YES ─▶ proxy the request  ──┼─────────────────┘
        │               │         return real response  │                 │
        └───────────────┤◀──────────────────────────────┼─────────────────┘
              402 or proxied response                    │
                        └──────────────────────────────┘

Die unbezahlte Antwort (HTTP 402):

{
  "x402Version": 1,
  "error": "Payment Required",
  "message": "This resource costs 0.001 USD. Retry with header 'x-payment: simulated'.",
  "accepts": [
    {
      "scheme": "simulated",
      "network": "local",
      "maxAmountRequired": "0.001",
      "asset": "USD",
      "payTo": "local402-simulated",
      "resource": "/",
      "description": "local402 simulated paywall",
      "mimeType": "application/json"
    }
  ],
  "hint": "x-payment: simulated"
}

Antwort-Header bei einer 402:

HTTP/1.1 402 Payment Required
x-payment-required: true
x-payment-amount: 0.001
x-payment-asset: USD
x-payment-network: local
accept-payment: x-payment: simulated

Bei einer bezahlten Anfrage fügt local402 eine simulierte Abrechnungsquittung hinzu, damit dein Client den Ablauf Ende-zu-Ende verifizieren kann:

x-payment-response: <base64 JSON receipt with a sim txHash>

🗺 Roadmap

local402 startet bewusst einfach. Der Plan:

• v0.1 — Simulierter Modus. Sofortige, lokale, blockchain-freie 402-Paywall. (du bist hier)

• v0.2 — Echte x402-Abrechnung. Echte X-PAYMENT-Payloads über einen steckbaren Facilitator verifizieren.

• v0.3 — MCP-nativer Modus. Erstklassiges Paywalling für MCP-Tools/-Ressourcen, nicht nur HTTP.

• v0.4 — Preisgestaltung pro Route. Unterschiedliche Preise für verschiedene Pfade und Methoden.

• v0.5 — Nutzungs-Dashboard. Live-TUI von Anfragen, Zahlungen und Einnahmen.

Lust, mitzugestalten? Eröffne ein Issue.

🤝 Mitwirken

Beiträge, Ideen und Fehlermeldungen sind alle willkommen — das hier soll ein freundliches kleines Werkzeug sein.

git clone https://github.com/wushu75/local402.git
cd local402
npm install
npm run dev -- --target http://localhost:3000   # run from source
npm run build                                    # compile to dist/

1. Forke es 🍴

2. Erstelle einen Branch (git checkout -b feat/amazing-thing)

3. Committe deine Änderungen (git commit -m 'feat: amazing thing')

4. Pushe und eröffne einen PR

Kein Beitrag ist zu klein — selbst eine Tippfehler-Korrektur hilft.

📄 Lizenz

MIT © die local402-Mitwirkenden. Mach damit, was du willst.

⭐ Gib dem Repo einen Stern, falls das nützlich ist

Wenn dich local402 davor bewahrt hat, einen Payment-Stack nur zum Testen eines Agenten aufzusetzen, hinterlasse einen Stern — er hilft anderen Menschen wirklich, es zu finden.

⭐ Gib local402 auf GitHub einen Stern

Gebaut für die Agenten, die ihren Weg selbst bezahlen. 🔒