Batch Payment#

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

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 small (a few cents to fractions of a cent)	✅
Ultra-high call frequency (tens to hundreds per minute)	✅
Response speed prioritized over instant on-chain settlement	✅

Prerequisites#

Batch payment requires the buyer to use Agentic Wallet. A regular EVM wallet cannot use this mode.

Reason: batch payment depends on two pieces of key infrastructure —

Session Key: a temporary signing key generated by Agentic Wallet; the Agent signs directly with this key on every call, no need to wake up the buyer's main private key per call
TEE: a hardware-isolated secure environment where OKX runs the 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 receives the resource immediately and the seller also confirms receipt immediately (settle returning status=success is treated as paid); on-chain settlement happens asynchronously.

Seller integration flow#

SDK status

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

Each Tab is a complete single-language implementation (aggr_deferred scheme). The architecture has 4 components: Facilitator client (with OKX API Key) → Resource Server (registers the scheme) → 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";                 // suited 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.

1
Install Agentic Wallet
Create Agentic Wallet via the Onchain OS Skill (email login, no seed phrase). The private key is generated and held inside the TEE. See Agentic Wallet install.
2
High-frequency calls
The Agent signs automatically; each signature is millisecond-level, and the entire call flow doesn't require the buyer's main private key.

Limits and trade-offs#

When not to use batch payment

Large per-call amount, need on-chain confirmation before delivery: aggregated on-chain settlement has latency; the resource may be delivered before on-chain confirmation (you've treated it as paid, but on-chain it isn't done yet) → use One-time payment syncSettle: true
Buyer unwilling to install Agentic Wallet: batch payment forces Agentic Wallet → fall back to One-time payment (any EIP-3009 wallet works)
Per-call consumption can't be precomputed: use Pay-as-you-go
Need splits: batch payment doesn't support splits yet; for small-amount split scenarios use One-time payment charge

Advanced#

Coexistence strategy with `exact`#

Let one route serve both buyer types — declare both exact and aggr_deferred in the accepts array, and the buyer wallet picks based on capability.