Skip to main content

Native L402 Integration

Lightning Enable supports two integration shapes. Native mode is the one where your API stays exactly where it is — same domain, same auth, same observability — and Lightning Enable handles the payment protocol via a small middleware you drop into your existing app.

When to choose Native mode over Proxy mode​

Proxy modeNative mode
Setup time~5 minutes in the dashboardOne install + one line of middleware
Code changes to your APINoneAdd one middleware registration
Traffic flows through Lightning EnableYesNo — your domain, your servers
You can keep your existing authDifficult (Authorization header is consumed by L402)Yes
Custom observability / rate limitingLimitedFull control
Best forPublic APIs, experiments, no-existing-authCommercial APIs, anything with sensitive infrastructure

If your API has its own authentication, custom rate limiting, observability you don't want to lose, or is hosted somewhere you can't change DNS for — Native mode is the right answer.

The two halves of the protocol​

The L402 protocol has a consumer side and a producer side. Lightning Enable publishes packages for both:

SideAudiencePackages
ConsumerAgents / clients that pay for paid APIsl402-requests (Node), L402Requests (.NET), l402-requests (Python)
ProducerAPI providers that charge for their endpointsThe packages described on this page

If you're calling paid APIs from an agent, you want the consumer packages. If you're building a paid API that you want agents to pay for, you want the producer packages — that's what the rest of this page is about.

Two layers: SDK and middleware​

Each language ships two packages: a server SDK (raw HTTP client for our producer API) and a framework middleware (drop-in for your web framework, built on top of the SDK).

StackSDKFramework middleware
Node + TypeScriptl402-serverl402-express
.NETL402ServerL402Server.AspNetCore

What the SDK does​

The SDK wraps two Lightning Enable hosted endpoints:

  • POST /api/l402/challenges → createChallenge() → mints a Lightning invoice + macaroon
  • POST /api/l402/challenges/verify → verifyToken() → validates an incoming L402 credential

That's it. ~200 lines of typed HTTP-client glue. The SDK knows nothing about HTTP frameworks, routes, or middleware pipelines. You give it inputs, it calls Lightning Enable, you get outputs. Use the SDK directly if you're calling these from a background job, queue worker, serverless function, or anywhere that isn't a typical HTTP middleware.

What the middleware does​

The framework middleware sits on top of the SDK and handles all the wiring for the 90% case (an HTTP API that wants to charge per request):

  1. Read the Authorization: L402 <macaroon>:<preimage> header
  2. If absent → call createChallenge(), respond 402 Payment Required with the invoice
  3. If present → call verifyToken(). Valid → call next handler; invalid → respond 401

That's all it does — and it does it so you don't have to write the parse-call-respond dance in every paid route. Most merchants will only ever touch the middleware. The SDK is what the middleware imports under the hood.

Quick start by stack​

  • Express (Node.js) — npm install l402-express, then one line of app.use(l402({ apiKey, priceSats }))
  • ASP.NET Core (.NET) — dotnet add package L402Server.AspNetCore, then app.UseL402() + [L402(PriceSats = 100)] attribute
  • More stacks coming — FastAPI (Python) and Go (net/http) are next on the roadmap. Direct producer API calls work today in any language; see the Producer API Reference.

Architectural decisions baked into the SDKs​

These are intentional. Worth knowing what you're getting:

  • No protocol code on the client side. Macaroon signing, preimage hashing, payment-hash linking — all server-side at Lightning Enable. The SDK is HTTP-client glue. If the protocol evolves, the hosted endpoint changes; you don't update your code.

  • Verification via the hosted endpoint, not local key material. Every verifyToken call goes to /api/l402/challenges/verify. One round-trip per paid request (~50ms regional, ~200ms cross-continent). We don't distribute the L402 root key to merchants — that's centralized for security and for replay protection.

  • Token reuse within the validity window is a feature. Macaroon caveats (path, merchant ID, amount, expires) bound the token's validity. The producer API enforces some caveats unconditionally and others on opt-in:

    • merchant_id is always enforced server-side — Merchant A can never verify a token bound to Merchant B (cross-tenant IDOR guard).
    • expires is always enforced — a presented token past its window returns valid: false.
    • path is enforced when the integrator passes resource on the verify call; otherwise it's read out for the integrator to compare.
    • amount_sats is enforced when the integrator passes amountSats on the verify call; otherwise read out only.

    Within the token validity window (60 minutes by default via DefaultTokenValiditySeconds), the same paymentHash can be re-verified for the same resource — useful for an agent making many quick calls within one paid window. The invoice itself expires sooner (10 minutes default) but the token, once paid, remains valid for the full token-validity window. If your endpoint needs strict single-use semantics, track paymentHash locally in your handler. See Token reuse within the validity window for the full contract.

  • No credentials stored anywhere. Lightning Enable never asks for your upstream API credentials. The middleware never touches your authentication. Your secrets stay on your servers.

Prerequisites​

  • An active Lightning Enable subscription — Agentic Commerce — Individual ($99/month) or Agentic Commerce — Business ($299/month). Both include a 30-day free trial.
  • A payment provider account — Strike (recommended) or OpenNode — with your API key saved in Dashboard → Settings.
  • A Lightning Enable merchant API key. Generate it at Dashboard → Settings → API Keys.
  • An existing HTTP API (or a fresh one) on Node + Express or .NET + ASP.NET Core. Other stacks are coming; if you want to use the raw HTTP API today in another language, see the Producer API Reference.

What the merchant pays for​

The middleware is open-source MIT. The SDK is open-source MIT. Lightning Enable's value is the hosted protocol broker — the API endpoint that mints macaroons, signs them with our root key, verifies preimages, enforces caveats (merchant scoping always; path + amount on opt-in), and integrates with your Lightning wallet (Strike / OpenNode / LND / NWC).

Your Lightning Enable subscription pays for that broker, plus the dashboard for configuring it, plus the registry for letting agents discover your API. The middleware code itself is free for anyone to read, audit, and modify.

Next steps​