Tema

Integrate via SDK#

Call the Onchain OS Payment SDK directly. The SDK has the 402 protocol response handling and on-chain transaction verification built in — no custom API implementation required.

Prerequisites#

Recipient wallet: any EVM-compatible wallet (e.g. Agentic Wallet)
API key: apply at the OKX Developer Portal. If your recipient wallet is Agentic Wallet, no API key is required.
Business backend: your own API service or backend server

Install the SDK#

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

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>

Or Java EE 8 / Spring Boot 2:

xml

<dependency>
  <groupId>com.okx</groupId>
  <artifactId>x402-java-javax</artifactId>
  <version>1.0.0</version>
</dependency>

For non-servlet frameworks (Vert.x, Play, Micronaut Netty, etc.), depend on com.okx:x402-java-core directly and implement the X402Request / X402Response adapters.

Integrate the service#

Node.js

Rust

Java

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 || "0xYourWalletAddress";

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 /generateImg": {
        accepts: [{
          scheme: "exact",
          network: NETWORK,
          payTo: PAY_TO,
          price: "$0.01",
        }],
        description: "AI Image Generation Service",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.get("/generateImg", (_req, res) => {
  res.json({
    success: true,
    imageUrl: "https://placehold.co/512x512/png?text=AI+Generated",
    prompt: "a sunset over mountains",
    timestamp: new Date().toISOString(),
  });
});

app.listen(4000, () => {
  console.log("[Seller] Image generation service listening at http://localhost:4000");
});

package main

import (
    "net/http"
    "os"
    "time"

    ginfw "github.com/gin-gonic/gin"
    x402http "github.com/okx/payments/go/x402/http"
    ginmw "github.com/okx/payments/go/x402/http/gin"
    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 /generateImg": {
            Accepts: x402http.PaymentOptions{
                {
                    Scheme:  "exact",
                    Price:   "$0.01",
                    Network: "eip155:196",
                    PayTo:   "0xYourWalletAddress",
                },
            },
            Description: "AI-generated image",
            MimeType:    "image/png",
        },
    }

    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("/generateImg", func(c *ginfw.Context) {
        c.JSON(http.StatusOK, ginfw.H{"image": "https://placehold.co/512x512/png?text=AI+Generated"})
    })

    r.Run(":4000")
}

rust

use std::collections::HashMap;
use axum::{routing::get, Json, Router};
use serde_json::{json, Value};
use x402_axum::{payment_middleware, AcceptConfig, RoutePaymentConfig};
use x402_core::http::OkxHttpFacilitatorClient;
use x402_core::server::X402ResourceServer;
use x402_evm::{AggrDeferredEvmScheme, ExactEvmScheme};

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let api_key = std::env::var("OKX_API_KEY").expect("OKX_API_KEY required");
    let secret_key = std::env::var("OKX_SECRET_KEY").expect("OKX_SECRET_KEY required");
    let passphrase = std::env::var("OKX_PASSPHRASE").expect("OKX_PASSPHRASE required");
    let pay_to = std::env::var("PAY_TO_ADDRESS")
        .unwrap_or_else(|_| "0xb483abdb92...aa6b88c381308".to_string());

    let facilitator = match std::env::var("FACILITATOR_URL") {
        Ok(url) => OkxHttpFacilitatorClient::with_url(&url, &api_key, &secret_key, &passphrase),
        Err(_) => OkxHttpFacilitatorClient::new(&api_key, &secret_key, &passphrase),
    }
    .expect("Failed to create facilitator client");

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

    server.initialize().await.expect("Failed to initialize");

    let routes = HashMap::from([(
        "GET /api/joke".to_string(),
        RoutePaymentConfig {
            accepts: vec![AcceptConfig {
                scheme: "exact".into(),
                price: "$0.001".into(),
                network: "eip155:196".into(),
                pay_to: pay_to.clone(),
                max_timeout_seconds: None,
                extra: None,
            }],
            description: "Get a random joke".into(),
            mime_type: "application/json".into(),
            sync_settle: None,
        },
    )]);

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

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

async fn health() -> Json<Value> {
    Json(json!({ "status": "ok" }))
}

async fn joke() -> Json<Value> {
    Json(json!({
        "joke": "Why do programmers always confuse Halloween and Christmas? Because Oct 31 = Dec 25",
        "price": "$0.001"
    }))
}

java

import com.okx.x402.facilitator.OKXFacilitatorClient;
import com.okx.x402.server.PaymentFilter;
import com.okx.x402.server.PaymentProcessor;
import jakarta.servlet.ServletContext;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.servlet.ServletContextInitializer;

import java.util.Map;

@SpringBootApplication
public class App implements ServletContextInitializer {

    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }

    @Override
    public void onStartup(ServletContext ctx) {
        // 1. Facilitator client (auto HMAC-SHA256 signing)
        OKXFacilitatorClient facilitator = new OKXFacilitatorClient(
                System.getenv("OKX_API_KEY"),
                System.getenv("OKX_SECRET_KEY"),
                System.getenv("OKX_PASSPHRASE"));

        // 2. Route pricing config
        PaymentProcessor.RouteConfig route = new PaymentProcessor.RouteConfig();
        route.scheme  = "exact";
        route.network = "eip155:196";                        // X Layer
        route.payTo   = System.getenv("PAY_TO_ADDRESS");
        route.price   = "$0.01";                             // auto-converted to USDT atomic units

        // 3. Register the Filter in one line
        ctx.addFilter("x402",
                PaymentFilter.create(facilitator, Map.of(
                        "GET /api/data", route)))
           .addMappingForUrlPatterns(null, false, "/api/*");
    }
}

Once running, hit GET /api/data: without PAYMENT-SIG → 402; replay after signing → 200, with the response carrying PAYMENT-RESPONSE settlement proof.

Test the service#

1
Hit the service port via Onchain OS
2
Server returns HTTP 402 with the PAYMENT-REQUIRED header
3
Use Agentic Wallet to complete payment
4
Wallet auto-retries the request
5
Server verifies the payment with the Broker and returns the resource

Innhold

Prerequisites

Install the SDK

Integrate the service

Test the service