LnBot.L402.AspNetCore
1.1.0
dotnet add package LnBot.L402.AspNetCore --version 1.1.0
NuGet\Install-Package LnBot.L402.AspNetCore -Version 1.1.0
<PackageReference Include="LnBot.L402.AspNetCore" Version="1.1.0" />
<PackageVersion Include="LnBot.L402.AspNetCore" Version="1.1.0" />
<PackageReference Include="LnBot.L402.AspNetCore" />
paket add LnBot.L402.AspNetCore --version 1.1.0
#r "nuget: LnBot.L402.AspNetCore, 1.1.0"
#:package LnBot.L402.AspNetCore@1.1.0
#addin nuget:?package=LnBot.L402.AspNetCore&version=1.1.0
#tool nuget:?package=LnBot.L402.AspNetCore&version=1.1.0
LnBot.L402.AspNetCore
L402 Lightning payment middleware for ASP.NET Core — paywall any API in one line. Built on ln.bot.
Protect ASP.NET Core routes behind L402 paywalls with middleware, [L402] attributes, or endpoint filters. Includes the LnBot.L402 client package.
What is L402?
L402 is a protocol built on HTTP 402 Payment Required. It enables machine-to-machine micropayments over the Lightning Network — ideal for API monetization, AI agent tool access, and pay-per-request data feeds.
Install
dotnet add package LnBot.L402.AspNetCore
This includes the client package (LnBot.L402) — no need to install both.
Quick Start
Middleware pipeline
using LnBot;
using LnBot.L402;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton(new LnBotClient("uk_..."));
var app = builder.Build();
app.UseL402Paywall("/api/premium", new L402Options
{
Price = 10,
Description = "API access",
});
app.MapGet("/api/premium/data", () => Results.Ok(new { data = "premium content" }));
app.MapGet("/api/free/health", () => Results.Ok(new { status = "ok" }));
app.Run();
Controller attribute
using LnBot.L402;
[ApiController]
[Route("api/[controller]")]
public class WeatherController : ControllerBase
{
[L402(Price = 50, Description = "Weather forecast")]
[HttpGet("forecast")]
public IActionResult GetForecast()
=> Ok(new { forecast = "sunny" });
}
Minimal API endpoint filter
app.MapGet("/api/premium/data", () => Results.Ok(new { data = "premium" }))
.AddEndpointFilter(new L402EndpointFilter(price: 10, description: "API access"));
Dynamic pricing
app.UseL402Paywall("/api/dynamic", new L402Options
{
WalletId = "wal_...",
PriceFactory = context =>
{
if (context.Request.Path.StartsWithSegments("/api/dynamic/bulk"))
return Task.FromResult(50);
return Task.FromResult(5);
}
});
One token, one request
By default each payment buys one request. Every challenge carries two caveats, lnbot_path=<path> and lnbot_price=<sats>, so the token it produces only opens the route it was issued for, at that price or less. A holder can add caveats to a macaroon but never remove them, so a token can't be widened. Tokens expire after an hour unless you set ExpirySeconds, and a spent token is remembered until then.
Spent tokens are remembered in memory by default. If your API runs on more than one instance, register one ISpentTokenStore they all share, or a token spent on one instance could be spent again on another:
using StackExchange.Redis;
public sealed class RedisSpentTokenStore(IConnectionMultiplexer redis) : ISpentTokenStore
{
// SET NX with an expiry: true only for the first caller
public Task<bool> ClaimAsync(string paymentHash, TimeSpan ttl, CancellationToken cancellationToken = default) =>
redis.GetDatabase().StringSetAsync($"l402:spent:{paymentHash}", "1", ttl, When.NotExists);
}
builder.Services.AddSingleton<IConnectionMultiplexer>(ConnectionMultiplexer.Connect("localhost"));
builder.Services.AddSingleton<ISpentTokenStore, RedisSpentTokenStore>();
A token is spent when the request reaches your endpoint, even if the endpoint then fails.
Passes: Reuse = true
For "pay once, use for an hour", let tokens be reused until they expire. A pass carries lnbot_pass=<prefix> and lnbot_price=<sats> caveats instead: it opens any route under the paywall's path prefix (or the endpoint's route, for the attribute and filter), at that price or less. Single-use tokens don't open a pass route, and passes don't open single-use routes:
app.UseL402Paywall("/api/pass", new L402Options
{
WalletId = "wal_...",
Price = 500,
Reuse = true,
ExpirySeconds = 3600, // without it, a reusable token never expires
});
The [L402] attribute takes Reuse = true too, and L402EndpointFilter takes reuse: true.
How It Works
The middleware makes two SDK calls:
client.Wallet(walletId).L402.CreateChallengeAsync()— creates an invoice + macaroon when a client needs to payclient.Wallet(walletId).L402.VerifyAsync()— verifies an L402 authorization token when a client presents one
Then it checks that the token was issued for this route and price, and marks it spent (unless Reuse is set).
All L402 logic — macaroon creation, signature verification, preimage checking — lives in the ln.bot API. Zero crypto dependencies.
Requirements
- .NET 8+
- An ln.bot API key — create a wallet to get one
Related
LnBot.L402— Client-side auto-pay handlerLnBot— The .NET SDK this package is built on@lnbot/l402— TypeScript equivalent
Links
- ln.bot — website
- Documentation
- L402 specification
- GitHub
License
MIT
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net8.0
- LnBot.L402 (>= 1.1.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.