Java SDK Reference#

<dependency>
  <groupId>com.okx</groupId>
  <artifactId>x402-java-jakarta</artifactId>   <!-- or x402-java-javax -->
  <version>1.0.0</version>
</dependency>

String network = "eip155:196";

public class ResourceInfo {
    public String url;          // Resource URL
    public String description;  // Description
    public String mimeType;     // MIME
}

public class PaymentRequirements {
    public String scheme;             // "exact" | "aggr_deferred"
    public String network;            // "eip155:196"
    public String amount;             // Atomic-unit string
    public String payTo;              // Recipient EOA
    public int    maxTimeoutSeconds;  // Signature validity
    public String asset;              // Token contract address
    public Map<String, Object> extra; // Scheme-specific fields
}

public class PaymentRequired {
    public int x402Version = 2;
    public String error;
    public ResourceInfo resource;
    public List<PaymentRequirements> accepts;
    public Map<String, Object> extensions;
}

public class PaymentPayload {
    public int x402Version = 2;
    public ResourceInfo resource;
    public PaymentRequirements accepted;     // The selected accepts[i]
    public Map<String, Object> payload;      // Scheme-specific signed payload
    public Map<String, Object> extensions;

    public String toHeader();                          // base64(JSON)
    public static PaymentPayload fromHeader(String);   // Reverse decode
}

{
  "signature": "0x...",
  "authorization": {
    "from": "0xBuyerEOA",
    "to":   "0xSellerEOA",
    "value": "10000",
    "validAfter":  "0",
    "validBefore": "1700000000",
    "nonce": "0x..."
  }
}

{
  "signature": "0x...",
  "authorization": {
    "from": "0xAAWalletAddress",
    "to":   "0xSellerEOA",
    "value": "10000",
    "validAfter":  "0",
    "validBefore": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
    "nonce": "0x..."
  }
}

public class VerifyResponse {
    public boolean isValid;
    public String  invalidReason;
    public String  invalidMessage;
    public String  payer;
    public Map<String, Object> extensions;
}

public class SettleResponse {
    public boolean success;
    public String  errorReason;
    public String  errorMessage;
    public String  payer;
    public String  transaction;          // exact: tx hash; aggr_deferred: ""
    public String  network;
    public String  amount;               // upto scheme: actual settled amount
    public String  status;               // "pending" | "success" | "timeout"
    public Map<String, Object> extensions;
}

public class SupportedKind {
    public int x402Version = 2;
    public String scheme;
    public String network;
    public Map<String, Object> extra;
}

public class SupportedResponse {
    public List<SupportedKind> kinds;
    public List<String> extensions;
    public Map<String, List<String>> signers;
}

import com.okx.x402.server.PaymentInterceptor;
import com.okx.x402.server.PaymentProcessor;

PaymentInterceptor interceptor = PaymentInterceptor.create(
        facilitator,                         // FacilitatorClient
        Map.of("GET /api/data", route));     // routes

// Get the underlying processor to configure hooks / executor
interceptor.processor()
           .settleExecutor(settlePool)
           .onAfterSettle((p, r, resp) -> auditLog.write(resp));

public static class RouteConfig {
    public String  scheme            = "exact";   // "exact" | "aggr_deferred"
    public String  network;                       // REQUIRED: "eip155:196"
    public String  payTo;                         // REQUIRED: recipient EOA
    public String  price;                         // "$0.01" or "10000"
    public String  asset;                         // Empty → AssetRegistry default (USDT0)
    public int     maxTimeoutSeconds = 86400;     // Signature validity, default 1 day
    public DynamicPrice priceFunction;            // Dynamic pricing (computed per request)
    public List<AcceptOption> accepts;            // Used for multi-token / multi-scheme; overrides scheme/price/asset
    public boolean syncSettle;                    // Wait for on-chain confirmation before returning
    public boolean asyncSettle;                   // Background settle, requires settleExecutor
}

@FunctionalInterface
public interface DynamicPrice {
    String resolve(X402Request request);   // Returns USD/atomic-unit string
}

public class AcceptOption {
    public String scheme;
    public String network;             // Empty inherits route.network
    public String payTo;               // Empty inherits route.payTo
    public String price;
    public DynamicPrice priceFunction;
    public String asset;               // Empty → AssetRegistry default
    public int    maxTimeoutSeconds;
    public Map<String, Object> extra;

    public static Builder builder();   // Chainable
}

// Example
AcceptOption.builder()
    .scheme("exact").price("$0.01")
    .asset("0x4ae46a509f6b1d9056937ba4500cb143933d2dc8")   // USDG
    .build();

