◇Paywall

Official SDK · Java

x402 Spring Boot SDKSpring Boot 3 (Java 17+)

Thin x402 payment-gate filter for Spring Boot. Implements the frozen X402v1 wire contract. No payment logic in your app; relays to the platform's signed challenge/verify and fails closed (502, never serves paid content if the platform is unreachable).

Start as a developerView source on GitHub

Source is public on GitHub — official registry packages (npm · PyPI · Packagist · Go · Maven Central · NuGet · RubyGems) are coming. Each SDK implements the same frozen X402v1 wire contract.

Add pay-per-request to any Spring Boot route with one filter.

Quick start — 3 steps
  1. 01
    Create an account & register a route

    In the dashboard, add the route + price and issue a test or live API key.

  2. 02
    Install the SDK

    One package; the per-SDK command is below.

  3. 03
    Add one middleware

    Wrap the route — it now returns a signed x402 challenge and only serves paid content after the agent pays in USDC.

Install
Maven: dev.x402:x402-spring:0.1.0

Package id: dev.x402:x402-spring

Minimal usage
import dev.x402.spring.X402Filter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
class X402Setup {
    @Bean
    FilterRegistrationBean<X402Filter> premiumGate() {
        FilterRegistrationBean<X402Filter> reg =
                new FilterRegistrationBean<>(new X402Filter("/premium", "0.10"));
        reg.addUrlPatterns("/premium");
        return reg;
    }
}
Configuration
X402_API_KEYyour key idIdentifies the key (from the API Keys page).
X402_SECRETshown onceHMAC signing secret — shown once on key creation, stored encrypted.
X402_ENVsandbox | livesandbox = test key (synthetic settlement); live = real on-chain USDC.
X402_BASE_URLhttps://api.payrelayer.comPlatform base URL the SDK calls.

Use a test key with X402_ENV=sandbox: payments settle synthetically so you can build and CI-assert the full challenge → pay → verify → allow loop with zero real USDC, then flip to a live key — no code change.

Built to save you time
  • Thin client — no settlement, custody, or crypto code runs in your process. Keys, fees, the on-chain 95/5 split and payouts all live on the platform; you add one middleware.
  • Fails closed — if the platform is unreachable the gated route returns 502 and never serves paid content. It cannot accidentally give away a paid response.
  • One frozen wire contract — X402v1 is byte-identical across all 9 SDKs, enforced by a shared known-answer signature test, so behaviour can't drift between languages.
  • Signed, retried webhooks (payment.settled, payout.sent, payout.failed) + a live dashboard of requests, balances and payouts — reconciliation is done for you.
  • OncePerRequestFilter / Spring Boot auto-config.
  • Java 17+, Spring Boot 3.
FAQ
Do I need blockchain or crypto code?

No. The SDK is a thin HTTP client. Settlement, the 95/5 split and payouts happen on-chain on the platform side; you add one middleware and read the result.

Can it accidentally serve paid content for free?

No. It fails closed — if the platform is unreachable the gated route returns 502 and never serves the paid response.

How do I test without spending real USDC?

Use a test/sandbox key (X402_ENV=sandbox). Payments settle synthetically end-to-end; flip to a live key when you're ready, with no code change.

Is the payment format stable across languages?

Yes. X402v1 is a frozen wire contract, byte-identical across all 9 SDKs and enforced by a shared known-answer signature test.

Do I need Spring Security?

No — it's a standalone filter; add it to any route, Security-independent.

All SDKsHow it works