Java SDK 参考#

<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;          // 资源 URL
    public String description;  // 描述
    public String mimeType;     // MIME
}

public class PaymentRequirements {
    public String scheme;             // "exact" | "aggr_deferred"
    public String network;            // "eip155:196"
    public String amount;             // 原子单位字符串
    public String payTo;              // 收款 EOA
    public int    maxTimeoutSeconds;  // 签名有效期
    public String asset;              // token 合约地址
    public Map<String, Object> extra; // scheme 专属字段
}

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;     // 选中的 accepts[i]
    public Map<String, Object> payload;      // scheme 专属签名载荷
    public Map<String, Object> extensions;

    public String toHeader();                          // base64(JSON)
    public static PaymentPayload fromHeader(String);   // 反向解码
}

{
  "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 实际结算金额
    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

// 取底层 processor 配置钩子 / 线程池
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: 收款 EOA
    public String  price;                         // "$0.01" 或 "10000"
    public String  asset;                         // 留空走 AssetRegistry 默认 (USDT0)
    public int     maxTimeoutSeconds = 86400;     // 签名有效期，默认 1 天
    public DynamicPrice priceFunction;            // 动态定价（每请求计算）
    public List<AcceptOption> accepts;            // 多币种 / 多 scheme 时用，覆盖 scheme/price/asset
    public boolean syncSettle;                    // 等链上确认再返回
    public boolean asyncSettle;                   // 后台 settle，要求注入 settleExecutor
}

@FunctionalInterface
public interface DynamicPrice {
    String resolve(X402Request request);   // 返回 USD/原子单位字符串
}

public class AcceptOption {
    public String scheme;
    public String network;             // 留空继承 route.network
    public String payTo;               // 留空继承 route.payTo
    public String price;
    public DynamicPrice priceFunction;
    public String asset;               // 留空走 AssetRegistry 默认
    public int    maxTimeoutSeconds;
    public Map<String, Object> extra;

    public static Builder builder();   // 链式
}

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

processor.pollInterval(Duration.ofSeconds(1));   // settle 状态轮询间隔，默认 1s
processor.pollDeadline(Duration.ofSeconds(5));   // settle 状态轮询超时，默认 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();    // 跳过付款，直接走业务
    }
    if (rateLimiter.isThrottled(request)) {
        return ProtectedRequestResult.abort("rate_limited");  // HTTP 403, {"error":"rate_limited"}
    }
    return ProtectedRequestResult.proceed();             // 正常付费流程
});

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()       // 链上已确认 → 当 success
            : SettlementTimeoutResult.notConfirmed();   // 走原超时 402 流程
});

@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 在 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 返回 null = 响应已写入（402 / 500），调用方应短路
// 返回非 null 但 !isVerified() = 不是付费路由（PASS_THROUGH），落到业务 handler
PaymentProcessor.VerifyResult vr = processor.preHandle(xReq, xRes);
if (vr == null) return;                              // 已写 402 / 500
// ... 业务 handler ...
if (vr.isVerified()) {
    processor.postHandle(vr, xReq, xRes);            // 触发 settle + 写 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 自动完成 402 → 签名 → 重放 → 200

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