Overview Wallet Payment Trade Market Data X Layer DApp Connect Wallet

One-time Payment#

HTTP Sellers focus on: Business flow → HTTP Seller integration (scheme selection → exact path (incl. Permit2) / charge path / upto 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?
Fixed, well-defined amount per call (a report / one inference / one query)	✅
Price known before the call, no further consumption afterward	✅
Non-revocable resource (e.g. file download, report generation)	✅ (recommend `syncSettle: true`)
Per-call cost not knowable upfront, needs settling by actual usage (e.g. LLM inference billed per token)	✅ (use `upto`)

Business flow#

The diagram below is the abstract flow — for HTTP sellers it's "triggered by a client request", for Agent sellers it's "the Agent proactively generates a payment link in the conversation", but the Challenge / Credential message semantics are identical for both. See the seller integration sections below for the concrete transport 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 standalone service.

HTTP Seller integration#

Choosing `exact`, `charge`, or `upto`?#

exact — single recipient, supports both sync and async settlement; collects stablecoins by default, and adding Permit2 extends it to any ERC-20.

charge — besides a single recipient, also supports splits, i.e. paying multiple recipients (≤10) in one payment; sync settlement only (the default and only option).

upto — single recipient, price is a cap, settled by actual usage after the call — suitable when the cost isn't knowable upfront.

Dimension	`exact`	`charge`	`upto`
Recipients	Single	Single / multiple (≤10)	Single
When the amount is fixed	Before the call	Before the call	After the call, by actual (≤ cap)
Settlement timing	Sync / async	Sync only (default)	Sync / async
Pricing token	EIP-3009 stablecoins (Permit2 → any ERC-20)	EIP-3009 stablecoins	Any ERC-20 (Permit2)

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

SDK status#

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

Permit2 signing for exact and upto are currently supported only on Node.js / Rust; other languages are coming soon.

`exact` path#

Each tab contains the full install command + implementation code. The architecture is composed of 4 components: Facilitator client (with OKX API Key) → Resource Server (registers the scheme) → Routes config (the accepts array) → Middleware mount.

Node.js

Rust

Java

Python

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 settlement: 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 configuration:

toml

[dependencies]
# This document is based on SDK 0.2.x; for the latest version refer to the release notes
okxweb3-app-x402-axum = "0.2"
okxweb3-app-x402-core = "0.2"
okxweb3-app-x402-evm  = "0.2"

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() -> Result<(), Box<dyn std::error::Error>> {
    let api_key    = std::env::var("OKX_API_KEY")?;
    let secret_key = std::env::var("OKX_SECRET_KEY")?;
    let passphrase = std::env::var("OKX_PASSPHRASE")?;
    let pay_to     = std::env::var("PAY_TO_ADDRESS")?;

    let facilitator = OkxHttpFacilitatorClient::new(&api_key, &secret_key, &passphrase)?;

    let mut server = X402ResourceServer::new(facilitator)
        .register("eip155:196", ExactEvmScheme::new());
    server.initialize().await?;

    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),         // synchronous settlement: wait for on-chain confirmation
            resource: None,
        },
    )]);

    let app = Router::new()
        .route("/api/premium", get(|| async { Json::<Value>(json!({"data": "premium content"})) }))
        .layer(payment_middleware(routes, server));

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

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";                  // Immediate 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 amounts, prioritizing response speed): just set syncSettle = false. The SDK immediately returns 200 + status="pending"; the on-chain result is obtained by polling settleStatus or via the onAfterSettle hook.

Java SDK notes:

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

Install:

bash

pip install okxweb3-app-x402 fastapi uvicorn

python

import os

from fastapi import FastAPI
from x402.http import (
    OKXAuthConfig,
    OKXFacilitatorClient,
    OKXFacilitatorConfig,
    PaymentOption,
)
from x402.http.middleware.fastapi import PaymentMiddlewareASGI
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact.server import ExactEvmScheme
from x402.server import x402ResourceServer

facilitator = OKXFacilitatorClient(
    OKXFacilitatorConfig(
        auth=OKXAuthConfig(
            api_key=os.getenv("OKX_API_KEY", ""),
            secret_key=os.getenv("OKX_SECRET_KEY", ""),
            passphrase=os.getenv("OKX_PASSPHRASE", ""),
        ),
        sync_settle=True,
    )
)

server = x402ResourceServer(facilitator)
server.register("eip155:196", ExactEvmScheme())

