概览 OKX.AI 钱包支付交易行情 X Layer

通过 SDK 接入#

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

准备工作#

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

安装 SDK#

Node.js

Rust

Java

Python

bash

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

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

Python

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 (
    "log"
    "net/http"
    "os"
    "time"

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

func boolPtr(b bool) *bool { return &b }

func main() {
    payTo := os.Getenv("PAY_TO_ADDRESS")
    if payTo == "" {
        payTo = "0xb483abdb92...aa6b88c381308"
    }

    facilitator, err := x402http.NewOKXFacilitatorClient(&x402http.OKXFacilitatorConfig{
        Auth: x402http.OKXAuthConfig{
            APIKey:     os.Getenv("OKX_API_KEY"),
            SecretKey:  os.Getenv("OKX_SECRET_KEY"),
            Passphrase: os.Getenv("OKX_PASSPHRASE"),
        },
        BaseURL: os.Getenv("OKX_BASE_URL"),
    })
    if err != nil {
        log.Fatalf("failed to create facilitator client: %v", err)
    }

    routes := x402http.RoutesConfig{
        "GET /api/joke": {
            Accepts: x402http.PaymentOptions{
                {Scheme: "exact", Price: "$0.001", Network: "eip155:196", PayTo: payTo},
            },
            Description: "Get a random joke",
            MimeType:    "application/json",
        },
    }

    r := gin.Default()

    r.GET("/health", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"status": "ok"})
    })

    paid := r.Group("/")
    paid.Use(ginmw.X402Payment(ginmw.Config{
        Routes:      routes,
        Facilitator: facilitator,
        Schemes:     []ginmw.SchemeConfig{{Network: "eip155:196", Server: exact.NewExactEvmScheme()}},
        Timeout:     300 * time.Second,
    }))
    paid.GET("/api/joke", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "joke":  "Why do programmers always confuse Halloween and Christmas? Because Oct 31 = Dec 25",
            "price": "$0.001",
        })
    })

    log.Fatal(r.Run("0.0.0.0:3000"))
}

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::ExactEvmScheme;

#[tokio::main]
async fn main() {
    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());

    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,
            resource: 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 结算证明。

python

import os
import sys

from fastapi import FastAPI
from x402.http import (
    OKXAuthConfig,
    OKXFacilitatorClient,
    OKXFacilitatorConfig,
    PaymentOption,
)
from x402.http.middleware.fastapi import PaymentMiddlewareASGI
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact.server import ExactEvmScheme
from x402.server import x402ResourceServer

pay_to = os.getenv("PAY_TO_ADDRESS", "")
if not pay_to:
    print("PAY_TO_ADDRESS required")
    sys.exit(1)

facilitator = OKXFacilitatorClient(
    OKXFacilitatorConfig(
        auth=OKXAuthConfig(
            api_key=os.getenv("OKX_API_KEY", ""),
            secret_key=os.getenv("OKX_SECRET_KEY", ""),
            passphrase=os.getenv("OKX_PASSPHRASE", ""),
        ),
        base_url=os.getenv("OKX_BASE_URL", "https://web3.okx.com"),
        sync_settle=True,
    )
)

server = x402ResourceServer(facilitator)
server.register("eip155:196", ExactEvmScheme())

routes = {
    "GET /weather": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                price="$0.1",
                network="eip155:196",
                pay_to=pay_to,
                max_timeout_seconds=300,
            ),
        ],
        description="Weather query",
        mime_type="application/json",
    ),
}

app = FastAPI()
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)


@app.get("/weather")
async def weather():
    return {"city": "Singapore", "tempC": 31, "condition": "Thunderstorm"}


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=4021)

测试服务#

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

测试网验证集成（可选）#

代码示例默认使用 X Layer Mainnet（eip155:196）。若想在不消耗真实资金的前提下跑通集成，可以先把网络常量改为测试网，跑通后再改回主网，只需改一行：

diff

- const NETWORK = "eip155:196";    // X Layer Mainnet
+ const NETWORK = "eip155:1952";   // X Layer Testnet

价格用 USD 字符串（如 "$0.01"），系统会自动按目标网络的稳定币换算，切网无需改 price 字段。

测试网领水：

Gas（test OKB）→ 前往 X Layer Faucet 领取
稳定币（test USD₮0）→ 前往 X Layer Faucet 领取

用官方 Mock Merchant 作为参考比对：

https://www.okx.com/api/v1/pay/mock-merchant/resource（X Layer Testnet 部署）