L402Server.AspNetCore 0.2.0

L402Server.AspNetCore

ASP.NET Core middleware for L402. Drop one line into any ASP.NET API to charge per-request Lightning payments. Built on L402Server — Lightning Enable handles invoices, macaroons, and payment verification; your API stays where it is.

Install

dotnet add package L402Server.AspNetCore

Target: .NET 8.0+.

30-second example

using L402Server.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddL402AspNetCore(opts =>
{
    opts.ApiKey = builder.Configuration["LightningEnable:ApiKey"]!;
});

var app = builder.Build();
app.UseRouting();
app.UseL402();
app.MapControllers();
app.Run();

Then mark any controller action with [L402(PriceSats = 100)] and that endpoint is gated behind a 100-sat L402 payment:

[ApiController]
[Route("api/premium")]
public class PremiumController : ControllerBase
{
    [HttpGet("weather")]
    [L402(PriceSats = 100)]
    public IActionResult Weather() => Ok(new { temp = 72 });
}

That's it. The middleware handles:

• Issuing 402 Payment Required with a Lightning invoice on unauthenticated requests
• Verifying Authorization: L402 <macaroon>:<preimage> on retries
• Stashing the verified credential in HttpContext.Items[L402HttpContextKeys.VerificationResult]

Endpoints without [L402] pass through ungated.

Pricing patterns

Per-route attributes (compile-time prices)

[HttpGet("forecast"), L402(PriceSats = 100)]
public IActionResult Forecast() => Ok(...);

[HttpGet("premium-llm"), L402(PriceSats = 500, Description = "GPT-4 backed")]
public IActionResult PremiumLlm() => Ok(...);

Global flat price (gates everything mounted under the middleware)

app.UseL402(opts => opts.DefaultPriceSats = 100);

Function-form pricing (variable per request)

app.UseL402(opts =>
{
    opts.PriceSelector = ctx => ValueTask.FromResult(
        ctx.Request.Query["model"] == "premium" ? 500 : 100);
});

Resolution order: PriceSelector > [L402(PriceSats)] attribute > DefaultPriceSats. If none → request passes through ungated.

The [L402] attribute

The attribute carries three properties:

[HttpGet("forecast")]
[L402(PriceSats = 100,                       // required, ≥ 1 (compile-time constant)
      Description = "Premium forecast",     // optional, shown in the payer's wallet
      Resource = "/canonical/forecast")]    // optional, overrides the macaroon-bound resource
public IActionResult Forecast() => Ok(...);

• PriceSats (required): price in satoshis. Attribute values are compile-time constants; for variable per-request pricing use PriceSelector on the middleware options.
• Description (optional): embedded in the Lightning invoice.
• Resource (optional): overrides the resource bound into the macaroon's path caveat. Defaults to the request path. Useful when several routes should share one canonical paid resource (e.g. normalizing route parameters out), since a token is only valid for the exact resource it was minted for.

The attribute can also be applied class-level to gate every action on a controller with one declaration. If both the controller and an action carry [L402], the action-level attribute wins for that endpoint (endpoint metadata is ordered least- to most-specific and the middleware reads the most specific match) — so a class-level default can be repriced per action:

[ApiController]
[Route("api/premium")]
[L402(PriceSats = 100)]   // every action below costs 100 sats
public class PremiumController : ControllerBase
{
    [HttpGet("weather")]
    public IActionResult Weather() => Ok(new { temp = 72 });

    [HttpGet("forecast")]
    public IActionResult Forecast() => Ok(new { rain = false });
}

Server-side path-caveat enforcement

Each macaroon is bound to the resource it was minted for. By default the middleware sends the resolved resource (same precedence as minting: [L402(Resource = ...)] > ResourceSelector > request path) with every verification call, so Lightning Enable rejects a token that was paid for a different path — replay protection across endpoints without writing a comparison yourself.

// To opt out (and do your own comparison against VerificationResult.Resource):
app.UseL402(opts => opts.EnforceResourceOnVerify = false);

Requires L402Server ≥ 0.2.0 (a transitive dependency of this package).

Verified credential on downstream handlers

[HttpGet("weather"), L402(PriceSats = 100)]
public IActionResult Weather(HttpContext ctx)
{
    var result = (VerificationResult)ctx.Items[L402HttpContextKeys.VerificationResult]!;
    _logger.LogInformation("Served {Resource} for {Sats} sats ({Hash})",
        result.Resource, result.AmountSats, result.PaymentHash);
    return Ok(new { temp = 72 });
}

Configuration

Two integration modes

Lightning Enable supports two integration shapes:

• Proxy mode — point Lightning Enable at your API URL; we forward authenticated requests on your behalf.
• Native mode — install this middleware in your existing API. Lightning Enable handles payment; your API handles everything else. This middleware is the Native mode for ASP.NET Core.

Documentation →

How the protocol works under the hood

Every paid request makes one round-trip to the Lightning Enable hosted API. The middleware never holds key material, never signs macaroons, never verifies preimages locally — all of that is in the hosted backend. The middleware itself is HTTP-client glue.

What you pay for with your Lightning Enable subscription: the protocol broker that lets this be one line of middleware.

Sibling packages

• L402Server — the SDK this middleware is built on. Use directly for non-ASP.NET-Core .NET hosts.
• L402Requests — consumer-side HTTP client. Auto-pays L402 challenges.

Contributing

Open source under MIT. Issues and PRs welcome.

License

MIT © Refined Element