routes = {
    "GET /api/premium": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                price="$0.10",
                network="eip155:196",
                pay_to="0xYourSellerWallet",
                max_timeout_seconds=300,
            ),
        ],
        description="Premium API",
        mime_type="application/json",
    ),
}

app = FastAPI()
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)


@app.get("/api/premium")
async def premium():
    return {"data": "premium content"}


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=4000)

Multiple schemes are all declared via the accepts: [...] array; to add aggr_deferred (batch payment), just add another entry to the array — see Batch Payment.

`exact` + Permit2: support any ERC-20#

By default, exact uses EIP-3009 signing and can only collect stablecoins that natively support EIP-3009 (USD₮0 / USDG); buyers need no on-chain approve and pay with a single off-chain signature.

To accept any ERC-20 on X Layer, declare one field in the accepts entry — extra: { assetTransferMethod: "permit2" } — and buyers will sign Permit2 instead. The scheme name stays exact, and the route structure and settlement flow (sync / async) are unchanged; the only difference is that the buyer must do a one-time approve for that token (authorizing the Permit2 contract) on first use.

	EIP-3009 (default)	Permit2
Token range	Only stablecoins that natively support EIP-3009	Any ERC-20
Buyer's first-time cost	Zero (pure signature)	One-time approve to the Permit2 contract
Subsequent payments	Pure signature	Pure signature after approve

Node.js

Rust

package.json:

json

{
  "dependencies": {
    "@okxweb3/x402-core": "^0.2",
    "@okxweb3/x402-evm": "^0.2",
    "@okxweb3/x402-express": "^0.2",
    "express": "^4.19"
  }
}

typescript

import express, { Request, Response } from "express";
import { OKXFacilitatorClient } from "@okxweb3/x402-core";
import { paymentMiddleware, x402ResourceServer } from "@okxweb3/x402-express";
import { ExactEvmScheme } from "@okxweb3/x402-evm/exact/server";

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

const resourceServer = new x402ResourceServer(facilitator)
  .register("eip155:196", new ExactEvmScheme());

// The one difference vs plain `exact`:
//   extra.assetTransferMethod = "permit2"
// tells the buyer to sign Permit2 instead of EIP-3009. Same scheme name
// ("exact"), same route shape — only the transfer method changes.
const routes = {
  "GET /api/premium": {
    accepts: {
      scheme: "exact",
      network: "eip155:196",
      payTo: process.env.PAY_TO_ADDRESS!,
      price: "$0.05",
      extra: { assetTransferMethod: "permit2" },
    },
    description: "Premium API — paid via Permit2 (any ERC-20 on X Layer)",
    mimeType: "application/json",
  },
};

const app = express();
app.use(paymentMiddleware(routes, resourceServer));

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

app.listen(4000, async () => {
  await resourceServer.initialize();
});

Cargo.toml:

toml

