One-time Payment#

HTTP Sellers focus on: Business flow → HTTP Seller integration (scheme selection → exact path / charge path → syncSettle decision) → Advanced (splits, supporting exact + charge simultaneously)

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

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

When it fits#

Your business	Suitable
Single-call amount is fixed and clear (one report / one inference / one query)	✅
Price is determined before the call, no follow-on consumption after	✅
Resource is non-revocable (file download, report generation, etc.)	✅ (recommend `syncSettle: true`)

Business flow#

The diagram below is the abstract-level flow — HTTP Sellers are "triggered by client request", Agent Sellers are "triggered by the Agent generating a payment link in the dialogue", but the Challenge / Credential message semantics are identical. The carrier differences are covered in the seller integration sections below.

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

KYT (on-chain risk screening) is a compliance check inside the Broker's Verify stage — not a separate service.

HTTP Seller integration#

`exact` or `charge`?#

exact — single recipient, supports both sync and async settlement.

charge — supports a single recipient too, plus splits, i.e. one payment to multiple addresses (≤10). Defaults to and only supports sync settlement.

Dimension	`exact`	`charge`
Recipient	Single	Single / one-payment-to-multiple-addresses (≤10)
Settlement timing	Sync / async	Default and sync only

Not sure which to pick? Use supporting exact + charge simultaneously and let the buyer choose.

SDK status#

Scheme	Node.js	Rust	Go	Java
`exact`	✅	✅	✅	✅
`charge`	✅	✅	✅	Coming soon

`exact` path#

Each Tab includes the full install command + implementation code. 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

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: "premium 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": "premium 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": "premium 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));

Async settlement (medium amount, prioritize response speed): just 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 @RestController + PaymentInterceptor, settlement-proof headers are lost because Spring commits the response too early; if you need the PAYMENT-RESPONSE proof header, use PaymentFilter.

Multi-scheme declarations all go through the accepts: [...] array; to append aggr_deferred (Batch payment), just add another entry to the array — see Batch payment.

Sync vs. async settlement#

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

Mode	Value	Facilitator behavior	Use case
Sync	`true`	Submits the transaction and waits for on-chain confirmation before returning `txHash`	High-value transactions; need confirmation before delivering the resource
Async	`false`	Returns `txHash` immediately after submission, without waiting for confirmation	Medium-value, response-speed sensitive

Async settlement carries a timing risk: the resource may be delivered before the on-chain payment is finalized. Sync settlement is recommended for high-value transactions. The charge scheme defaults to and only supports sync.

`charge` path#

SDK status

Rust / Node.js / Go SDKs are live; Java SDK coming soon.

charge does not use x402's accepts array; instead it uses a ChargeConfig type + MppCharge<T> extractor to describe each route's price — the price is returned by an associated function on the type and locked at compile time, not overridable at the route-config layer.

Node.js

Rust

package.json:

json

{
  "type": "module",
  "dependencies": {
    "@okxweb3/mpp": "^0.1.0"
  }
}

typescript

// server.ts
// Run: node --env-file=.env --experimental-strip-types server.ts
// Or:  npx tsx --env-file=.env server.ts
import * as http from "node:http";
import { Mppx } from "@okxweb3/mpp";
import { charge } from "@okxweb3/mpp/evm/server";
import { SaApiClient } from "@okxweb3/mpp/evm";

// SA-API client (broadcasts EIP-3009 in transaction mode).
const saClient = new SaApiClient({
  apiKey: process.env.OKX_API_KEY!,
  secretKey: process.env.OKX_SECRET_KEY!,
  passphrase: process.env.OKX_PASSPHRASE!,
});

const mppx = Mppx.create({
  methods: [charge({ saClient })],
  realm: "test realm",
  secretKey: process.env.MPP_SECRET_KEY!,
});

// Per-route price (base units; "100" = 0.0001 of a 6-decimal token).
// fee_payer = true → seller broadcasts the EIP-3009 (transaction mode).
const CHARGE = {
  amount: "100",
  currency: "0x...adb21711",                 // currency
  recipient: "0x...378211",                  // receipt
  description: "One premium API call",
  methodDetails: { chainId: 196, feePayer: true },  // X Layer
} as const;

