Paygate

Spring Boot starter for Lightning payment-gated APIs

Paygate lets Spring Boot developers protect endpoints with a single annotation, issue HTTP 402 payment challenges, and accept Bitcoin Lightning credentials through L402 or the draft Payment authentication flow.

Start a technical prototype View on GitHub Read docs

Problem

Most API monetization stacks are built around accounts, subscriptions, and human checkout flows. Agent and machine clients need a protocol-native way to pay per request without custom billing infrastructure.

Solution

Paygate auto-configures Spring Boot filters, protocol handlers, Lightning backends, credential validation, and observability. Developers add `@PaymentRequired`, configure LNbits or LND, and unpaid requests receive a 402 challenge instead of protected content.

Why it matters

As agents consume more APIs directly, payment and authorization need to become programmable, metered, and machine-readable. Paygate gives Java teams a concrete path to sell API access over Lightning without building the payment protocol layer from scratch.

Proof in production

Reference Service / Real LNbits Settlement

Live

Paygate Agent Trust

A live reference service with real LNbits settlement shows the full unpaid request, Lightning invoice, paid retry, and signed JSON response loop.

Free catalog and quote endpoints before payment
Payment-gated trust report generation through Paygate
Real LNbits invoice settlement before retry
Ed25519-signed JSON response after payment

Open live service View on GitHub Read docs

Who it is for

Backend engineers
Spring Boot teams
API developers
Agent platform builders
AI infrastructure teams
Lightning application builders

Use cases

Protect premium API endpoints behind Lightning payments
Add pay-per-use pricing with `@PaymentRequired` annotations
Serve L402 and Payment challenges from the same endpoint
Use dynamic pricing for expensive AI or data operations
Integrate payment validation into Spring Security filter chains

Quickstart

Add payment gating to a Spring Boot endpoint

Paygate is publicly available as a Spring Boot starter for payment-gated APIs. The examples below show the released developer experience.

Install

Gradle first, Maven compatible

Gradle

dependencies {
    implementation("com.greenharborlabs:paygate-spring-boot-starter:0.1.4")
}

Maven

<dependency>
  <groupId>com.greenharborlabs</groupId>
  <artifactId>paygate-spring-boot-starter</artifactId>
  <version>0.1.4</version>
</dependency>

Protect an endpoint

@GetMapping("/trust/report")
@PaymentRequired(priceSats = 30)
TrustReport report(@RequestParam String domain) {
    return trustReports.generate(domain);
}

Unpaid request

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 invoice="<bolt11>", macaroon="<token>"
WWW-Authenticate: Payment invoice="<bolt11>", amount="30sat"

{
  "error": "payment_required",
  "retry": "pay invoice and repeat the request"
}

Lightning backend

paygate:
  backend: lnbits
  default-price-sats: 30
  lnbits:
    url: ${LNBITS_URL}
    api-key: ${LNBITS_API_KEY}
# backend: lnd is supported for node-direct deployments

Explore all 11 technical features

Single-dependency Spring Boot starter for Paygate auto-configuration
Annotation-driven endpoint protection with `@PaymentRequired`
Dual-protocol support for L402 and MPP with multiple `WWW-Authenticate` headers
LNbits and LND Lightning backend modules
Dynamic pricing through `PaygatePricingStrategy`
Spring Security integration with authentication provider, filter, and token support
Delegation caveats for path, method, and client IP restrictions
Micrometer metrics, Actuator health integration, and `/actuator/paygate` runtime status
Test mode for local development without a real Lightning node
Fail-closed behavior when the Lightning backend is unavailable
Macaroon V2 compatibility with Go macaroon tooling

Build with the lab

Build with Paygate

Have a focused use case for Paygate? Green Harbor Labs can help shape the integration or prototype.

Discuss Paygate Explore Harbor Mind CLI