[dependencies]
# This doc targets SDK 0.2.x; see the release notes for the latest version
okxweb3-app-x402-axum = "0.2"
okxweb3-app-x402-core = "0.2"
okxweb3-app-x402-evm  = "0.2"

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() -> Result<(), Box<dyn std::error::Error>> {
    let api_key    = std::env::var("OKX_API_KEY")?;
    let secret_key = std::env::var("OKX_SECRET_KEY")?;
    let passphrase = std::env::var("OKX_PASSPHRASE")?;
    let pay_to     = std::env::var("PAY_TO_ADDRESS")?;

    let facilitator = OkxHttpFacilitatorClient::new(&api_key, &secret_key, &passphrase)?;

    let mut server = X402ResourceServer::new(facilitator)
        .register("eip155:196", ExactEvmScheme::new());
    server.initialize().await?;

    // The one difference vs plain `exact`:
    //   extra.assetTransferMethod = "permit2"
    // tells the buyer to sign Permit2 instead of EIP-3009. Same scheme name
    // ("exact"), same route shape.
    let routes = HashMap::from([(
        "GET /api/premium".to_string(),
        RoutePaymentConfig {
            accepts: vec![AcceptConfig {
                scheme: "exact".into(),
                price: "$0.05".into(),
                network: "eip155:196".into(),
                pay_to: pay_to.clone(),
                max_timeout_seconds: None,
                extra: Some(HashMap::from([(
                    "assetTransferMethod".to_string(),
                    json!("permit2"),
                )])),
            }],
            description: "Premium API — paid via Permit2 (USD-pegged stablecoins on X Layer)".into(),
            mime_type: "application/json".into(),
            sync_settle: Some(true),
            resource: None,
        },
    )]);

    let app = Router::new()
        .route("/api/premium", get(|| async { Json::<Value>(json!({"data": "premium content"})) }))
        .layer(payment_middleware(routes, server));

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

Sync vs. async settlement#

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

Mode	Value	Facilitator behavior	When to use
Sync	`true`	Submits the transaction and returns `txHash` after on-chain confirmation	High-value transactions that must be confirmed before delivering the resource
Async	`false`	Returns `txHash` immediately after submitting, without waiting for confirmation	Medium value, with response-speed requirements

Async settlement carries a timing risk: the resource may be delivered before the on-chain payment is finally confirmed. Sync settlement is recommended for high-value transactions. The charge scheme supports sync only (the default and only option).

`charge` path#

SDK status

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

charge doesn't use x402's accepts array; instead it describes each route's price with a ChargeConfig type + MppCharge<T> extractor — the price is returned by an associated function of the type and locked at compile time, so it can't be overridden by the route-config layer.

TypeScript

Rust

Python

package.json:

json

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

typescript

// server.ts
// Start: 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]
# This doc targets SDK 0.2.x; see the release notes for the latest version
okxweb3-app-mpp = "0.2"
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() -> 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, 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)
            recipient: "0x...378211".into(),    // Primary recipient (payee)
            chain_id: 196,                       // X Layer
            fee_payer: Some(true),
            realm: "test realm".into(),
            secret_key,
            splits: None,
            resource_url: None,                  // Set to Some(url) to let SA aggregate revenue by URL
        },
    ));

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

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

Install:

bash

pip install okxweb3-app-mpp fastapi uvicorn

python

import os

from fastapi import FastAPI, Request
from mpp import Credential, Receipt
from mpp.server.mpp import Mpp

from mpp_evm import X_LAYER_CHAIN_ID
from mpp_evm.charge.intent import ChargeIntent
from mpp_evm.method import EvmMethod
from mpp_evm.saclient.client import OKXSAClient


def env(key: str, default: str = "") -> str:
    return os.environ.get(key, default)


TOKEN_ADDRESS = "0x...adb21711"
DECIMALS = 6

sa_client = OKXSAClient(
    base_url=env("OKX_BASE_URL", "https://web3.okx.com"),
    api_key=env("OKX_API_KEY"),
    secret_key=env("OKX_SECRET_KEY"),
    passphrase=env("OKX_PASSPHRASE"),
)

charge_intent = ChargeIntent(
    sa_client=sa_client,
    chain_id=X_LAYER_CHAIN_ID,
    recipient="0x...378211",
    fee_payer=True,
)

method = EvmMethod(intents={"charge": charge_intent})
method.currency = TOKEN_ADDRESS
method.recipient = "0x...378211"
method.decimals = DECIMALS
method.chain_id = X_LAYER_CHAIN_ID

mpp = Mpp(method=method, realm="test realm", secret_key=env("MPP_SECRET_KEY"))

app = FastAPI()

@app.get("/api/premium")
@mpp.pay(amount="0.0001", intent="charge", description="One premium API call")
async def premium(request: Request, credential: Credential, receipt: Receipt) -> dict:
    return {
        "data": "premium content",
        "receipt": {"reference": receipt.reference, "status": receipt.status, "method": receipt.method},
    }


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=4000)

When fee_payer=True, the seller broadcasts the EIP-3009 (transaction mode). amount is a human-readable value, converted to base units by method.decimals ("0.0001" = 100 base units at 6 decimals).

Receipt is a frozen dataclass (no model_dump); read its fields or serialize it with receipt.to_payment_receipt().

`upto` path#

upto is a variant of one-time payment — the buyer first authorizes a payment cap, and after the server completes the request it settles the actual amount (≤ cap) based on the real cost; the over-authorized portion is not charged. If the request ultimately has no billable output, the actual amount can be 0, in which case no on-chain transaction is initiated at all.

Suitable for scenarios that are a single call but whose final amount can only be determined after the request finishes executing, for example: a data query billed by the number of rows actually returned, or a batch validation billed by the number of entries actually processed successfully.

Key differences from exact:

price is a cap, not the amount actually charged; the real amount is filled in by the handler after the request is processed.
upto is based on Permit2 signing (not EIP-3009), but the settlement structure is still "one settlement per request".

