Java SDK

The T402 Java SDK provides a complete implementation of the t402 payment protocol for Java applications, with first-class support for Spring Boot.

Installation

<dependency>
    <groupId>io.t402</groupId>
    <artifactId>t402</artifactId>
    <version>1.0.0</version>
</dependency>

Features

Feature	Status
Core Client	✅
Core Server	✅
Facilitator Client	✅
EVM Mechanism	✅
Spring Boot Integration	✅
Servlet Filter	✅

Quick Start

Spring Boot (Recommended)

The easiest way to use T402 in a Spring Boot application is with auto-configuration.

1. Add configuration to application.yml:

t402:
  enabled: true
  facilitator-url: https://facilitator.t402.io
  network: eip155:8453
  pay-to: "0xYourReceiverAddress"
  asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  token-name: "USD Coin"
  token-version: "2"

2. Create a protected endpoint:

@RestController
public class ApiController {
 
    @GetMapping("/api/premium")
    public Map<String, String> premiumContent() {
        // This endpoint is automatically protected
        return Map.of("data", "Premium content!");
    }
}

The PaymentFilter is automatically registered for /api/* endpoints.

Manual Setup

For non-Spring applications or custom configurations:

import io.t402.server.PaymentFilter;
import io.t402.client.HttpFacilitatorClient;
 
// Create facilitator client
FacilitatorClient facilitator = new HttpFacilitatorClient(
    "https://facilitator.t402.io"
);
 
// Create payment filter
PaymentFilter filter = new PaymentFilter(facilitator);
 
// Register with your servlet container
FilterRegistration.Dynamic registration = servletContext.addFilter("t402", filter);
registration.addMappingForUrlPatterns(
    EnumSet.of(DispatcherType.REQUEST),
    true,
    "/api/*"
);

Client Usage

EVM Payments

The EvmSigner class provides EIP-3009 TransferWithAuthorization signing:

import io.t402.crypto.EvmSigner;
import io.t402.client.T402HttpClient;
 
// Create EVM signer for USDC on Base
EvmSigner signer = EvmSigner.fromPrivateKey(
    "0xYourPrivateKey",
    8453,                                              // Base chain ID
    "USD Coin",                                        // Token name
    "2",                                               // Token version
    "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"       // USDC address
);
 
// Create HTTP client
T402HttpClient client = new T402HttpClient(signer);
 
// Make a payment request
BigInteger amount = BigInteger.valueOf(1_000_000); // 1 USDC
HttpResponse<String> response = client.get(
    URI.create("https://api.example.com/premium"),
    amount,
    "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "0xReceiverAddress"
);

Manual Signing

For more control over the signing process:

import io.t402.crypto.EvmSigner;
import org.web3j.crypto.Credentials;
 
// Create credentials from private key
Credentials credentials = Credentials.create("0xYourPrivateKey");
 
// Create signer
EvmSigner signer = new EvmSigner(
    credentials,
    8453,                                              // Chain ID
    "USD Coin",                                        // Token name
    "2",                                               // Version
    "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"       // Token address
);
 
// Build authorization payload
Map<String, Object> payload = new HashMap<>();
payload.put("from", signer.getAddress());
payload.put("to", "0xRecipientAddress");
payload.put("value", "1000000");                       // Amount in atomic units
payload.put("validAfter", "0");
payload.put("validBefore", String.valueOf(System.currentTimeMillis() / 1000 + 3600));
payload.put("nonce", "0x" + generateRandomNonce());
 
// Sign with EIP-712
String signature = signer.sign(payload);
// Returns: 0x-prefixed hex signature (r || s || v)

Supported Networks

Network	Chain ID	CAIP-2 Identifier
Ethereum Mainnet	1	`eip155:1`
Base	8453	`eip155:8453`
Base Sepolia	84532	`eip155:84532`
Arbitrum One	42161	`eip155:42161`
Optimism	10	`eip155:10`
Polygon	137	`eip155:137`

API Reference

Core Classes

Class	Description
`T402HttpClient`	HTTP client with automatic payment header handling
`PaymentFilter`	Jakarta Servlet filter for payment-protected endpoints
`FacilitatorClient`	Interface for facilitator communication
`HttpFacilitatorClient`	HTTP implementation of FacilitatorClient

Crypto Classes

Class	Description
`CryptoSigner`	Interface for signing payment payloads
`EvmSigner`	EIP-3009 signing implementation using Web3j

Spring Boot

Class	Description
`T402AutoConfiguration`	Auto-configuration for Spring Boot
`T402Properties`	Configuration properties (`t402.*`)

Models

Class	Description
`PaymentPayload`	Payment header structure
`PaymentRequirements`	Payment requirements for an endpoint
`Authorization`	EIP-3009 authorization structure
`VerificationResponse`	Facilitator verification response
`SettlementResponse`	Facilitator settlement response

Configuration Properties

Property	Description	Default
`t402.enabled`	Enable T402 integration	`false`
`t402.facilitator-url`	Facilitator service URL	`https://facilitator.t402.io`
`t402.network`	Network identifier (CAIP-2)	`eip155:8453`
`t402.pay-to`	Payment receiver address	-
`t402.asset`	Token contract address	-
`t402.token-name`	EIP-712 token name	`USD Coin`
`t402.token-version`	EIP-712 token version	`2`
`t402.scheme`	Payment scheme	`exact`
`t402.max-timeout-seconds`	Max payment timeout	`3600`

Error Handling

Payment Required (402)

When payment is required but not provided:

{
  "t402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xReceiverAddress"
    }
  ],
  "error": "missing payment header"
}

Verification Failed

{
  "error": "Payment verification failed: invalid signature"
}

Requirements

Java 17+
Jakarta Servlet API 6.0+ (for servlet filter)
Spring Boot 3.x (for auto-configuration)

Dependencies

The SDK includes:

Web3j - Ethereum library for EIP-712 signing
Jackson - JSON processing
Spring Boot (optional) - Auto-configuration support