主題

通过 SDK 接入#

直接调用 Onchain OS Payment SDK 完成集成，SDK 内置 402 协议响应处理与链上交易验证，无需自定义 API 实现。

准备工作#

收款钱包：任何 EVM 兼容钱包（如Agentic Wallet）
API 密钥：通过 OKX 开发者管理平台申请。如果你的收款钱包是 Agentic Wallet，则无需申请 API 密钥。
业务后端：您自己的 API 服务或后台服务器

安装 SDK#

Node.js

Rust

Java

bash

npm install express @okxweb3/x402-express @okxweb3/x402-core @okxweb3/x402-evm
npm install -D typescript tsx @types/express @types/node

Cargo.toml 配置：

toml

[dependencies]
x402-axum = { git = "https://github.com/okx/payments" }
x402-core = { git = "https://github.com/okx/payments" }
x402-evm  = { git = "https://github.com/okx/payments" }

pom.xml —— Jakarta EE 9+ / Spring Boot 3：

xml

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

或 Java EE 8 / Spring Boot 2：

xml

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

非 servlet 框架（Vert.x、Play、Micronaut Netty 等）请直接依赖 com.okx:x402-java-core 并实现 X402Request / X402Response 适配器。

接入服务#

Node.js

Rust

Java

typescript

import express from "express";
import {
  paymentMiddleware,
  x402ResourceServer,
} from "@okxweb3/x402-express";
import { ExactEvmScheme } from "@okxweb3/x402-evm/exact/server";
import { OKXFacilitatorClient } from "@okxweb3/x402-core";

const app = express();
const NETWORK = "eip155:196";
const PAY_TO = process.env.PAY_TO_ADDRESS || "0xYourWalletAddress";

const facilitatorClient = new OKXFacilitatorClient({
  apiKey: "OKX_API_KEY",
  secretKey: "OKX_SECRET_KEY",
  passphrase: "OKX_PASSPHRASE",
});

const resourceServer = new x402ResourceServer(facilitatorClient);
resourceServer.register(NETWORK, new ExactEvmScheme());