upto end-to-end flow (authorize a cap → settle by actual)

upto is based on Permit2 signing; buyers can use any EVM wallet. As with exact + Permit2, the buyer must do a one-time approve for that token (authorizing the Permit2 contract) on first use.

Node.js

Rust

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, { Request, Response } from "express";
import { OKXFacilitatorClient } from "@okxweb3/x402-core";
import {
  paymentMiddleware,
  setSettlementOverrides,
  x402ResourceServer,
} from "@okxweb3/x402-express";
import { UptoEvmScheme } from "@okxweb3/x402-evm/upto/server";

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

const resourceServer = new x402ResourceServer(facilitator)
  .register("eip155:196", new UptoEvmScheme());

// price is the cap, not the actual charge; the handler decides the actual amount.
const routes = {
  "GET /api/usage": {
    accepts: [
      {
        scheme: "upto",
        network: "eip155:196",
        payTo: process.env.PAY_TO_ADDRESS!,
        price: "$0.10",              // The cap the buyer authorizes
        maxTimeoutSeconds: 300,
        // extra omitted — UptoEvmScheme auto-injects the required fields
      },
    ],
    description: "Pay-by-actual-usage demo (upto)",
    mimeType: "application/json",
  },
};

const app = express();
app.use(express.json());
app.use(paymentMiddleware(routes, resourceServer));

app.get("/api/usage", (_req: Request, res: Response) => {
  // Compute the real cost of this request (e.g. tokens × unit price)
  const actualAmount = "$0.034";

  // The middleware reads this header, settles the override amount, and strips the header before responding.
  // amount accepts four formats:
  //   "1234000"  base units
  //   "50%"      percent of the cap
  //   "$0.034"   dollar string (same syntax as price)
  //   "0"        short-circuit — no on-chain transaction
  setSettlementOverrides(res, { amount: actualAmount });

  res.json({ report: { tokens_used: 1342, model: "demo" }, billed: actualAmount });
});

app.listen(4000, async () => {
  await resourceServer.initialize();
});

Cargo.toml configuration:

toml

[dependencies]
# This document is based on SDK 0.2.x; for the latest version refer to the release notes
okxweb3-app-x402-axum = "0.2"
okxweb3-app-x402-core = "0.2"
okxweb3-app-x402-evm  = "0.2"

rust

use std::collections::HashMap;
use axum::{http::StatusCode, response::{IntoResponse, Response}, routing::get, Json, Router};
use serde_json::json;
use x402_axum::{payment_middleware, set_settlement_overrides, AcceptConfig, RoutePaymentConfig, SettlementOverrides};
use x402_core::http::OkxHttpFacilitatorClient;
use x402_core::server::X402ResourceServer;
use x402_evm::UptoEvmScheme;

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

    let facilitator = OkxHttpFacilitatorClient::new(&api_key, &secret_key, &passphrase)?;

    let mut server = X402ResourceServer::new(facilitator)
        .register("eip155:196", UptoEvmScheme::new());
    server.initialize().await?;

    // `price` is the CAP, not the actual charge. The handler decides the
    // real amount per request via set_settlement_overrides().
    let routes = HashMap::from([(
        "GET /api/usage".to_string(),
        RoutePaymentConfig {
            accepts: vec![AcceptConfig {
                scheme: "upto".into(),
                price: "$0.10".into(),          // upper bound the buyer authorizes
                network: "eip155:196".into(),
                pay_to: pay_to.clone(),
                max_timeout_seconds: Some(300),
                extra: None,                    // UptoEvmScheme auto-injects required extras
            }],
            description: "Pay-by-actual-usage demo (upto)".into(),
            mime_type: "application/json".into(),
            sync_settle: Some(true),
            resource: None,
        },
    )]);

    let app = Router::new()
        .route("/api/usage", get(usage_handler))
        .layer(payment_middleware(routes, server));

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

async fn usage_handler() -> Response {
    // amount accepts: base units / "50%" / "$0.034" / "0" (short-circuit, no on-chain tx).
    let actual_amount = "$0.034";

    let body = Json(json!({ "report": { "tokens_used": 1342 }, "billed": actual_amount }));
    let mut resp = (StatusCode::OK, body).into_response();

    // NOT calling set_settlement_overrides => charges the full cap (same as exact).
    set_settlement_overrides(&mut resp, &SettlementOverrides { amount: Some(actual_amount.into()) });
    resp
}

