Green Harbor Labs

Product

Open Source

Paygate

Payment infrastructure for machine-native APIs

Paygate gives services and machine clients both sides of an HTTP 402 payment flow: Spring Boot APIs issue L402 or MPP challenges, the Rust client applies local spend policy and pays over Lightning, and the request is retried with a scoped credential.

Start a technical prototypeView on GitHubRead 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.

Ecosystem

A complete payment loop

Use the projects independently or together: protect an API, pay from a machine client under explicit policy, and inspect the flow against a live service.

Server

Open Sourcev0.1.6

Paygate Spring Boot Starter

Annotation-driven payment gating for Spring Boot 4 APIs with L402 and MPP, Lightning backends, Spring Security, and fail-closed defaults.

  • Protect an endpoint with `@PaymentRequired`
  • Bind credentials to the exact request boundary
  • Run with LNbits or LND settlement backends
View on GitHubRead docs

Payer

Open Sourcev0.1.0 source

Paygate Client

A Rust CLI that validates payment challenges, enforces host and spend policy, pays through a configured backend, caches scoped credentials, and retries the request.

  • MPP-first with optional L402 support
  • Per-request limits, fee caps, and daily budgets
  • Isolated profiles for manager and worker agents
View on GitHubRead docs

Live reference service

Livev0.1.4

Paygate Agent Trust

A public service that sells signed agent trust reports and demonstrates the full challenge, Lightning settlement, paid retry, and receipt flow.

  • Free catalog and quote discovery
  • Real LNbits-backed settlement
  • Ed25519-signed reports with payment receipts
Open live serviceView on GitHubRead 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.6")
}
Maven
<dependency>
  <groupId>com.greenharborlabs</groupId>
  <artifactId>paygate-spring-boot-starter</artifactId>
  <version>0.1.6</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
  • Spring Boot 4 starter with annotation-driven `@PaymentRequired` endpoint protection
  • Dual-protocol L402 and MPP challenges through multiple `WWW-Authenticate` headers
  • Rust payer client with local request limits, fee caps, daily budgets, and host allowlists
  • Credential caching and isolated client profiles for manager and worker agents
  • LNbits and LND Lightning settlement backends
  • Credentials bound to HTTP method, registered path, raw query, and bounded request body
  • Authenticated MPP expiry and `Payment-Receipt` proof after successful validation
  • Dynamic pricing through `PaygatePricingStrategy` with replayable bounded request bodies
  • Spring Security integration with authenticated, verifier-approved attributes
  • Micrometer metrics, Actuator health and status, challenge rate limiting, and trusted-proxy controls
  • Fail-closed outages and strict canonical credential parsing with Macaroon V2 interoperability

Build with the lab

Build with Paygate

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

Discuss PaygateExplore Harbor Mind CLI