app.use(
  paymentMiddleware(
    {
      "GET /generateImg": {
        accepts: [{
          scheme: "exact",
          network: NETWORK,
          payTo: PAY_TO,
          price: "$0.01",
        }],
        description: "AI Image Generation Service",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.get("/generateImg", (_req, res) => {
  res.json({
    success: true,
    imageUrl: "https://placehold.co/512x512/png?text=AI+Generated",
    prompt: "a sunset over mountains",
    timestamp: new Date().toISOString(),
  });
});

app.listen(4000, () => {
  console.log("[Seller] Image generation service listening at http://localhost:4000");
});

package main

import (
    "net/http"
    "os"
    "time"

    ginfw "github.com/gin-gonic/gin"
    x402http "github.com/okx/payments/go/x402/http"
    ginmw "github.com/okx/payments/go/x402/http/gin"
    evm "github.com/okx/payments/go/x402/mechanisms/evm/exact/server"
)

func main() {
    facilitator, _ := x402http.NewOKXFacilitatorClient(&x402http.OKXFacilitatorConfig{
        Auth: x402http.OKXAuthConfig{
            APIKey:     os.Getenv("OKX_API_KEY"),
            SecretKey:  os.Getenv("OKX_SECRET_KEY"),
            Passphrase: os.Getenv("OKX_PASSPHRASE"),
        },
    })

    routes := x402http.RoutesConfig{
        "GET /generateImg": {
            Accepts: x402http.PaymentOptions{
                {
                    Scheme:  "exact",
                    Price:   "$0.01",
                    Network: "eip155:196",
                    PayTo:   "0xYourWalletAddress",
                },
            },
            Description: "AI-generated image",
            MimeType:    "image/png",
        },
    }

    r := ginfw.Default()
    r.Use(ginmw.X402Payment(ginmw.Config{
        Routes:      routes,
        Facilitator: facilitator,
        Schemes: []ginmw.SchemeConfig{
            {Network: "eip155:196", Server: evm.NewExactEvmScheme()},
        },
        Timeout: 30 * time.Second,
    }))

    r.GET("/generateImg", func(c *ginfw.Context) {
        c.JSON(http.StatusOK, ginfw.H{"image": "https://placehold.co/512x512/png?text=AI+Generated"})
    })

    r.Run(":4000")
}

rust

use std::collections::HashMap;
use axum::{routing::get, Json, Router};
use serde_json::{json, Value};
use x402_axum::{payment_middleware, AcceptConfig, RoutePaymentConfig};
use x402_core::http::OkxHttpFacilitatorClient;
use x402_core::server::X402ResourceServer;
use x402_evm::{AggrDeferredEvmScheme, ExactEvmScheme};

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let api_key = std::env::var("OKX_API_KEY").expect("OKX_API_KEY required");
    let secret_key = std::env::var("OKX_SECRET_KEY").expect("OKX_SECRET_KEY required");
    let passphrase = std::env::var("OKX_PASSPHRASE").expect("OKX_PASSPHRASE required");
    let pay_to = std::env::var("PAY_TO_ADDRESS")
        .unwrap_or_else(|_| "0xb483abdb92...aa6b88c381308".to_string());

    let facilitator = match std::env::var("FACILITATOR_URL") {
        Ok(url) => OkxHttpFacilitatorClient::with_url(&url, &api_key, &secret_key, &passphrase),
        Err(_) => OkxHttpFacilitatorClient::new(&api_key, &secret_key, &passphrase),
    }
    .expect("Failed to create facilitator client");

    let mut server = X402ResourceServer::new(facilitator)
        .register("eip155:196", ExactEvmScheme::new())
        .register("eip155:196", AggrDeferredEvmScheme::new());

    server.initialize().await.expect("Failed to initialize");

    let routes = HashMap::from([(
        "GET /api/joke".to_string(),
        RoutePaymentConfig {
            accepts: vec![AcceptConfig {
                scheme: "exact".into(),
                price: "$0.001".into(),
                network: "eip155:196".into(),
                pay_to: pay_to.clone(),
                max_timeout_seconds: None,
                extra: None,
            }],
            description: "Get a random joke".into(),
            mime_type: "application/json".into(),
            sync_settle: None,
        },
    )]);

    let app = Router::new()
        .route("/health", get(health))
        .route("/api/joke", get(joke))
        .layer(payment_middleware(routes, server));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

async fn health() -> Json<Value> {
    Json(json!({ "status": "ok" }))
}

async fn joke() -> Json<Value> {
    Json(json!({
        "joke": "Why do programmers always confuse Halloween and Christmas? Because Oct 31 = Dec 25",
        "price": "$0.001"
    }))
}

java

import com.okx.x402.facilitator.OKXFacilitatorClient;
import com.okx.x402.server.PaymentFilter;
import com.okx.x402.server.PaymentProcessor;
import jakarta.servlet.ServletContext;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.servlet.ServletContextInitializer;

import java.util.Map;

@SpringBootApplication
public class App implements ServletContextInitializer {

    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }

    @Override
    public void onStartup(ServletContext ctx) {
        // 1. Facilitator 客户端（自动 HMAC-SHA256 签名）
        OKXFacilitatorClient facilitator = new OKXFacilitatorClient(
                System.getenv("OKX_API_KEY"),
                System.getenv("OKX_SECRET_KEY"),
                System.getenv("OKX_PASSPHRASE"));

        // 2. 路由计费配置
        PaymentProcessor.RouteConfig route = new PaymentProcessor.RouteConfig();
        route.scheme  = "exact";
        route.network = "eip155:196";                        // X Layer
        route.payTo   = System.getenv("PAY_TO_ADDRESS");
        route.price   = "$0.01";                             // 自动换算为 USDT 原子单位

        // 3. 一行注册 Filter
        ctx.addFilter("x402",
                PaymentFilter.create(facilitator, Map.of(
                        "GET /api/data", route)))
           .addMappingForUrlPatterns(null, false, "/api/*");
    }
}

启动后访问 GET /api/data：未带 PAYMENT-SIG → 402；签名后重放 → 200，响应头携带 PAYMENT-RESPONSE 结算证明。

测试服务#

1
通过 Onchain OS 访问服务端口
2
服务器返回 402 状态码和 PAYMENT-REQUIRED 响应头
3
使用 Agentic Wallet 完成支付
4
钱包自动重试请求
5
服务端会向 Broker 验证支付结果，并返回对应资源