Buyer prerequisite: the Permit2 path requires the buyer wallet to do a one-time approve(PERMIT2_ADDRESS, MAX); see the Permit2 / Upto constants section of the SDK reference for details.

upto is currently supported only on the Node.js / Rust SDKs; Go / Java / Python are coming soon.

Advanced#

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

1. Splits (only `charge`)#

A single payment is automatically split to up to 10 recipients. Common scenarios: platform commission, multi-party revenue sharing, referral commissions.

Hard constraints:

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

Signing overhead: the buyer signs one EIP-3009 per split — 1 for the primary recipient + 1 per split — all submitted together by the seller at /settle.

TypeScript

Rust

Python

package.json:

json

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

typescript

// server.ts
// Start: 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]
# This doc targets SDK 0.2.x; see the release notes for the latest version
okxweb3-app-mpp = "0.2"
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() -> 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")?;

    // Buyer signs one EIP-3009 per split (one to primary + one per entry below).
    let splits = vec![
        ChargeSplit {
            amount: "30".into(),
            recipient: "0x....321a1308".into(),
            memo: Some("partner-a".into()),
        },
        ChargeSplit {
            amount: "20".into(),
            recipient: "0x....d31a6608".into(),
            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(),
            recipient: "0x...378211".into(),    // Primary recipient (payee; receives the remainder after splits)
            chain_id: 196,
            fee_payer: Some(true),
            realm: "test realm".into(),
            secret_key,
            splits: Some(splits),
            resource_url: 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?;
    axum::serve(listener, app).await?;
    Ok(())
}

Install:

bash

pip install okxweb3-app-mpp fastapi uvicorn

Splits aren't supported by the @mpp.pay() decorator; use the lower-level Mpp.charge(..., splits=[...]) and handle the challenge / receipt manually inside the handler. splits and fee_payer are mutually exclusive.

python

import os

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse, Response
from mpp import Challenge
from mpp.server.mpp import Mpp

from mpp_evm import X_LAYER_CHAIN_ID
from mpp_evm.charge.intent import ChargeIntent
from mpp_evm.method import EvmMethod
from mpp_evm.saclient.client import OKXSAClient


def env(key: str, default: str = "") -> str:
    return os.environ.get(key, default)


TOKEN_ADDRESS = "0x...adb21711"
DECIMALS = 6

sa_client = OKXSAClient(
    base_url=env("OKX_BASE_URL", "https://web3.okx.com"),
    api_key=env("OKX_API_KEY"),
    secret_key=env("OKX_SECRET_KEY"),
    passphrase=env("OKX_PASSPHRASE"),
)

charge_intent = ChargeIntent(
    sa_client=sa_client,
    chain_id=X_LAYER_CHAIN_ID,
    recipient="0x...378211",
    fee_payer=False,
)

method = EvmMethod(intents={"charge": charge_intent})
method.currency = TOKEN_ADDRESS
method.recipient = "0x...378211"
method.decimals = DECIMALS
method.chain_id = X_LAYER_CHAIN_ID

mpp = Mpp(method=method, realm="test realm", secret_key=env("MPP_SECRET_KEY"))

SPLITS = [
    {"amount": "30", "recipient": "0x....321a1308", "memo": "partner-a"},
    {"amount": "20", "recipient": "0x....d31a6608", "memo": "partner-b"},
]

app = FastAPI()

@app.get("/api/premium")
async def premium(request: Request):
    result = await mpp.charge(
        authorization=request.headers.get("Authorization"),
        amount="0.0001",
        splits=SPLITS,
    )
    if isinstance(result, Challenge):
        return Response(
            status_code=402,
            headers={"WWW-Authenticate": result.to_www_authenticate(mpp.realm)},
        )
    credential, receipt = result
    return JSONResponse(
        {
            "data": "premium content (split)",
            "receipt": {"reference": receipt.reference, "status": receipt.status, "method": receipt.method},
        },
        headers={"Payment-Receipt": receipt.to_payment_receipt()},
    )


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=4000)

charge split is currently implemented as explicit amounts — each split is an absolute base-units value, not a ratio.

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

TypeScript

Rust

Python

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
// Start: 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]
# This doc targets SDK 0.2.x; see the release notes for the latest version
# OKX dual-protocol router (MPP + x402 on the same URL).
okxweb3-app-payment-router-axum = "0.2"
okxweb3-app-mpp                  = "0.2"
okxweb3-app-x402-core            = "0.2"
okxweb3-app-x402-axum            = "0.2"
okxweb3-app-x402-evm             = "0.2"

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

