主題

单次支付#

HTTP 卖家 重点看：业务流程 → HTTP 卖家接入（含 exact vs charge 选型、syncSettle 决策）→ 进阶（分账）

Agent 卖家 重点看：业务流程 → Agent 卖家接入（付款链接生成与分发） → 进阶（分账）

定义、底层协议详见核心概念 · 单次支付。本页聚焦接入。

适用场景#

你的业务	是否适合
单笔金额固定明确（一篇报告 / 一次推理 / 一次查询）	✅
调用前价格已确定，调用后无后续消费	✅
资源不可撤回（如文件下载、报告生成）	✅（推荐 `syncSettle: true`）
单次价格极低 + 调用频率极高	⚠️ 改用批量支付
单次消费量算不准	⚠️ 改用按量支付

业务流程#

下图是抽象层流程——HTTP 卖家是"客户端请求触发"，Agent 卖家是"Agent 在对话里主动生成付款链接触发"，但Challenge / Credential 消息语义两者一致。具体载体差异见下文卖家接入。

单次支付端到端流程（含失败分支）

KYT（链上风险审查）是 Broker Verify 阶段内部的合规检查，不是独立服务。

HTTP 卖家接入#

SDK 状态

✅ exact 模式：Node.js / Rust / Go / Java SDK 均已可用
💡 charge 分账：SDK 与 REST API 均即将推出

每个 Tab 包含完整的安装命令 + 实现代码。架构由 4 个组件组合：Facilitator 客户端（带 OKX API Key）→ Resource Server（注册 scheme）→ Routes 配置（accepts 数组）→ 中间件挂载。

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

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 || "0xYourSellerWallet";

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 /api/premium": {
        accepts: [
          {
            scheme: "exact",
            network: NETWORK,
            payTo: PAY_TO,
            price: "$0.10",
            syncSettle: true,            // 同步结算：等链上确认
          },
        ],
        description: "Premium API",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.get("/api/premium", (_req, res) => {
  res.json({ data: "付费资源内容" });
});

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

bash

go get github.com/okx/payments/go/x402

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 /api/premium": {
            Accepts: x402http.PaymentOptions{
                {
                    Scheme:     "exact",
                    Price:      "$0.10",
                    Network:    "eip155:196",
                    PayTo:      "0xYourSellerWallet",
                    SyncSettle: true,
                },
            },
            Description: "Premium API",
            MimeType:    "application/json",
        },
    }

    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("/api/premium", func(c *ginfw.Context) {
        c.JSON(http.StatusOK, ginfw.H{"data": "付费资源内容"})
    })

    r.Run(":4000")
}

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" }

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").unwrap();
    let secret_key = std::env::var("OKX_SECRET_KEY").unwrap();
    let passphrase = std::env::var("OKX_PASSPHRASE").unwrap();
    let pay_to     = std::env::var("PAY_TO_ADDRESS").unwrap();

    let facilitator = OkxHttpFacilitatorClient::new(&api_key, &secret_key, &passphrase)
        .expect("facilitator");

    let mut server = X402ResourceServer::new(facilitator)
        .register("eip155:196", ExactEvmScheme::new());
    server.initialize().await.expect("init");

    let routes = HashMap::from([(
        "GET /api/premium".to_string(),
        RoutePaymentConfig {
            accepts: vec![AcceptConfig {
                scheme: "exact".into(),
                price: "$0.10".into(),
                network: "eip155:196".into(),
                pay_to: pay_to.clone(),
                max_timeout_seconds: None,
                extra: None,
            }],
            description: "Premium API".into(),
            mime_type: "application/json".into(),
            sync_settle: Some(true),
        },
    )]);

    let app = Router::new()
        .route("/api/premium", get(|| async { Json(json!({"data": "付费资源内容"})) }))
        .layer(payment_middleware(routes, server));

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

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

import com.okx.x402.facilitator.OKXFacilitatorClient;
import com.okx.x402.server.PaymentFilter;
import com.okx.x402.server.PaymentProcessor;

import java.util.Map;

