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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="LnBot.L402.AspNetCore" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="LnBot.L402.AspNetCore" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="LnBot.L402.AspNetCore" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add LnBot.L402.AspNetCore --version 1.1.0
                    
#r "nuget: LnBot.L402.AspNetCore, 1.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package LnBot.L402.AspNetCore@1.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=LnBot.L402.AspNetCore&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=LnBot.L402.AspNetCore&version=1.1.0
                    
Install as a Cake Tool

LnBot.L402.AspNetCore

NuGet License: MIT

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 pay
  • client.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

  • LnBot.L402 — Client-side auto-pay handler
  • LnBot — The .NET SDK this package is built on
  • @lnbot/l402 — TypeScript equivalent

License

MIT

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 115 10/24/2026
1.0.0 180 3/5/2026
0.2.0 141 2/27/2026
0.1.0 140 2/27/2026