Motyw

One-time Payment#

HTTP Sellers focus on: Business flow → HTTP Seller integration (including exact vs charge selection and syncSettle decisions) → Advanced (revenue splits)

Agent Sellers focus on: Business flow → Agent Seller integration (payment link generation and delivery) → Advanced (revenue splits)

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

When it fits#

Your business	Suitable
Per-call amount is fixed (a report / one inference / one query)	✅
Price is known up front, no follow-up consumption	✅
Resources are non-revocable (file download, report generation)	✅ (recommend `syncSettle: true`)
Tiny per-call price + ultra-high frequency	⚠️ Use Batch payment
Per-call consumption unpredictable	⚠️ Use Pay-as-you-go

Business flow#

The diagram below is the abstract flow — for HTTP Sellers it's "client request triggers", for Agent Sellers it's "the Agent proactively generates a payment link in dialogue", but the Challenge / Credential message semantics are identical. See the per-Seller integration sections below for carrier differences.

One-time payment end-to-end flow (with failure branch)

KYT (on-chain risk screening) is a compliance check internal to the Broker's Verify phase, not a separate service.

HTTP Seller integration#

SDK Status

✅ exact mode: Node.js / Rust / Go / Java SDKs all available
💡 charge revenue splits: SDK and REST API are both coming soon

Each tab below has the full install command + implementation. 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

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,            // sync settle: wait for on-chain confirmation
          },
        ],
        description: "Premium API",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.get("/api/premium", (_req, res) => {
  res.json({ data: "paid resource content" });
});

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": "paid resource content"})
    })

    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": "paid resource content"})) }))
        .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";                  // Instant single settlement
route.network      = "eip155:196";
route.payTo        = System.getenv("PAY_TO_ADDRESS");
route.price        = "$0.10";
route.syncSettle   = true;                     // ← sync: wait for on-chain confirmation

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

For async settlement (medium amount, response-speed-first), set syncSettle = false. The SDK returns 200 + status="pending" immediately; on-chain results are obtained via settleStatus polling or the onAfterSettle hook.

Java SDK notes:

When route.asyncSettle = true, you must inject your own thread pool via processor.settleExecutor(yourPool); otherwise startup throws IllegalStateException.
With the @RestController + PaymentInterceptor combo, the settlement-proof header may be lost because Spring commits the response early. If you need the PAYMENT-RESPONSE proof header, use PaymentFilter instead.

Multi-scheme declarations are all done via the accepts: [...] array; to add aggr_deferred (Batch payment), append another entry. See Batch payment.

Sync vs. async settlement#

After /settle is called, the Facilitator submits the transaction on-chain. The syncSettle field in route config controls settlement behavior:

Mode	Value	Facilitator behavior	Suitable for
Sync	`true`	Submit transaction and return `txHash` after on-chain confirmation	High-value transactions; deliver resource only after confirmed
Async	`false`	Submit transaction and return `txHash` immediately, no waiting	Mid-value, response-speed-sensitive

Async settlement carries a timing risk: resources may be delivered before final on-chain confirmation. For high-value transactions, use sync settlement. The charge scheme defaults to and only supports sync.

Agent Seller integration#

The Agent proactively generates a payment link in the conversation#

Agent Sellers don't "passively mount middleware and wait for requests" — instead, the Agent proactively generates a payment link when it needs to charge, sending it into the messaging channel (XMTP / Telegram, etc.).

Agent Sellers do not support x402 exact. Agent one-time payment uses charge.

This section focuses on payment-link generation and delivery; for how two Agents establish a session over Telegram / XMTP, see Quickstart · I'm an Agent Seller — configuring the messaging-channel gateway.

Install OnchainOS Skill

Send the prompt below to your AI Agent and follow the guided installation:

text

Please install Onchain OS Payment Skill so my Agent can generate payment links and charge for services.
My recipient wallet: 0xYourSellerWallet

See Agent Seller Quickstart for details.

Generate a payment link

The Agent calls the Skill to generate a one-time payment link when it needs to charge:

text

User: Translate this 3000-word document for me
Agent: Got it — translation costs 50 USD₮0.
       [Skill call: createPayment({type:'charge', amount:'50000000', recipient:'0x...'})]
       Please pay here: https://pay.okx.com/p/a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB

Each link is single-use and expires automatically after 30 minutes by default.

3
Send the payment link
The Skill returns a payment URL (like https://pay.okx.com/p/a2a_xxx); send it to the Buyer Agent as a text message. The other side parses the URL and signs through Agentic Wallet.
4
Poll payment status
The Skill automatically polls GET /payment/{paymentId}/status. Once the status becomes completed, it notifies the Agent to deliver the service.
text
Skill: Payment completed (tx: 0xabc...) Agent: Payment received, starting translation...

Buyer integration#

The Buyer integrates by installing Onchain OS Skill on their Agent — installing the Skill automatically configures Agentic Wallet as the underlying signing wallet, no separate installation needed. The Skill auto-detects HTTP 402 responses and payment URLs in messaging channels, signs through the wallet, and replays the request — no manual intervention required from the Buyer. See Agent Buyer for full integration steps.

Limits and trade-offs#

When not to use One-time payment

Tiny per-call price + ultra-high frequency: per-call on-chain settlement is uneconomic → use Batch payment
Per-call consumption is unpredictable (e.g. LLM per token): can't price up front → use Pay-as-you-go
Two parties don't trust each other, payout requires acceptance: use Escrow payment

Advanced#

Revenue splits (`charge` only)#

SDK Status

💡 SDK and REST API are both coming soon; revenue splits are not yet live.

A single payment can be split across up to 10 recipients; the total split must be less than the main amount. Common scenarios: platform cut, multi-party rev-share, referral commissions.

Splits are configured by bps (basis points; 1 bps = 0.01%) — e.g. 5% platform cut is bps: 500, 2% referral is bps: 200. The Broker auto-divides the funds proportionally at settlement.