// Runs only after verify + settle.
async function premium(request: Request): Promise<Response> {
  const result = await mppx.charge(CHARGE)(request);
  if (result.status === 402) return result.challenge;
  return result.withReceipt(Response.json({ data: "premium content" }));
}

// node:http ↔ Web Standards bridge (10 lines).
http.createServer(async (req, res) => {
  const url = `http://${req.headers.host ?? "localhost:4000"}${req.url}`;
  const webReq = new Request(url, {
    method: req.method,
    headers: new Headers(req.headers as Record<string, string>),
  });
  const webRes =
    new URL(url).pathname === "/api/premium"
      ? await premium(webReq)
      : new Response("not found", { status: 404 });
  res.statusCode = webRes.status;
  webRes.headers.forEach((v, k) => res.setHeader(k, v));
  res.end(await webRes.text());
}).listen(4000);

go.mod:

require github.com/okx/payments/go/mpp v0.1.0

package main

import (
    "log"
    "net/http"
    "os"

    "github.com/gin-gonic/gin"

    "github.com/okx/payments/go/mpp/evm"
    mppgin "github.com/okx/payments/go/mpp/http/gin"
    "github.com/okx/payments/go/mpp/saclient"
    "github.com/okx/payments/go/mpp/server"
)

func main() {
    saClient := saclient.NewOKXSAClient(
        os.Getenv("OKX_BASE_URL"),
        os.Getenv("OKX_API_KEY"),
        os.Getenv("OKX_SECRET_KEY"),
        os.Getenv("OKX_PASSPHRASE"),
    )

    // fee_payer = true -> seller broadcasts the EIP-3009 (transaction mode).
    chargeMethod := evm.NewEVMChargeMethod().
        WithChainID(196).                       // X Layer
        WithRecipient("0x...378211").            // recipient
        WithSAClient(saClient).
        WithFeePayer(true)

    mpp := server.NewMpp(server.EVMConfig{
        ChainID:   196,
        Recipient: "0x...378211",
        SecretKey: os.Getenv("MPP_SECRET_KEY"),
        Realm:     "test realm",
    }, chargeMethod, nil)

    r := gin.Default()

    // Per-route price (base units; "100" = 0.0001 of a 6-decimal token).
    r.GET("/api/premium",
        mppgin.ChargeMiddleware(mpp, server.ChargeRouteConfig{
            Amount:      "100",
            Currency:    "0x...adb21711",
            Decimals:    6,
            Description: "One premium API call",
        }),
        func(c *gin.Context) {
            receipt := mppgin.GetReceipt(c)
            c.JSON(http.StatusOK, gin.H{
                "data":    "premium content",
                "receipt": receipt,
            })
        },
    )

    log.Fatal(r.Run(":4000"))
}

Cargo.toml:

toml

[dependencies]
mpp-evm = { git = "https://github.com/okx/payments" } # tag is configurable
mpp     = { version = "0.10", features = ["server", "evm", "tower", "axum"] }

rust

use std::sync::Arc;

use axum::{routing::get, Json, Router};
use mpp::server::axum::{ChargeChallenger, ChargeConfig, MppCharge, WithReceipt};
use mpp_evm::sa_client::SaApiClient;
use mpp_evm::{
    EvmChargeChallenger, EvmChargeChallengerConfig, EvmChargeMethod, OkxSaApiClient,
};
use serde_json::{json, Value};

// Per-route price (base units; "100" = 0.0001 of a 6-decimal token).
struct OnePremiumCall;
impl ChargeConfig for OnePremiumCall {
    fn amount() -> &'static str { "100" }
    fn description() -> Option<&'static str> { Some("One premium API call") }
}

// Runs only after verify + settle.
async fn premium(charge: MppCharge<OnePremiumCall>) -> WithReceipt<Json<Value>> {
    WithReceipt {
        receipt: charge.receipt,
        body: Json(json!({ "data": "premium content" })),
    }
}