OKXFacilitatorClient facilitator = new OKXFacilitatorClient(
        System.getenv("OKX_API_KEY"),
        System.getenv("OKX_SECRET_KEY"),
        System.getenv("OKX_PASSPHRASE"));

PaymentProcessor.RouteConfig route = new PaymentProcessor.RouteConfig();
route.scheme       = "exact";                  // 即时单次结算
route.network      = "eip155:196";
route.payTo        = System.getenv("PAY_TO_ADDRESS");
route.price        = "$0.10";
route.syncSettle   = true;                     // ← 同步：等链上确认

PaymentFilter filter = PaymentFilter.create(facilitator, Map.of(
        "GET /api/premium", route));

异步结算（中等金额，优先响应速度）：把 syncSettle = false 即可。SDK 立即返回 200 + status="pending"，链上结果通过 settleStatus 轮询或 onAfterSettle 钩子获取。

Java SDK 注意事项：

route.asyncSettle = true 时必须通过 processor.settleExecutor(yourPool) 注入业务自有线程池，否则启动时抛 IllegalStateException。
@RestController + PaymentInterceptor 组合下结算证明头会被 Spring 提前提交丢失；若需 PAYMENT-RESPONSE 证明头，请用 PaymentFilter。

多 scheme 声明都通过 accepts: [...] 数组完成；要追加 aggr_deferred（批量支付）时，在数组里再加一项即可，详见批量支付。

同步结算 vs 异步结算#

调用 /settle 后，Facilitator 将交易提交到链上。路由配置中的 syncSettle 字段控制结算行为：

模式	参数值	Facilitator 行为	适用场景
同步	`true`	提交交易并等待链上确认后返回 `txHash`	高价值交易，需确认到账后再交付资源
异步	`false`	提交交易后立即返回 `txHash`，不等确认	中等价值，对响应速度有要求

异步结算存在时序风险：资源可能在链上支付最终确认前就已交付。高价值交易建议使用同步结算。charge scheme 默认且只支持同步。

Agent 卖家接入#

Agent 在对话里主动生成付款链接#

Agent 卖家不是"被动挂中间件等买家请求"，而是Agent 在对话里需要收费时主动生成付款链接，发到消息通道（XMTP / Telegram 等）。

Agent 卖家不支持 x402 exact。Agent 单次支付走 charge。

本节聚焦付款链接的生成与分发；关于两个 Agent 如何通过 Telegram / XMTP 等消息通道建立会话，详见快速开始 · 我是 Agent 卖家 — 配置消息通道网关。

安装 OnchainOS Skill

把以下提示词发给你的 AI Agent，跟随引导完成安装：

text

请帮我安装 Onchain OS Payment Skill，让我的 Agent 能生成付款链接并对外收费。
我的收款钱包地址：0xYourSellerWallet

详见 Agent 卖家快速开始。

生成付款链接

Agent 在需要收费时调用 Skill 生成一次性付款链接：

text

用户：帮我翻译这份 3000 字文档
Agent：好的，翻译服务 50 USD₮0。
       [Skill 调用：createPayment({type:'charge', amount:'50000000', recipient:'0x...'})]
       请点击付款：https://pay.okx.com/p/a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB

每条链接是一次性的，默认 30 分钟到期自动失效。

3
发送付款链接
Skill 返回的付款 URL（形如 https://pay.okx.com/p/a2a_xxx）作为文本消息发送给买家 Agent，对端解析 URL 后通过 Agentic Wallet 完成签名。
4
轮询支付状态
Skill 自动轮询 GET /payment/{paymentId}/status，状态变 completed 后通知 Agent 交付服务。
text
Skill: 支付已完成（tx: 0xabc...） Agent: 收到付款，开始翻译...

买家接入#

买家通过给 Agent 安装 Onchain OS Skill 完成接入——安装 Skill 时会自动配置 Agentic Wallet 作为底层签名钱包，无需单独安装。Skill 自动识别 HTTP 402 响应或消息通道里的付款 URL，调用钱包完成签名后重放请求，全程无需买家手动介入。完整接入步骤见 Agent 买家。