processor.pollInterval(Duration.ofSeconds(1));   // settle status poll interval, default 1s
processor.pollDeadline(Duration.ofSeconds(5));   // settle status poll timeout, default 5s

ExecutorService settlePool = Executors.newFixedThreadPool(16, r -> {
    Thread t = new Thread(r, "x402-settle"); t.setDaemon(true); return t;
});
processor.settleExecutor(settlePool);

processor
    .onBeforeVerify((p, r) -> AbortResult.proceed())
    .onAfterVerify((p, r, resp) -> metrics.verifyOk())
    .onVerifyFailure((p, r, e) -> RecoverResult.<VerifyResponse>notRecovered())
    .onBeforeSettle((p, r) -> AbortResult.proceed())
    .onAfterSettle((p, r, resp) -> auditLog.write(resp))
    .onSettleFailure((p, r, e) -> RecoverResult.<SettleResponse>notRecovered());

import static com.okx.x402.server.PaymentHooks.ProtectedRequestResult;

processor.onProtectedRequest((request, routeConfig) -> {
    if ("internal".equals(request.getHeader("x-api-key"))) {
        return ProtectedRequestResult.grantAccess();    // Skip payment, proceed to business
    }
    if (rateLimiter.isThrottled(request)) {
        return ProtectedRequestResult.abort("rate_limited");  // HTTP 403, {"error":"rate_limited"}
    }
    return ProtectedRequestResult.proceed();             // Normal payment flow
});

import static com.okx.x402.server.PaymentHooks.SettlementTimeoutResult;

processor.onSettlementTimeout((txHash, network) -> {
    TransactionReceipt r = web3j.ethGetTransactionReceipt(txHash)
            .send().getTransactionReceipt().orElse(null);
    return (r != null && r.isStatusOK())
            ? SettlementTimeoutResult.confirmed()       // Confirmed on-chain → treat as success
            : SettlementTimeoutResult.notConfirmed();   // Fall through to original timeout 402 flow
});

@Bean
FilterRegistrationBean<PaymentFilter> x402Filter(OKXFacilitatorClient facilitator) {
    PaymentProcessor.RouteConfig route = new PaymentProcessor.RouteConfig();
    route.network = "eip155:196";
    route.payTo   = System.getenv("PAY_TO_ADDRESS");
    route.price   = "$0.01";

    FilterRegistrationBean<PaymentFilter> reg = new FilterRegistrationBean<>(
            PaymentFilter.create(facilitator, Map.of("GET /api/data", route)));
    reg.addUrlPatterns("/api/*");
    reg.setOrder(20);          // billing filter at 10
    return reg;
}

@Configuration
class X402Config implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry r) {
        r.addInterceptor(billingInterceptor).order(10);
        r.addInterceptor(PaymentInterceptor.create(facilitator, routes))
                .order(20)
                .addPathPatterns("/api/**");
    }
}

public class App implements ServletContextInitializer {
    @Override
    public void onStartup(ServletContext ctx) {
        ctx.addFilter("x402", PaymentFilter.create(facilitator, routes))
           .addMappingForUrlPatterns(null, false, "/api/*");
    }
}

class VertxX402Request  implements X402Request  { /* ~25 lines */ }
class VertxX402Response implements X402Response { /* ~25 lines */ }

PaymentProcessor processor = new PaymentProcessor(facilitator, routes);

// preHandle returning null = response already written (402 / 500), caller should short-circuit
// returning non-null but !isVerified() = not a paid route (PASS_THROUGH), fall to business handler
PaymentProcessor.VerifyResult vr = processor.preHandle(xReq, xRes);
if (vr == null) return;                              // 402 / 500 already written
// ... business handler ...
if (vr.isVerified()) {
    processor.postHandle(vr, xReq, xRes);            // Triggers settle + writes PAYMENT-RESPONSE
}

OKXEvmSigner signer  = new OKXEvmSigner(System.getenv("PRIVATE_KEY"));
OKXHttpClient client = new OKXHttpClient(signer, "eip155:196");
HttpResponse<String> resp = client.get(URI.create("https://seller/api/data"));
// SDK auto-handles 402 → sign → replay → 200

AssetRegistry.register("eip155:196", AssetConfig.builder()
        .symbol("USDG")
        .contractAddress("0x4ae46a509f6b1d9056937ba4500cb143933d2dc8")
        .decimals(6)
        .eip712Name("USDG")
        .eip712Version("1")
        .transferMethod("eip3009")
        .build());