Tema

Batch Payment#

This page is for HTTP Sellers. Batch payment is currently only supported for HTTP Sellers.

For definitions and the underlying protocol, see Core Concepts · Batch payment. This page focuses on integration.

When it fits#

Your business	Suitable
Per-call amount is very low (cents to fractions of a cent)	✅
Very high call frequency (tens to hundreds per minute)	✅
Response speed is more important than instant on-chain settlement	✅
Resources are non-revocable, must wait for on-chain confirmation before delivery	❌ Use One-time payment with `syncSettle: true`
Low call volume / low frequency	❌ Use One-time payment
Per-call consumption is unpredictable (per-token / per-byte billing)	❌ Use Pay-as-you-go

Prerequisites#

Batch payment requires the Buyer to use Agentic Wallet. Ordinary EVM wallets cannot use this mode.

Why: Batch payment depends on two key pieces of infrastructure:

Session Key: a temporary signing key generated by Agentic Wallet, allowing the Agent to sign autonomously within the authorized scope without invoking the main private key on every call
TEE: a hardware-isolated secure environment where OKX runs batch settlement, ensuring signature data cannot be tampered with or stolen

Business flow#

Batch payment end-to-end flow (with TEE aggregation)

Key timing difference (vs. One-time payment): the Buyer gets the resource immediately, and the Seller also confirms receipt immediately (verified signature = received payment); on-chain settlement happens asynchronously.

Seller integration#

SDK Status

✅ Node.js / Rust / Go / Java SDKs are all available

Each tab below is a single-language complete implementation (aggr_deferred scheme). The architecture is composed of four pieces: Facilitator client (with OKX API Key) → Resource Server (register schemes) → Routes config (accepts array) → middleware mount.

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: "realtime 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": "realtime 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": "realtime 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";          // ← Batch deferred settlement
route.network = "eip155:196";
route.payTo   = System.getenv("PAY_TO_ADDRESS");
route.price   = "$0.001";                 // Suitable for batch payment

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));

Buyer integration#

The Buyer must use Agentic Wallet and pre-authorize a Session Key.

1
Install Agentic Wallet
Create Agentic Wallet through Onchain OS Skill (email login, no seed phrase needed); the private key is generated and held inside a TEE. See Agentic Wallet installation.
2
Authorize a Session Key
Set the Agent's signing scope:
- Cap: start with a small amount (e.g. 10 USD₮0)
- Validity: start with a short period (e.g. 24 hours)
- Scope: bind to a specific Seller domain / endpoint
3
High-frequency calls
The Agent signs autonomously within the authorized scope; each signature is millisecond-fast, and the call flow does not need the Buyer's main private key.

Limits and trade-offs#

When not to use Batch payment

Large per-call amount, must wait for on-chain confirmation before delivery: Aggregated on-chain has latency; resources may be delivered before on-chain confirmation (you've already counted it as received, but on-chain hasn't completed) → use One-time payment with syncSettle: true
Buyer doesn't want to install Agentic Wallet: Batch payment requires Agentic Wallet → fall back to One-time payment (any EIP-3009 wallet works)
Per-call consumption is unpredictable: use Pay-as-you-go
Need revenue splits: Batch payment doesn't yet support splits; for small-amount scenarios needing splits, use One-time payment with charge

Advanced#

Coexisting with `exact`#

Make the same route serve both buyer types — declare both exact and aggr_deferred in the accepts array and let the buyer wallet auto-select by capability.