主題

批量支付#

本页面向 HTTP 卖家。批量支付目前仅 HTTP 卖家支持。

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

适用场景#

你的业务	是否适合
单笔金额很低（几美分到几厘钱）	✅
调用频率极高（每分钟数十至上百次）	✅
响应速度优先于链上即时结算	✅
资源不可撤回，必须等链上确认再交付	❌ 用单次支付 `syncSettle: true`
调用量小、低频	❌ 用单次支付
单次消费量不可预测（按 token / 按字节计费）	❌ 用按量支付

前提条件#

批量支付要求买家使用 Agentic Wallet。普通 EVM 钱包无法使用此模式。

原因：批量支付依赖两项关键基础设施——

Session Key：由 Agentic Wallet 生成的临时签名密钥，允许 Agent 在授权范围内自主签名，无需每次调用主私钥
TEE：硬件级安全隔离环境，OKX 在 TEE 内执行批量结算，确保签名数据无法被篡改或窃取

业务流程#

批量支付端到端流程（含 TEE 聚合）

关键时序差异（vs 单次支付）：买家立刻拿到资源，卖家也立刻确认收款（验签通过即视为收款），链上结算异步发生。

卖家接入流程#

SDK 状态

✅ Node.js / Rust / Go / Java SDK 均已可用

每个 Tab 是单一语言的完整实现（aggr_deferred scheme）。架构由 4 个组件组合：Facilitator 客户端（带 OKX API Key）→ Resource Server（注册 scheme）→ Routes 配置（accepts 数组）→ 中间件挂载。

Node.js

Rust

Java

typescript

import express from "express";
import {
  paymentMiddleware,
  x402ResourceServer,
} from "@okxweb3/x402-express";
import { AggrDeferredEvmScheme } from "@okxweb3/x402-evm/aggr-deferred/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 AggrDeferredEvmScheme());

app.use(
  paymentMiddleware(
    {
      "GET /api/realtime": {
        accepts: [
          {
            scheme: "aggr_deferred",
            network: NETWORK,
            payTo: PAY_TO,
            price: "$0.001",
          },
        ],
        description: "Realtime data",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.get("/api/realtime", (_req, res) => {
  res.json({ data: "实时数据" });
});

app.listen(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"
    aggr "github.com/okx/payments/go/x402/mechanisms/evm/aggr_deferred/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/realtime": {
            Accepts: x402http.PaymentOptions{
                {
                    Scheme:  "aggr_deferred",
                    Price:   "$0.001",
                    Network: "eip155:196",
                    PayTo:   "0xYourSellerWallet",
                },
            },
            Description: "Realtime data",
            MimeType:    "application/json",
        },
    }

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

    r.GET("/api/realtime", func(c *ginfw.Context) {
        c.JSON(http.StatusOK, ginfw.H{"data": "实时数据"})
    })

    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;

#[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", AggrDeferredEvmScheme::new());
    server.initialize().await.expect("init");

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

    let app = Router::new()
        .route("/api/realtime", 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();
}

java

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

import java.util.Map;

PaymentProcessor.RouteConfig route = new PaymentProcessor.RouteConfig();
route.scheme  = "aggr_deferred";          // ← 批量延迟结算
route.network = "eip155:196";
route.payTo   = System.getenv("PAY_TO_ADDRESS");
route.price   = "$0.001";                 // 适合批量支付

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

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

买家接入#

买家必须使用 Agentic Wallet，并预先授权一把 Session Key。

1
安装 Agentic Wallet
通过 Onchain OS Skill 创建 Agentic Wallet（邮箱登录，无需助记词），私钥在 TEE 内生成与保管。安装步骤见 Agentic Wallet 安装。
2
授权 Session Key
设置 Agent 的签名授权范围：
- 额度上限：建议先设较小金额（如 10 USD₮0）
- 有效期：建议先设较短时间（如 24 小时）
- 用途范围：限定到特定卖家域名 / 接口
3
高频调用
Agent 在授权范围内自动签名，每笔签名毫秒级，整个调用流程无需买家主私钥介入。

边界与权衡#

什么时候不该用批量支付

单笔金额大、需链上确认再交付：聚合上链有延迟，资源可能在链上确认前已交付（你已视为收款，但实际链上还没完成）→ 用单次支付 syncSettle: true
买家不愿意装 Agentic Wallet：批量支付强制要求 Agentic Wallet → 退回单次支付（任意 EIP-3009 钱包都行）
单次消费量算不准：用按量支付
需要分账：批量支付暂不支持分账，需分账的小额场景用单次支付 charge