#[tokio::main]
async fn main() {
    let okx_api_key     = std::env::var("OKX_API_KEY").unwrap();
    let okx_secret_key  = std::env::var("OKX_SECRET_KEY").unwrap();
    let okx_passphrase    = std::env::var("OKX_PASSPHRASE").unwrap();
    let secret_key = std::env::var("MPP_SECRET_KEY").unwrap();

    let sa_client: Arc<dyn SaApiClient> =
        Arc::new(OkxSaApiClient::new(okx_api_key, okx_secret_key, okx_passphrase));

    // fee_payer = true → seller broadcasts the EIP-3009 (transaction mode).
    let challenger: Arc<dyn ChargeChallenger> = Arc::new(EvmChargeChallenger::new(
        EvmChargeChallengerConfig {
            charge_method: EvmChargeMethod::new(sa_client),
            currency: "0x...adb21711".into(),  // pricing token (ERC-20 contract address on X Layer, e.g. USDC)
            recipient: "0x...378211".into(),   // primary recipient (payee)
            chain_id: 196, // X Layer
            fee_payer: Some(true),
            realm: "test realm",
            secret_key,
            splits: None,
        },
    ));

    let app = Router::new()
        .route("/api/premium", get(premium))
        .with_state(challenger);

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

Advanced#

Applies only to HTTP Sellers — the SDK code blocks below all attach to HTTP middleware. Agent Sellers generate payment links via the Skill and don't touch this layer.

1. Splits (only `charge`)#

One payment is automatically split among up to 10 recipients. Common scenarios: platform commission, multi-party revenue split, referral payout.

Hard constraints:

sum(splits.amount) < ChargeConfig::amount() (split total must be strictly less than the primary amount)
splits.len() ≤ 10
Each recipient must be an EIP-55-checksummed 40-hex address

Signing burden: the buyer signs one EIP-3009 per split — 1 to the primary recipient + 1 per split — and the seller submits them all together at /settle.

Node.js

Rust

package.json:

json

{
  "type": "module",
  "dependencies": {
    "@okxweb3/mpp": "^0.1.0"
  }
}

typescript

// server.ts
// Run: npx tsx --env-file=.env server.ts
import * as http from "node:http";
import { Mppx } from "@okxweb3/mpp";
import { charge } from "@okxweb3/mpp/evm/server";
import { SaApiClient } from "@okxweb3/mpp/evm";

const saClient = new SaApiClient({
  apiKey: process.env.OKX_API_KEY!,
  secretKey: process.env.OKX_SECRET_KEY!,
  passphrase: process.env.OKX_PASSPHRASE!,
});

const mppx = Mppx.create({
  methods: [charge({ saClient })],
  realm: "test realm",
  secretKey: process.env.MPP_SECRET_KEY!,
});

// Total 100 base units; primary keeps 50, splits take 30 + 20.
// Constraints: sum(splits) < amount; splits.length <= 10;
//              recipient must be 40-hex EIP-55.
// Buyer signs one EIP-3009 per split (one to primary + one per entry).
const splits = [
  { amount: "30", recipient: "0x....321a1308", memo: "partner-a" },
  { amount: "20", recipient: "0x....d31a6608", memo: "partner-b" },
];

// Only difference vs single charge: methodDetails.splits.
const CHARGE = {
  amount: "100",
  currency: "0x...adb21711",                 // currency
  recipient: "0x...378211",                  // primary receipt
  description: "One premium API call (split)",
  methodDetails: { chainId: 196, feePayer: true, splits },
} as const;

async function premium(request: Request): Promise<Response> {
  const result = await mppx.charge(CHARGE)(request);
  if (result.status === 402) return result.challenge;
  return result.withReceipt(Response.json({ data: "premium content" }));
}

http.createServer(async (req, res) => {
  const url = `http://${req.headers.host ?? "localhost:4000"}${req.url}`;
  const webReq = new Request(url, {
    method: req.method,
    headers: new Headers(req.headers as Record<string, string>),
  });
  const webRes =
    new URL(url).pathname === "/api/premium"
      ? await premium(webReq)
      : new Response("not found", { status: 404 });
  res.statusCode = webRes.status;
  webRes.headers.forEach((v, k) => res.setHeader(k, v));
  res.end(await webRes.text());
}).listen(4000);

go.mod:

require github.com/okx/payments/go/mpp v0.1.0

package main

import (
    "log"
    "net/http"
    "os"

    "github.com/gin-gonic/gin"

    "github.com/okx/payments/go/mpp/evm"
    mppgin "github.com/okx/payments/go/mpp/http/gin"
    "github.com/okx/payments/go/mpp/saclient"
    "github.com/okx/payments/go/mpp/server"
)

func main() {
    saClient := saclient.NewOKXSAClient(
        os.Getenv("OKX_BASE_URL"),
        os.Getenv("OKX_API_KEY"),
        os.Getenv("OKX_SECRET_KEY"),
        os.Getenv("OKX_PASSPHRASE"),
    )

    chargeMethod := evm.NewEVMChargeMethod().
        WithChainID(196).
        WithRecipient("0x...378211").
        WithSAClient(saClient).
        WithFeePayer(true)

    mpp := server.NewMpp(server.EVMConfig{
        ChainID:   196,
        Recipient: "0x...378211",
        SecretKey: os.Getenv("MPP_SECRET_KEY"),
        Realm:     "test realm",
    }, chargeMethod, nil)

    // Total 100 base units; primary keeps 50, splits take 30 + 20.
    // Constraints: sum(splits) < amount; splits.len() <= 10; recipient must be 40-hex EIP-55.
    splits := []evm.Split{
        {Amount: "30", Recipient: "0x....321a1308", Memo: strPtr("partner-a")},
        {Amount: "20", Recipient: "0x....d31a6608", Memo: strPtr("partner-b")},
    }

    r := gin.Default()

    r.GET("/api/premium",
        mppgin.ChargeMiddleware(mpp, server.ChargeRouteConfig{
            Amount:      "100",
            Currency:    "0x...adb21711",
            Decimals:    6,
            Description: "One premium API call (split)",
            Splits:      splits,
        }),
        func(c *gin.Context) {
            receipt := mppgin.GetReceipt(c)
            c.JSON(http.StatusOK, gin.H{
                "data":    "premium content",
                "receipt": receipt,
            })
        },
    )

    log.Fatal(r.Run(":4000"))
}

func strPtr(s string) *string { return &s }

Cargo.toml:

toml

[dependencies]
mpp-evm = { git = "https://github.com/okx/payments"} # tag is configurable
mpp     = { version = "0.10", features = ["server", "evm", "tower", "axum"] }

rust

use std::sync::Arc;

use axum::{routing::get, Json, Router};
use mpp::server::axum::{ChargeChallenger, ChargeConfig, MppCharge, WithReceipt};
use mpp_evm::sa_client::SaApiClient;
use mpp_evm::{
    ChargeSplit, EvmChargeChallenger, EvmChargeChallengerConfig, EvmChargeMethod, OkxSaApiClient,
};
use serde_json::{json, Value};

// Total 100 base units; primary keeps 50, splits take 30 + 20.
// Constraints: sum(splits) < amount(); splits.len() <= 10; recipient must be 40-hex EIP-55.
struct OnePremiumCall;
impl ChargeConfig for OnePremiumCall {
    fn amount() -> &'static str { "100" }
    fn description() -> Option<&'static str> { Some("One premium API call (split)") }
}

async fn premium(charge: MppCharge<OnePremiumCall>) -> WithReceipt<Json<Value>> {
    WithReceipt {
        receipt: charge.receipt,
        body: Json(json!({ "data": "premium content" })),
    }
}

#[tokio::main]
async fn main() {
    let okx_api_key     = std::env::var("OKX_API_KEY").unwrap();
    let okx_secret_key  = std::env::var("OKX_SECRET_KEY").unwrap();
    let okx_passphrase    = std::env::var("OKX_PASSPHRASE").unwrap();
    let secret_key = std::env::var("MPP_SECRET_KEY").unwrap();

    // Buyer signs one EIP-3009 per split (one to primary + one per entry below).
    let splits = vec![
        ChargeSplit {
            amount: "30".into(),
            recipient: "0x....321a1308",
            memo: Some("partner-a".into()),
        },
        ChargeSplit {
            amount: "20".into(),
            recipient: "0x....d31a6608",
            memo: Some("partner-b".into()),
        },
    ];

    let sa_client: Arc<dyn SaApiClient> =
        Arc::new(OkxSaApiClient::new(okx_api_key, okx_secret_key, okx_passphrase));

    // Only difference vs single charge: `splits: Some(...)`.
    let challenger: Arc<dyn ChargeChallenger> = Arc::new(EvmChargeChallenger::new(
        EvmChargeChallengerConfig {
            charge_method: EvmChargeMethod::new(sa_client),
            currency: "0x...adb21711".into(),  // pricing token (ERC-20 contract address on X Layer, e.g. USD₮0)
            recipient: "0x...378211".into(),   // primary recipient (payee — receives the remainder after splits)
            chain_id: 196,
            fee_payer: Some(true),
            realm: "test realm",
            secret_key,
            splits: Some(splits),
        },
    ));

    let app = Router::new()
        .route("/api/premium", get(premium))
        .with_state(challenger);

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

The current charge split implementation uses explicit amounts — each split is in absolute base units, not a percentage.

2. Supporting `exact` + `charge` simultaneously#

Node.js

Rust

package.json:

json

{
  "type": "module",
  "dependencies": {
    "@okxweb3/payment-router": "^0.1.0",
    "@okxweb3/mpp": "^0.1.0",
    "@okxweb3/x402-core": "^0.1.0",
    "@okxweb3/x402-evm": "^0.1.0"
  }
}

typescript

// server.ts
// Run: npx tsx --env-file=.env server.ts
import * as http from "node:http";

import { Mppx } from "@okxweb3/mpp";
import { charge as mppCharge } from "@okxweb3/mpp/evm/server";
import { SaApiClient } from "@okxweb3/mpp/evm";

import { OKXFacilitatorClient } from "@okxweb3/x402-core";
import {
  x402HTTPResourceServer,
  x402ResourceServer,
} from "@okxweb3/x402-core/server";
import { ExactEvmScheme } from "@okxweb3/x402-evm/exact/server";

import {
  MppAdapter,
  X402Adapter,
  paymentRouter,
} from "@okxweb3/payment-router";

// —— MPP setup ——
const saClient = new SaApiClient({
  apiKey: process.env.OKX_API_KEY!,
  secretKey: process.env.OKX_SECRET_KEY!,
  passphrase: process.env.OKX_PASSPHRASE!,
});
const mppx = Mppx.create({
  methods: [mppCharge({ saClient })],
  realm: "test realm",
  secretKey: process.env.MPP_SECRET_KEY!,
});

// —— x402 setup (facilitator + scheme; routes are declared on the router) ——
const NETWORK = "eip155:196"; // X Layer Mainnet
const x402Server = new x402ResourceServer(
  new OKXFacilitatorClient({
    apiKey: process.env.OKX_API_KEY!,
    secretKey: process.env.OKX_SECRET_KEY!,
    passphrase: process.env.OKX_PASSPHRASE!,
  }),
).register(NETWORK, new ExactEvmScheme());

// Built-in priorities: MPP=10, x402=20 (MPP wins when both headers present).
// Custom adapters should start at priority ≥ 100.
const protect = paymentRouter({
  adapters: [
    new MppAdapter({ mppx }),
    new X402Adapter({
      resourceServer: x402Server,
      httpResourceServerCtor: x402HTTPResourceServer,
    }),
  ],
  routes: {
    "GET /generateImg": {
      description: "AI Image Generation Service",
      adapterConfigs: {
        mpp: {
          intent: "charge",
          amount: "10000",
          currency: "0x...adb21711",         // currency
          recipient: "0x...378211",          // receipt
          description: "AI Image Generation Service",
          methodDetails: { chainId: 196, feePayer: true },
        },
        x402: {
          scheme: "exact",
          network: NETWORK,
          payTo: "0x...378211",              // receipt
          price: "$0.01",
          description: "AI Image Generation Service",
          mimeType: "application/json",
        },
      },
    },
  },
});

// Protocol-agnostic. Runs only after one of the adapters has verified payment.
const handler = protect(async () =>
  Response.json({
    imageUrl: "https://placehold.co/512x512/png?text=AI+Generated",
    prompt: "a sunset over mountains",
  }),
);

http.createServer(async (req, res) => {
  const url = `http://${req.headers.host ?? "localhost:4000"}${req.url}`;
  const webReq = new Request(url, {
    method: req.method,
    headers: new Headers(req.headers as Record<string, string>),
  });
  const webRes =
    new URL(url).pathname === "/generateImg" && req.method === "GET"
      ? await handler(webReq)
      : new Response("not found", { status: 404 });
  res.statusCode = webRes.status;
  webRes.headers.forEach((v, k) => res.setHeader(k, v));
  res.end(await webRes.text());
}).listen(4000);

go.mod:

require (
    github.com/okx/payments/go/mpp           v0.1.0
    github.com/okx/payments/go/paymentrouter  v0.1.0
    github.com/okx/payments/go/x402           v0.1.0
)

package main

import (
    "log"
    "net/http"
    "os"

    "github.com/gin-gonic/gin"

    mppadapters "github.com/okx/payments/go/mpp/adapters"
    "github.com/okx/payments/go/mpp/evm"
    "github.com/okx/payments/go/mpp/saclient"
    "github.com/okx/payments/go/mpp/server"
    pr "github.com/okx/payments/go/paymentrouter"
    prgin "github.com/okx/payments/go/paymentrouter/gin"
    "github.com/okx/payments/go/x402"
    x402adapters "github.com/okx/payments/go/x402/adapters"
    x402http "github.com/okx/payments/go/x402/http"
    exact "github.com/okx/payments/go/x402/mechanisms/evm/exact/server"
)

// Protocol-agnostic. Runs only after one of the adapters has verified payment.
func generateImg(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{
        "imageUrl": "https://placehold.co/512x512/png?text=AI+Generated",
        "prompt":   "a sunset over mountains",
    })
}

func main() {
    payTo := os.Getenv("PAY_TO_ADDRESS")

    saClient := saclient.NewOKXSAClient(
        os.Getenv("OKX_BASE_URL"),
        os.Getenv("OKX_API_KEY"),
        os.Getenv("OKX_SECRET_KEY"),
        os.Getenv("OKX_PASSPHRASE"),
    )

    // fee_payer = true -> seller broadcasts the EIP-3009 (transaction mode).
    chargeMethod := evm.NewEVMChargeMethod().
        WithChainID(196).
        WithRecipient(payTo).
        WithSAClient(saClient).
        WithFeePayer(true)

    mpp := server.NewMpp(server.EVMConfig{
        ChainID:   196,
        Recipient: payTo,
        SecretKey: os.Getenv("MPP_SECRET_KEY"),
        Realm:     "test realm",
    }, chargeMethod, nil)

    facilitator, err := x402http.NewOKXFacilitatorClient(&x402http.OKXFacilitatorConfig{
        Auth: x402http.OKXAuthConfig{
            APIKey:     os.Getenv("OKX_API_KEY"),
            SecretKey:  os.Getenv("OKX_SECRET_KEY"),
            Passphrase: os.Getenv("OKX_PASSPHRASE"),
        },
        BaseURL:    os.Getenv("OKX_BASE_URL"),
        SyncSettle: boolPtr(true),
    })
    if err != nil {
        log.Fatalf("x402 facilitator: %v", err)
    }

    x402Server := x402http.Newx402HTTPResourceServer(nil, x402.WithFacilitatorClient(facilitator))
    x402Server.Register("eip155:196", exact.NewExactEvmScheme())

    // Built-in priorities: MPP=10, x402=20 (MPP wins when both headers present).
    mppAdapter := mppadapters.NewMppAdapter(mpp)
    x402Adapter := x402adapters.NewX402Adapter(x402Server)

    r := gin.Default()
    paid := prgin.New([]pr.ProtocolAdapter{mppAdapter, x402Adapter})

    imgCfg := pr.RouteConfig{
        "mpp": mppadapters.MppRouteConfig{
            Intent:      "charge",
            Amount:      "0.01",                                   // 10000 base units at 6 decimals
            Currency:    "0x...adb21711",
            Decimals:    6,
            Description: "AI Image Generation Service",
        },
        "x402": x402http.RouteConfig{
            Accepts: x402http.PaymentOptions{{
                Scheme:            "exact",
                Price:             "$0.01",
                Network:           "eip155:196",
                PayTo:             payTo,
                MaxTimeoutSeconds: 300,
            }},
            Description: "AI Image Generation Service",
            MimeType:    "application/json",
        },
    }

    r.GET("/generateImg", paid.For(imgCfg), generateImg)

    log.Fatal(r.Run(":4000"))
}

func boolPtr(b bool) *bool { return &b }

Cargo.toml:

toml

[dependencies]
# OKX dual-protocol router (MPP + x402 on the same URL).
# tag is configurable
payment-router-axum = { git = "https://github.com/okx/payments" } 
mpp-evm             = { git = "https://github.com/okx/payments" }
x402-core           = { git = "https://github.com/okx/payments" }
x402-axum           = { git = "https://github.com/okx/payments" }
x402-evm            = { git = "https://github.com/okx/payments" }

# Upstream MPP protocol layer (re-exported types).
mpp = { version = "0.10", features = ["server", "evm", "tower", "axum"] }

rust

use std::collections::HashMap;
use std::sync::Arc;

use axum::{routing::get, Json, Router};
use mpp::server::axum::ChargeChallenger;
use mpp_evm::sa_client::SaApiClient;
use mpp_evm::{
    EvmChargeChallenger, EvmChargeChallengerConfig, EvmChargeMethod, OkxSaApiClient,
};
use payment_router_axum::{
    adapters::{MppAdapter, X402Adapter},
    PaymentRouterConfig, PaymentRouterLayer, ProtocolAdapter, UnifiedRouteConfig,
};
use serde_json::{json, Value};
use x402_axum::{AcceptConfig, RoutePaymentConfig, RoutesConfig};
use x402_core::http::OkxHttpFacilitatorClient;
use x402_core::server::X402ResourceServer;
use x402_evm::ExactEvmScheme;

// Protocol-agnostic. Runs only after one of the adapters has verified payment.
async fn generate_img() -> Json<Value> {
    Json(json!({
        "imageUrl": "https://placehold.co/512x512/png?text=AI+Generated",
        "prompt": "a sunset over mountains",
    }))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let okx_api_key    = std::env::var("OKX_API_KEY")?;
    let okx_secret_key = std::env::var("OKX_SECRET_KEY")?;
    let okx_passphrase   = std::env::var("OKX_PASSPHRASE")?;
    let secret_key = std::env::var("MPP_SECRET_KEY")?;

    let sa_client: Arc<dyn SaApiClient> =
        Arc::new(OkxSaApiClient::new(okx_api_key.clone(), okx_secret_key.clone(), okx_passphrase.clone()));
    let mpp_challenger: Arc<dyn ChargeChallenger> = Arc::new(EvmChargeChallenger::new(
        EvmChargeChallengerConfig {
            charge_method: EvmChargeMethod::new(sa_client),
            currency: "0x...adb21711".into(),  // pricing token (ERC-20 contract address on X Layer, e.g. USDC)
            recipient: "0x...378211".into(),   // primary recipient (payee)
            chain_id: 196, // X Layer
            fee_payer: Some(true),
            realm: "test realm",
            secret_key,
            splits: None,
        },
    ));

    let facilitator = OkxHttpFacilitatorClient::new(&okx_api_key, &okx_secret_key, &okx_passphrase)?;
    let mut x402_server = X402ResourceServer::new(facilitator)
        .register("eip155:196", ExactEvmScheme::new());
    x402_server.initialize().await?;

    let x402_routes: RoutesConfig = HashMap::from([(
        "GET /generateImg".to_string(),
        RoutePaymentConfig {
            accepts: vec![AcceptConfig {
                scheme: "exact".into(),
                price: "$0.01".into(),
                network: "eip155:196".into(),
                pay_to: "0x...378211".into(),  // primary recipient
                max_timeout_seconds: None,
                extra: None,
            }],
            description: "AI Image Generation Service".into(),
            mime_type: "application/json".into(),
            sync_settle: Some(true),
        },
    )]);

    // Built-in priorities: MPP=10, x402=20 (MPP wins when both headers present).
    // Custom adapters should start at priority ≥ 100.
    let mpp_adapter  = Arc::new(MppAdapter::new(mpp_challenger.clone()));
    let x402_adapter = Arc::new(X402Adapter::new(Arc::new(x402_server), x402_routes));
    let adapters: Vec<Arc<dyn ProtocolAdapter>> = vec![mpp_adapter, x402_adapter];

    let unified_routes: HashMap<String, UnifiedRouteConfig> = HashMap::from([(
        "GET /generateImg".to_string(),
        UnifiedRouteConfig {
            adapter_configs: HashMap::from([
                ("mpp".to_string(), json!({
                    "amount": "10000",
                    "description": "AI Image Generation Service",
                })),
                // x402 reads its config from `x402_routes`; `{}` just enables it on this route.
                ("x402".to_string(), json!({})),
            ]),
        },
    )]);

    let layer = PaymentRouterLayer::new(PaymentRouterConfig {
        adapters,
        routes: unified_routes,
        on_error: None,
    })?;

    let app = Router::new()
        .route("/generateImg", get(generate_img))
        .layer(layer);

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

Agent Seller integration#

Agent generates payment links in dialogue#

Agent Sellers don't "passively mount middleware and wait for buyer requests" — instead, the Agent actively generates a payment link in the dialogue when it needs to charge, and sends it through a messaging channel (XMTP / Telegram / etc.).

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

Install the Onchain OS Skill

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

text

Please install the Onchain OS Payment Skill so my Agent can generate payment links and charge externally.
My payout wallet address: 0xYourSellerWallet

See Agent Seller quickstart.

Generate a payment link

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

text

Buyer Agent: Translate this 3000-word document for me
Seller Agent: Sure, translation service 50 USD₮0.
       [Skill call: createPayment({type:'charge', amount:'50000000', recipient:'0x...'})]
       Payment link: https://pay.okx.com/p/a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB

Each link is one-time and expires automatically after 30 minutes by default.

3
Send the payment link
Send the URL returned by the Skill (in the form https://pay.okx.com/p/a2a_xxx) as a text message to the buyer Agent. The other side parses the URL and uses Agentic Wallet to sign.
4
Poll payment status
The Skill polls GET /payment/{paymentId}/status automatically. When status becomes completed, it notifies the Agent to deliver the service.
text
Skill: Payment completed (tx: 0xabc...) Agent: Payment received, starting translation...

Buyer integration#

Buyers integrate by installing the Onchain OS Skill in their Agent — installing the Skill automatically configures Agentic Wallet as the underlying signing wallet, no separate install. The Skill auto-detects HTTP 402 responses or payment URLs in the messaging channel, calls the wallet to sign, and replays the request — all without manual intervention. Full integration steps in Agent Buyer.

Limits and trade-offs#

When not to use one-time payment

Tiny single-call price + ultra-high call frequency: per-call on-chain settlement is uneconomical → use Batch payment
Long-running relationship + repeated cumulative billing (subscription APIs / Agent multi-step tasks): one channel beats per-call settlement → use Pay-as-you-go
Mutually distrustful parties needing acceptance before payout: use Escrow payment