rust

use std::sync::Arc;

use axum::{routing::get, Json, Router};
use mpp_evm::sa_client::SaApiClient;
use mpp_evm::{EvmCharge, EvmConfig, EvmMpp, OkxSaApiClient};
use payment_router_axum::{
    adapters::{MppAdapter, MppRouteConfig, X402Adapter, X402RouteConfig},
    PaymentRouterConfig, PaymentRouterLayer, ProtocolAdapter, UnifiedRouteConfig,
};
use serde_json::{json, Value};
use x402_axum::AcceptConfig;
use x402_core::http::OkxHttpFacilitatorClient;
use x402_core::server::X402ResourceServer;
use x402_evm::ExactEvmScheme;

const NETWORK: &str = "eip155:196"; // X Layer mainnet

// 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 mpp_secret_key = std::env::var("MPP_SECRET_KEY")?;
    let pay_to         = std::env::var("PAY_TO_ADDRESS")?;

    // —— MPP setup —— EvmMpp facade with charge method.
    let sa: Arc<dyn SaApiClient> = Arc::new(OkxSaApiClient::new(
        okx_api_key.clone(),
        okx_secret_key.clone(),
        okx_passphrase.clone(),
    ));
    let mpp = Arc::new(
        EvmMpp::builder(EvmConfig {
            chain_id: 196,
            recipient: pay_to.clone(),
            secret_key: mpp_secret_key,
            realm: "test realm".into(),
        })
        .with_charge(EvmCharge::new(sa).with_fee_payer(true))
        .build()?,
    );

    // —— x402 setup —— initialize() must run before the adapter sees its first request.
    let facilitator =
        OkxHttpFacilitatorClient::new(&okx_api_key, &okx_secret_key, &okx_passphrase)?;
    let mut x402_server =
        X402ResourceServer::new(facilitator).register(NETWORK, ExactEvmScheme::new());
    x402_server.initialize().await?;

    // —— Per-route config —— each adapter declared once via the unified builder.
    let route = UnifiedRouteConfig::builder()
        .description("AI Image Generation Service")
        .adapter(
            "mpp",
            MppRouteConfig {
                intent: "charge".into(),
                amount: "10000".into(),       // base units
                currency: "0x...adb21711".into(),
                description: Some("AI Image Generation Service".into()),
                external_id: None,
                unit_type: None,
                suggested_deposit: None,
            },
        )
        .adapter(
            "x402",
            X402RouteConfig {
                accepts: vec![AcceptConfig {
                    scheme: "exact".into(),
                    price: "$0.01".into(),
                    network: NETWORK.into(),
                    pay_to: pay_to.clone(),
                    max_timeout_seconds: None,
                    extra: None,
                }],
                description: "AI Image Generation Service".into(),
                mime_type: "application/json".into(),
                sync_settle: None,
                resource: None,
            },
        )
        .build();

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

    let layer = PaymentRouterLayer::new(PaymentRouterConfig {
        routes: vec![("GET /generateImg".into(), route)],
        protocols: vec![mpp_adapter, x402_adapter],
        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(())
}

Install:

bash

pip install okxweb3-app-paymentrouter okxweb3-app-mpp okxweb3-app-x402 fastapi uvicorn

python

import os

from fastapi import Depends, FastAPI

from mpp_evm import X_LAYER_CHAIN_ID, DEFAULT_ESCROW_CONTRACT, FileStore, MppAdapter, MppRouteConfig
from mpp_evm.charge.intent import ChargeIntent
from mpp_evm.method import EvmMethod
from mpp_evm.saclient.client import OKXSAClient
from mpp_evm.session.intent import SessionIntent
from mpp_evm.signer import PrivateKeySigner
from mpp.server.mpp import Mpp

from x402.http import OKXAuthConfig, OKXFacilitatorClient, OKXFacilitatorConfig, PaymentOption
from x402.http import x402HTTPResourceServer
from x402.http.types import RouteConfig as X402RouteConfig
from x402.mechanisms.evm.deferred.server import AggrDeferredEvmScheme
from x402.mechanisms.evm.exact.server import ExactEvmScheme
from x402.server import x402ResourceServer
from x402.adapters import X402Adapter

from paymentrouter import PaymentGate, RouteConfig
from paymentrouter.fastapi.middleware import register_management_handler


def env(key: str, default: str = "") -> str:
    return os.environ.get(key, default)


TOKEN_ADDRESS = "0x...adb21711"
DECIMALS = 6
pay_to = env("PAY_TO_ADDRESS")

sa_client = OKXSAClient(
    base_url=env("OKX_BASE_URL", "https://web3.okx.com"),
    api_key=env("OKX_API_KEY"),
    secret_key=env("OKX_SECRET_KEY"),
    passphrase=env("OKX_PASSPHRASE"),
)

charge_intent = ChargeIntent(
    sa_client=sa_client, chain_id=X_LAYER_CHAIN_ID, recipient=pay_to, fee_payer=True,
)
session_intent = SessionIntent(
    sa_client=sa_client,
    recipient=pay_to,
    signer=PrivateKeySigner.from_hex(env("PRIVATE_KEY")),
    store=FileStore(env("CHANNEL_STORE_DIR", "./mpp-data/channels")),
    chain_id=X_LAYER_CHAIN_ID,
    escrow_contract=env("ESCROW_CONTRACT", DEFAULT_ESCROW_CONTRACT),
    per_request_cost=10,
    min_voucher_delta=30,
    fee_payer=True,
)

method = EvmMethod(intents={"charge": charge_intent, "session": session_intent})
method.currency = TOKEN_ADDRESS
method.recipient = pay_to
method.decimals = DECIMALS
method.chain_id = X_LAYER_CHAIN_ID

mpp = Mpp(method=method, realm="mpp", secret_key=env("MPP_SECRET_KEY"))

facilitator = OKXFacilitatorClient(
    OKXFacilitatorConfig(
        auth=OKXAuthConfig(
            api_key=env("OKX_API_KEY"),
            secret_key=env("OKX_SECRET_KEY"),
            passphrase=env("OKX_PASSPHRASE"),
        ),
        base_url=env("OKX_BASE_URL", "https://web3.okx.com"),
        sync_settle=True,
    )
)

x402_resource = x402ResourceServer(facilitator)
x402_resource.register("eip155:196", ExactEvmScheme())
x402_resource.register("eip155:196", AggrDeferredEvmScheme())
x402_server = x402HTTPResourceServer(x402_resource, routes={})

mpp_adapter = MppAdapter(mpp)
x402_adapter = X402Adapter(x402_server)

paid = PaymentGate(
    protocols=[mpp_adapter, x402_adapter],
    on_error=lambda err, phase, protocol: print(f"[{protocol}] {phase}: {err}"),
)

onetime_cfg: RouteConfig = {
    "mpp": MppRouteConfig(
        intent="charge", amount="0.01", currency=TOKEN_ADDRESS, decimals=DECIMALS,
        description="AI Image Generation Service",
    ),
    "x402": X402RouteConfig(
        accepts=[PaymentOption(
            scheme="exact", price="$0.01", network="eip155:196",
            pay_to=pay_to, max_timeout_seconds=300,
        )],
        description="AI Image Generation Service",
        mime_type="application/json",
    ),
}

app = FastAPI(title="PaymentRouter Demo — Dual Protocol")
register_management_handler(app)

@app.get("/generateImg", dependencies=[Depends(paid.for_route(onetime_cfg))])
async def generate_img():
    return {
        "imageUrl": "https://placehold.co/512x512/png?text=AI+Generated",
        "prompt": "a sunset over mountains",
    }


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=4000)

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 OnchainOS Skill

Send the following prompt to your AI Agent and follow the guided steps to finish installation:

text

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

See the Agent Seller Quickstart.

Generate a payment link

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

text

Buyer Agent: Please translate this 3000-word document for me.
Seller Agent: Sure, translation service is 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 payment URL returned by the Skill (in the form https://pay.okx.com/p/a2a_xxx) to the buyer Agent as a text message; the other side parses the URL and completes signing via 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#

Buyers integrate by installing the Onchain OS Skill on their Agent — installing the Skill automatically configures Agentic Wallet as the underlying signing wallet, with no separate installation needed. The Skill automatically detects HTTP 402 responses or payment URLs in message channels, completes signing via the wallet, then replays the request — no manual buyer involvement at any point. For the full integration steps, see 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
Single call, cost only known afterward: just use upto on this page; only "charging accumulated across many calls" needs Pay-as-you-go
Mutually distrustful parties needing acceptance before payout: use Escrow payment