Node SDK 参考#

type Network = `${string}:${string}`;
// CAIP-2 format, e.g., "eip155:196", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"

type Money = string | number;
// User-friendly amount, e.g., "$0.01", "0.01", 0.01

type AssetAmount = {
  asset: string;            // Token contract address
  amount: string;           // Amount in token's smallest unit (e.g., "10000" for 0.01 USDC)
  extra?: Record<string, unknown>;  // Scheme-specific data (e.g., EIP-712 domain)
};

type Price = Money | AssetAmount;
// Either a user-friendly amount or a specific token amount

interface ResourceInfo {
  url: string;              // Resource URL path
  description?: string;     // Human-readable description
  mimeType?: string;        // Response content type (e.g., "application/json")
}

type PaymentRequirements = {
  scheme: string;           // Payment scheme: "exact" | "aggr_deferred" | "period"
  network: Network;         // CAIP-2 network identifier
  asset: string;            // Token contract address
  amount: string;           // Price in token's smallest unit
  payTo: string;            // Recipient wallet address
  maxTimeoutSeconds: number; // Payment authorization validity window
  extra: Record<string, unknown>; // Scheme-specific data
};

type PaymentRequired = {
  x402Version: number;       // Protocol version (currently 2)
  error?: string;            // Optional error message
  resource: ResourceInfo;    // Protected resource metadata
  accepts: PaymentRequirements[];  // List of accepted payment options
  extensions?: Record<string, unknown>;  // Extension data (e.g., Bazaar)
};

type PaymentPayload = {
  x402Version: number;       // Must match server's version
  resource?: ResourceInfo;   // Optional resource reference
  accepted: PaymentRequirements;  // The chosen payment option from `accepts`
  payload: Record<string, unknown>;  // Scheme-specific signed data (see below)
  extensions?: Record<string, unknown>;  // Extension data
};

{
  signature: `0x${string}`;     // EIP-712 signature
  authorization: {
    from: `0x${string}`;       // Buyer wallet address
    to: `0x${string}`;         // Seller wallet address
    value: string;              // Amount in smallest unit
    validAfter: string;         // Unix timestamp (start validity)
    validBefore: string;        // Unix timestamp (end validity)
    nonce: `0x${string}`;      // 32-byte unique nonce
  };
}

{
  signature: `0x${string}`;     // Session key signature
  authorization: { /* same as EIP-3009 */ };
  // acceptedExtraOverrides includes sessionCert
}

{
  permitSingle: {                 // Permit2 PermitSingle 授权
    details: { token, amount, expiration, nonce };
    spender: string;              // subscription 合约地址
    sigDeadline: string;
  };
  permitSingleSignature: `0x${string}`;
  terms: {                        // SubscriptionTerms EIP-712 消息（见订阅章节）
    payer, merchant, facilitator, token, amountPerPeriod, periodSec, periodMode,
    maxPeriods, startAt, initialChargePeriods, initialChargeAmount,
    planTier, changeFromSubId, changeEffectiveAt, permitHash, salt, termsDeadline,
  };
  termsSignature: `0x${string}`;
}

type VerifyResponse = {
  isValid: boolean;          // Whether signature is valid
  invalidReason?: string;    // Machine-readable reason code
  invalidMessage?: string;   // Human-readable error message
  payer?: string;            // Recovered payer address
  extensions?: Record<string, unknown>;
};

type SettleResponse = {
  success: boolean;          // Whether settlement succeeded
  status?: "pending" | "success" | "timeout";  // OKX extension
  errorReason?: string;      // Machine-readable error code
  errorMessage?: string;     // Human-readable error message
  payer?: string;            // Payer address
  transaction: string;       // On-chain transaction hash (empty for aggr_deferred)
  network: Network;          // Settlement network
  amount?: string;           // Actual settled amount (may differ for "upto")
  extensions?: Record<string, unknown>;
};

type SupportedKind = {
  x402Version: number;
  scheme: string;
  network: Network;
  extra?: Record<string, unknown>;
};

type SupportedResponse = {
  kinds: SupportedKind[];
  extensions: string[];      // Supported extension keys
  signers: Record<string, string[]>;  // CAIP family → signer addresses
};

import { x402ResourceServer } from "@okxweb3/x402-core/server";

const server = new x402ResourceServer(facilitatorClients?);
// facilitatorClients: FacilitatorClient | FacilitatorClient[]

server
  .register("eip155:84532", new ExactEvmScheme())
  .register("eip155:196", new AggrDeferredEvmScheme())
  .register("eip155:196", new PermitSubscriptionScheme({ /* ... */ }));  // 订阅

interface ResourceServerExtension {
  key: string;
  enrichDeclaration?: (declaration: unknown, transportContext: unknown) => unknown;
  enrichPaymentRequiredResponse?: (
    declaration: unknown,
    context: PaymentRequiredContext,
  ) => Promise<unknown>;
  enrichSettlementResponse?: (
    declaration: unknown,
    context: SettleResultContext,
  ) => Promise<unknown>;
}

await server.initialize();

interface ResourceConfig {
  scheme: string;               // "exact" | "aggr_deferred" | "upto" | "period"
  payTo: string;                // Recipient wallet address
  price: Price;                 // "$0.01" or AssetAmount
  network: Network;             // "eip155:196"
  maxTimeoutSeconds?: number;   // Default: 300
  extra?: Record<string, unknown>;
}

const reqs = await server.buildPaymentRequirements({
  scheme: "exact",
  payTo: "0xSeller",
  price: "$0.01",
  network: "eip155:196",
});

const reqs = await server.buildPaymentRequirementsFromOptions(
  [
    {
      scheme: "exact",
      network: "eip155:196",
      payTo: (ctx) => ctx.sellerId === "A" ? "0xWalletA" : "0xWalletB",
      price: (ctx) => ctx.premium ? "$0.10" : "$0.01",
    },
  ],
  requestContext
);

const result = await server.verifyPayment(paymentPayload, requirements);
// result.isValid: boolean

const result = await server.settlePayment(
  paymentPayload,
  requirements,
  declaredExtensions?,     // Extension data from 402 response
  transportContext?,       // HTTP transport context
  settlementOverrides?,    // { amount: "$0.05" } for upto scheme
);

server.onBeforeVerify(async (ctx) => {
  // Log or gate verification
});

server.onAfterSettle(async (ctx) => {
  console.log(`Settled: ${ctx.result.transaction} on ${ctx.result.network}`);
});

server.onSettleFailure(async (ctx) => {
  if (ctx.error.message.includes("timeout")) {
    return { recovered: true, result: { success: true, transaction: "", network: "eip155:196" } };
  }
});

import { x402HTTPResourceServer } from "@okxweb3/x402-core/http";

const httpServer = new x402HTTPResourceServer(resourceServer, routes);

type RoutesConfig = Record<string, RouteConfig> | RouteConfig;

interface RouteConfig {
  accepts: PaymentOption | PaymentOption[];  // Accepted payment methods
  resource?: string;           // Override resource name
  description?: string;        // Human-readable description
  mimeType?: string;           // Response MIME type
  customPaywallHtml?: string;  // Custom HTML for browser 402 page
  unpaidResponseBody?: (ctx: HTTPRequestContext) => HTTPResponseBody | Promise<HTTPResponseBody>;
  settlementFailedResponseBody?: (ctx, result) => HTTPResponseBody | Promise<HTTPResponseBody>;
  extensions?: Record<string, unknown>;

  // ── 订阅（period）专属 ─────────────────────────────
  /**
   * 订阅特殊操作路由：
   *   "change"                 — 切换套餐（升 / 降级；同一 URL 分两阶段）
   *   "cancel"                 — 取消订阅
   *   "cancel-pending-change"  — 撤销排队中的降级
   * 未设置 → 普通访问路由。
   */
  operation?: "change" | "cancel" | "cancel-pending-change";

  /**
   * 路由级 onBeforeAccess，语义与 httpServer.onBeforeAccess() 相同，
   * 仅作用于本 route；在所有 seller 全局 hook 之后执行。
   */
  onBeforeAccess?: OnBeforeAccessHook;
}

interface PaymentOption {
  scheme: string;              // "exact" | "aggr_deferred" | "upto" | "period"
  payTo: string | DynamicPayTo;  // Static or dynamic recipient
  price: Price | DynamicPrice;   // Static or dynamic price
  network: Network;
  maxTimeoutSeconds?: number;
  extra?: Record<string, unknown>;
}

// Dynamic functions receive HTTPRequestContext
type DynamicPayTo = (context: HTTPRequestContext) => string | Promise<string>;
type DynamicPrice = (context: HTTPRequestContext) => Price | Promise<Price>;

type OnSettlementTimeoutHook = (txHash: string, network: string) => Promise<{ confirmed: boolean }>;

httpServer.onSettlementTimeout(async (txHash, network) => {
  // Custom recovery logic
  return { confirmed: false };
});

type ProtectedRequestHook = (
  context: HTTPRequestContext,
  routeConfig: RouteConfig,
) => Promise<void | { grantAccess: true } | { abort: true; reason: string }>;

httpServer.onProtectedRequest(async (ctx, config) => {
  // Grant free access for certain users
  if (ctx.adapter.getHeader("x-api-key") === "internal") {
    return { grantAccess: true };
  }
});

httpServer.onBeforeAccess(async (ctx) => {
  if (banList.has(ctx.subscription.subId)) return { ok: false, error: "banned" };
  return { ok: true };
});

import {
  paymentMiddleware,
  paymentMiddlewareFromConfig,
  paymentMiddlewareFromHTTPServer,
  setSettlementOverrides,
} from "@okxweb3/x402-express";

// From pre-configured server (recommended)
app.use(paymentMiddleware(routes, server, paywallConfig?, paywall?, syncFacilitatorOnStart?));

// From config (creates server internally)
app.use(paymentMiddlewareFromConfig(routes, facilitatorClients?, schemes?, paywallConfig?, paywall?, syncFacilitatorOnStart?));

// From HTTP server (most control) — 订阅场景需要挂 onBeforeAccess 时用这个
app.use(paymentMiddlewareFromHTTPServer(httpServer, paywallConfig?, paywall?, syncFacilitatorOnStart?));

// Settlement override in handler (for "upto" scheme)
app.post("/api/generate", (req, res) => {
  setSettlementOverrides(res, { amount: "$0.05" });
  res.json({ result: "..." });
});

import {
  paymentProxy,
  paymentProxyFromConfig,
  paymentProxyFromHTTPServer,
  withX402,
  withX402FromHTTPServer,
} from "@okxweb3/x402-next";

// As global middleware (middleware.ts)
const proxy = paymentProxy(routes, server, paywallConfig?, paywall?, syncFacilitatorOnStart?);
export async function middleware(request: NextRequest) { return proxy(request); }
export const config = { matcher: ["/api/:path*"] };

// Per-route wrapper (app/api/data/route.ts)
export const GET = withX402(handler, routeConfig, server, paywallConfig?, paywall?, syncFacilitatorOnStart?);
export const GET = withX402FromHTTPServer(handler, httpServer, paywallConfig?, paywall?, syncFacilitatorOnStart?);

import { paymentMiddleware, paymentMiddlewareFromConfig, paymentMiddlewareFromHTTPServer } from "@okxweb3/x402-hono";

app.use("/*", paymentMiddleware(routes, server, paywallConfig?, paywall?, syncFacilitatorOnStart?));

import { paymentMiddleware, paymentMiddlewareFromConfig, paymentMiddlewareFromHTTPServer } from "@okxweb3/x402-fastify";

// NOTE: Fastify registers hooks directly, returns void
paymentMiddleware(app, routes, server, paywallConfig?, paywall?, syncFacilitatorOnStart?);

import { ExactEvmScheme } from "@okxweb3/x402-evm";

const scheme = new ExactEvmScheme();  // No constructor args for server-side
scheme.scheme;  // "exact"
// Automatically handles price parsing, EIP-712 domain injection

import { AggrDeferredEvmScheme } from "@okxweb3/x402-evm/deferred/server";

const scheme = new AggrDeferredEvmScheme();
scheme.scheme;  // "aggr_deferred"
// Delegates to ExactEvmScheme for price parsing

import { PermitSubscriptionScheme } from "@okxweb3/x402-evm/subscription";

const scheme = new PermitSubscriptionScheme({
  facilitator,               // SubscriptionFacilitatorClient
  network: "eip155:196",
  store,                     // SubscriptionStore（与 SubscriptionClient 共享同一实例）
  accessProofWindowSec: 300, // AccessProof 时间窗，默认 ±300s
});
scheme.scheme;  // "period"

npm install @okxweb3/x402-axios @okxweb3/x402-evm @okxweb3/x402-core axios

import axios from "axios";
import { wrapAxiosWithPaymentFromConfig } from "@okxweb3/x402-axios";
import { ExactEvmScheme, toClientEvmSigner } from "@okxweb3/x402-evm";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { xLayer } from "viem/chains";

// 用买家私钥构造 viem signer
const signer = toClientEvmSigner(
  createWalletClient({
    account: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`),
    chain: xLayer,
    transport: http(),
  }),
);

const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
  schemes: [
    {
      network: "eip155:196", // X Layer；用 "eip155:*" 可匹配任意 EVM 链
      client: new ExactEvmScheme(signer),
    },
  ],
});

// 402 → 签名 → 重发，对调用方完全透明
const response = await api.get("https://api.example.com/paid-endpoint");

npm install @okxweb3/x402-fetch @okxweb3/x402-evm @okxweb3/x402-core

import { wrapFetchWithPaymentFromConfig } from "@okxweb3/x402-fetch";
import { ExactEvmScheme, toClientEvmSigner } from "@okxweb3/x402-evm";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { xLayer } from "viem/chains";

const signer = toClientEvmSigner(
  createWalletClient({
    account: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`),
    chain: xLayer,
    transport: http(),
  }),
);

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [
    {
      network: "eip155:196",
      client: new ExactEvmScheme(signer),
    },
  ],
});

const response = await fetchWithPayment("https://api.example.com/paid-endpoint");

import axios from "axios";
import { wrapAxiosWithPayment, x402Client } from "@okxweb3/x402-axios";
import { ExactEvmScheme, toClientEvmSigner } from "@okxweb3/x402-evm";

const client = new x402Client()
  .register("eip155:196", new ExactEvmScheme(signer));

const api = wrapAxiosWithPayment(axios.create(), client);

import { decodePaymentResponseHeader } from "@okxweb3/x402-axios"; // 或 "@okxweb3/x402-fetch"

// Axios
const paymentResponse = response.headers["payment-response"];
// Fetch
// const paymentResponse = response.headers.get("PAYMENT-RESPONSE");

if (paymentResponse) {
  const receipt = decodePaymentResponseHeader(paymentResponse);
  console.log("支付回执：", receipt);
}

type PaymentPolicy = (
  x402Version: number,
  paymentRequirements: PaymentRequirements[],
) => PaymentRequirements[];

import {
  wrapAxiosWithPaymentFromConfig,
  type PaymentPolicy,
} from "@okxweb3/x402-axios";

// 拒绝单笔超过 1 USDT（1_000_000 原子单位，6 位小数）的支付
const maxAmountPolicy: PaymentPolicy = (_version, reqs) =>
  reqs.filter(r => BigInt(r.amount) <= 1_000_000n);

// 仅允许 X Layer 主网
const xLayerOnlyPolicy: PaymentPolicy = (_version, reqs) =>
  reqs.filter(r => r.network === "eip155:196");

// 同时提供两种 scheme 时优先选 "exact"
const preferExactPolicy: PaymentPolicy = (_version, reqs) => {
  const exact = reqs.filter(r => r.scheme === "exact");
  return exact.length > 0 ? exact : reqs;
};

const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
  schemes: [{ network: "eip155:196", client: new ExactEvmScheme(signer) }],
  policies: [maxAmountPolicy, xLayerOnlyPolicy, preferExactPolicy],
});

type SelectPaymentRequirements = (
  x402Version: number,
  paymentRequirements: PaymentRequirements[],
) => PaymentRequirements;

const cheapestFirst: SelectPaymentRequirements = (_version, reqs) =>
  [...reqs].sort((a, b) => Number(BigInt(a.amount) - BigInt(b.amount)))[0];

const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(signer) }],
  paymentRequirementsSelector: cheapestFirst,
});

import { wrapAxiosWithPayment, x402Client } from "@okxweb3/x402-axios";
import { ExactEvmScheme } from "@okxweb3/x402-evm";

const client = new x402Client()
  .register("eip155:196", new ExactEvmScheme(signer))
  // 1. 签名前 —— 可整体中止支付
  .onBeforePaymentCreation(async ({ paymentRequired, selectedRequirements }) => {
    const tooExpensive = BigInt(selectedRequirements.amount) > 5_000_000n;
    if (tooExpensive) {
      return { abort: true, reason: "金额超出买家策略上限" };
    }
  })
  // 2. 签名成功后 —— 仅观察（日志、埋点）
  .onAfterPaymentCreation(async ({ paymentPayload }) => {
    console.log("已签名 payload nonce：", paymentPayload.payload?.authorization?.nonce);
  })
  // 3. 签名失败时 —— 可返回手动构造的 payload 进行恢复
  .onPaymentCreationFailure(async ({ error }) => {
    console.error("payment 创建失败：", error.message);
    // return { recovered: true, payload: fallbackPayload };
  });

const api = wrapAxiosWithPayment(axios.create(), client);

client.registerExtension({
  key: "eip2612GasSponsoring",
  async enrichPaymentPayload(payload, paymentRequired) {
    // 签 EIP-2612 permit，挂在 payload.extensions 上
    return { ...payload, extensions: { ...payload.extensions, /* ... */ } };
  },
});

import { OKXFacilitatorClient } from "@okxweb3/x402-core";
import { x402HTTPResourceServer, x402ResourceServer } from "@okxweb3/x402-core/server";
import {
  InMemoryStore,
  SubscriptionClient,
  type Subscription, type SubscriptionState, type PendingPlanChange,
  type PlanCatalogEntry, type PlanInitialCharge,
  type AccessProof, type CancelAuth, type PendingChangeCancelAuth,
  type ChargeResult,
  type SettleSubscribeResult, type SettleChangeResult,
  type SettleCancelResult, type SettleCancelPendingChangeResult,
  type SubscriptionCapability, type SubscriptionStore,
  type OnBeforeAccessHook, type OnBeforeAccessContext, type OnBeforeAccessResult,
  type AccessRouteRequirements,
} from "@okxweb3/x402-core/subscription";
import { PermitSubscriptionScheme } from "@okxweb3/x402-evm/subscription";
import { paymentMiddleware, paymentMiddlewareFromHTTPServer } from "@okxweb3/x402-express";

new PermitSubscriptionScheme({
  facilitator: SubscriptionFacilitatorClient,   // OKXFacilitatorClient / HTTPFacilitatorClient
  network: Network,                             // "eip155:196"
  store: SubscriptionStore,                     // 与 SubscriptionClient 共享
  accessProofWindowSec?: number,                // 默认 300（±300s）
});

class SubscriptionClient {
  constructor(config: { scheme: SubscriptionCapability; store: SubscriptionStore });

  charge(subId: string): Promise<ChargeResult>;
  cancelBySeller(subId: string, auth: CancelAuth, reason?: string): Promise<void>;
  syncFromChain(subId: string): Promise<Subscription | null>;
  getSubscription(subId: string): Promise<Subscription | null>;
}

interface SubscriptionStore {
  get(subId: string): Promise<Subscription | null>;
  put(sub: Subscription): Promise<void>;
  delete(subId: string): Promise<void>;
  list(): Promise<Subscription[]>;
}

interface SubscriptionFacilitatorClient {
  subscribe(payload, requirements): Promise<...>;
  changeSubscription(payload, requirements): Promise<...>;
  cancelSubscription(subId, auth): Promise<...>;
  cancelPendingChange(subId, auth): Promise<...>;
  chargeSubscription(subId): Promise<...>;
  getSubscription(subId): Promise<...>;
  finalizeExpired(subId): Promise<...>;
  getCharges(subId): Promise<...>;
  getPendingChange(subId): Promise<...>;
}

interface Subscription {
  subId: string;
  payer: string;
  merchant: string;
  token: string;
  amountPerPeriod: string;
  periodMode: number;              // 0 fixed_seconds / 1 calendar_month
  periodSec: number;
  billingAnchorAt?: number;        // 自然月锚点（Unix s），fixed 模式为 undefined 或 0
  maxPeriods: number;
  startAt: number;
  state: SubscriptionState;
  lastChargedPeriod: number;
  totalPulled: string;             // 已扣总额
  planId: string;
  planTier: number;
  changedToSubId?: string;         // state === "changed" 时指向新 sub
  pendingPlanChange?: PendingPlanChange;

  // 读时刻派生（随墙钟漂移；判断过期请用 elapsedPeriods）
  isActive?: boolean;
  serviceEnded?: boolean;
  currentPeriod?: number;
  elapsedPeriods?: number;
  nextChargeableAt?: number;       // 下一次可扣时间点（Unix s），全部扣完为 null
}

type SubscriptionState =
  | "pending"     // 0 — 已上链，等待激活
  | "active"      // 1 — 活跃
  | "completed"   // 2 — maxPeriods 全部扣完
  | "canceled"    // 3 — 已取消
  | "changed"     // 4 — 已被切换（changedToSubId 指向新 sub）
  | "failed";     // 99 — 上链失败 / 异常

interface PendingPlanChange {
  subId: string;                  // 当前订阅
  newSubId: string;               // 降级后新 sub id
  effectiveFromPeriod: number;    // 从第几期开始切换
  state: number;                  // 0 pending / 1 activated / 2 canceled / 3 expired
}

interface PlanCatalogEntry {
  id: string;                     // 业务 plan id（访问校验按此比对）
  tier: number;                   // 数字越大等级越高
  amountPerPeriod: string;        // 每期扣款金额（token base units）
  periodMode?: 0 | 1;             // 0 fixed_seconds / 1 calendar_month
  periodSec: number;              // 周期长度（秒）
  maxPeriods: number;             // 最多扣款期数
  asset?: string;                 // ERC-20；不填 → SDK 用 network 默认稳定币
  payTo: string;
  initialCharge?: PlanInitialCharge;
  name?: string;
}

interface PlanInitialCharge {
  periodCount: number;            // 首扣覆盖多少期
  totalAmount: string;            // 首扣总额（≤ periodCount × amountPerPeriod）
}

interface AccessProof {
  kind: "subscription-id";
  subId: string;
  payer: string;
  timestamp: number;
  signature: string;
}

interface CancelAuth {
  action: 0;                      // 固定 0 = cancel_subscription
  subId: string;
  initiator: 0 | 1;               // 0=payer / 1=merchant
  nonce: string;
  deadline: number;
  signature: string;
}

interface PendingChangeCancelAuth {
  subId: string;
  newSubId: string;               // 必须等于当前 pendingPlanChange.newSubId
  nonce: string;
  deadline: number;
  signature: string;
}

type VerifyResultOk    = { ok: true };
type VerifyResultFail  = { ok: false; error: string };

interface VerifyAccessOk    { ok: true; subscription: Subscription; }
interface VerifyOwnershipOk { ok: true; subId: string; payer: string; subscription: Subscription; }
interface VerifyChangeOk    { ok: true; oldSubId: string; direction: "upgrade" | "downgrade"; }

type SettleResultFail = {
  success: false;
  error: string;
  subId?: string;                 // pending=true 时 seller 可后续 syncFromChain(subId)
  pending?: boolean;
};

interface SettleSubscribeOk           { success: true; subId: string; subscription: Subscription; headers: Record<string, string>; }
interface SettleChangeOk              { success: true; oldSubId: string; newSubId: string; operationType: "upgrade" | "downgrade"; scheduledFromPeriod?: number; headers: Record<string, string>; }
interface SettleCancelOk              { success: true; subId: string; headers: Record<string, string>; }
interface SettleCancelPendingChangeOk { success: true; subId: string; headers: Record<string, string>; }

interface ChargeResult {
  success: true;
  period: number;                 // 本次扣款推进到的期数
  amount: string;                 // 本次扣款金额（base units）
  txHash?: string;
  planChangeTriggered?: boolean;  // 排队中的降级此次激活
  newSubId?: string;              // planChangeTriggered=true 时的新 sub id
}

interface SubscriptionCapability {
  readonly settlementMode: "pre";       // 中间件采用"先 settle 再 handler"

  verifySubscribe(payload, requirements): Promise<VerifyResult>;
  settleSubscribe(payload, requirements): Promise<SettleSubscribeResult>;

  enrichAcceptsForChange(accepts: PaymentRequirements[], currentSubId: string): Promise<PaymentRequirements[] | null>;
  verifyChange(payload, requirements): Promise<VerifyChangeResult>;
  settleChange(payload, requirements): Promise<SettleChangeResult>;

  verifyCancel(auth: CancelAuth, subId: string): Promise<VerifyResult>;
  settleCancel(auth: CancelAuth, subId: string): Promise<SettleCancelResult>;

  verifyCancelPendingChange(auth: PendingChangeCancelAuth, subId: string): Promise<VerifyResult>;
  settleCancelPendingChange(auth: PendingChangeCancelAuth, subId: string): Promise<SettleCancelPendingChangeResult>;

  verifyAccess(proof: AccessProof, route: AccessRouteRequirements): Promise<VerifyAccessResult>;
  verifyOwnership(proof: AccessProof): Promise<VerifyOwnershipResult>;

  charge(subId: string): Promise<ChargeResult>;
  getSubscription(subId: string): Promise<Subscription | null>;
}

interface OnBeforeAccessContext {
  subscription: Subscription;                     // 命中订阅的完整快照
  request: {
    path: string;                                 // 请求 pathname（真实值）
    method: string;                               // HTTP method（真实值）
    headers: Record<string, string>;              // 全部请求头（小写 key）；adapter 未实现 getHeaders 则为 {}
  };
  route: AccessRouteRequirements;                 // 本 route 的 plan 声明
}

type OnBeforeAccessResult =
  | { ok: true }
  | {
      ok: false;
      error?: string;                             // 直接进 402 响应体
      retryAfter?: number;                        // 进 Retry-After 响应头
      upgradeOffers?: PaymentRequirements[];      // 建议买家改用的 accept 列表
    };

type OnBeforeAccessHook = (ctx: OnBeforeAccessContext) => Promise<OnBeforeAccessResult>;

interface AccessRouteRequirements {
  acceptedPlanIds?: string[];             // route accepts 里的 plan id 白名单
  accepts?: PaymentRequirements[];        // 完整 accepts；extra.plan = { id, tier, name }
                                          // 同时带 extra.amountPerPeriod / extra.periodSec /
                                          // extra.periodMode / extra.maxPeriods
}

{
  contracts: { subscription: string; permit2: string };
  facilitator: string;                     // 从 /supported.extra.facilitatorAddress 拷贝
  amountPerPeriod: string;
  periodSec: number;
  periodMode?: number;                     // 0 fixed_seconds / 1 calendar_month
  maxPeriods: number;
  startAt?: number;
  initialCharge?: PlanInitialCharge;
  plan: { id: string; tier: number; name?: string };
  changeFrom?: ChangeFromExtra;            // 只在 operation="change" 的 402 里出现
  domain: TypedDataDomain;                 // EIP-712 域（name / version / chainId / verifyingContract）
}

{
  fromSubId: string;
  fromPlanId: string;
  fromPlanTier: number;
  direction: "upgrade" | "downgrade";
  effectiveAt: "immediate" | "period_end";
}

SubscriptionTerms(
  address payer,
  address merchant,
  address facilitator,
  address token,
  uint256 amountPerPeriod,
  uint256 periodSec,
  uint8   periodMode,
  uint256 maxPeriods,
  uint256 startAt,
  uint256 initialChargePeriods,
  uint256 initialChargeAmount,
  uint256 planTier,
  bytes32 changeFromSubId,
  uint8   changeEffectiveAt,        // 0=none / 1=immediate / 2=period_end
  bytes32 permitHash,
  bytes32 salt,
  uint64  termsDeadline
)

app.post("/subscription/cancel", (req, res) => {
  const x402 = (req as any).x402;
  res.json({ subId: x402.settleResult?.data?.subId });
});

npm install @okxweb3/mpp viem

// 顶层：mppx runtime + 命名空间
import { Mppx, Errors } from '@okxweb3/mpp'

// EVM 共用：SA API 客户端、EIP-712 工具
import { SaApiClient, verifyVoucher, buildSettleAuth } from '@okxweb3/mpp/evm'

// EVM 服务端工厂
import { charge, session } from '@okxweb3/mpp/evm/server'

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: 'demo.merchant.com',
  secretKey: process.env.MPPX_SECRET_KEY!,
})

async function premium(request: Request): Promise<Response> {
  const result = await mppx.charge({
    amount: '100',
    currency: '0xA8CE8aee21bC2A48a5EF670afCc9274C7bbbC035',
    recipient: '0x742d35Cc6634c0532925a3b844bC9e7595F8fE00',
    methodDetails: { feePayer: true },     // chainId 默认 196
  })(request)

  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json({ data: 'premium content' }))
}

type ChargeOptions = {
  amount: string                  // 扣费金额，base units 整数字符串
  currency: string                // ERC-20 合约 EVM 地址
  recipient: string               // 收款方 EVM 地址
  description?: string            // 描述，写入 challenge
  externalId?: string             // 商户订单号，回带在 receipt 上
  methodDetails: {
    chainId?: number              // 默认 196 (X Layer)
    feePayer?: boolean            // true = 服务端代付 gas（仅 transaction 模式）
    permit2Address?: string       // Uniswap Permit2 合约地址
    splits?: ChargeSplit[]        // 分账，最多 10 项
    resourceUrl?: string          // Endpoint URL，用于后台按 URL 维度统计（见下方"resourceUrl 用法"）
  }
}

type ChargeSplit = {
  amount: string                  // 该路收款 base units
  recipient: string               // 该路收款方 EVM 地址
  memo?: string
}

methodDetails: {
  feePayer: true,
  splits: [
    { amount: '30', recipient: '0x...', memo: 'partner-a' },
    { amount: '20', recipient: '0x...', memo: 'partner-b' },
  ],
}

async function handler(request: Request): Promise<Response> {
  const result = await mppx.charge({
    amount: '100',
    currency: '0xA8CE8aee21bC2A48a5EF670afCc9274C7bbbC035',
    recipient: '0x742d35Cc6634c0532925a3b844bC9e7595F8fE00',
    methodDetails: {
      feePayer: true,
      resourceUrl: 'https://api.myshop.com/v1/reports',   // 按此 URL 打点
    },
  })(request)

  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json({ data: '...' }))
}

Seller SDK (mppx.charge)
   └── methodDetails.resourceUrl
        ↓ base64url 编入 ChargeRequest → PaymentChallenge.request
Buyer 回显 (ChallengeEcho)
        ↓ POST /charge/settle | /charge/verifyHash
SA API 后端（按 resourceUrl 归集统计）

import { privateKeyToAccount } from 'viem/accounts'

const sellerSigner = privateKeyToAccount(process.env.MERCHANT_PK as `0x${string}`)

const mppx = Mppx.create({
  methods: [session({ saClient, signer: sellerSigner })],
  realm: 'demo.merchant.com',
  secretKey: process.env.MPPX_SECRET_KEY!,
})

type SessionParameters = {
  saClient: SaApiClient                  // 必填
  signer: SessionSigner                  // 必填，settle / close 时签 EIP-712 授权
  chainId?: number                       // 默认 196
  escrowContract?: Hex                   // 默认 0x5E550002e64FaF79B41D89fE8439eEb1be66CE3b
  domainName?: string                    // 默认 "EVM Payment Channel"
  domainVersion?: string                 // 默认 "1"
  store?: SessionStore                   // 默认进程内存 store
  minVoucherDelta?: string               // 默认 "0"，base units
}

/** 卖家签名能力。viem 的 LocalAccount / WalletClient.account 都满足。 */
type SessionSigner = {
  signTypedData: <const td extends TypedDataDefinition>(p: td) => Promise<Hex>
}

async function meter(request: Request): Promise<Response> {
  const result = await mppx.session({
    amount: '100',
    currency: '0x...',
    recipient: '0x...',
    unitType: 'request',
    suggestedDeposit: '10000',
    methodDetails: {},                    // chainId / escrowContract 自动用工厂默认
  })(request)

  if (result.status === 402) return result.challenge
  // open / topUp / close 这三个管理动作 SDK 强制返 204；
  // 只有 voucher 动作真正交付资源，下面这行 Response 会被透传。
  return result.withReceipt(Response.json({ data: 'metered content' }))
}

type SessionOptions = {
  amount: string                  // 单价，base units
  currency: string                // ERC-20 EVM 地址
  recipient: string               // 收款方 EVM 地址
  description?: string
  externalId?: string
  unitType?: string               // "request" | "byte" | "llm_token" | ...
  suggestedDeposit?: string       // 建议初次开通存入金额，base units
  methodDetails: {
    chainId?: number              // 工厂默认兜底
    escrowContract?: string       // 工厂默认兜底
    channelId?: string
    minVoucherDelta?: string      // 节流：voucher 最小递增量
    feePayer?: boolean
    splits?: SessionSplit[]       // 按 bps 分润
  }
}

type SessionSplit = {
  recipient: string
  bps: number                     // basis points（1‒9999），sum(bps) < 10000
  memo?: string
}

/** 用本地最高 voucher 提链上结算（不关闭通道）。
 *  自动签 SettleAuthorization 并提交。 */
mppx.session.settle(channelId: string): Promise<SessionReceipt>

/** 查询链上通道状态。 */
mppx.session.status(channelId: string): Promise<ChannelStatus>

interface SessionReceipt {
  method: string                  // "evm"
  intent: string                  // "session"
  status: string                  // "success"
  timestamp: string               // RFC 3339
  channelId: string
  chainId: number
  reference?: string              // tx hash（transaction 模式）
  deposit: string                 // 链上 escrow 当前存款总额
}

interface ChannelStatus {
  channelId: string
  payer: string
  payee: string
  token: string
  deposit: string
  settledOnChain: string          // 已链上结算金额（settle 后才更新）
  sessionStatus: 'OPEN' | 'CLOSING' | 'CLOSED'
  remainingBalance: string        // = deposit - cumulativeAmount
}

interface SessionStore {
  get(channelId: string):
    Promise<ChannelState | null> | ChannelState | null
  set(channelId: string, state: ChannelState):
    Promise<void> | void
  delete(channelId: string):
    Promise<void> | void

  /** read-modify-write 整体原子。
   *  state 不存在时不调 mutator，直接返 null。
   *  实现侧需保证 mutator 调用期间无并发写入。 */
  update(channelId: string, mutator: ChannelMutator):
    Promise<ChannelState | null> | ChannelState | null
}

/** 同步纯函数，对 state 就地修改；抛错回滚不写入。
 *  不要在 mutator 内做异步 IO（实现可能多次调用它）。 */
type ChannelMutator = (state: ChannelState) => void

interface ChannelState {
  channelId: Hex                  // 主键 = 链上 channelId
  chainId: number
  escrowContract: Hex
  domainName: string
  domainVersion: string
  signer: Hex                     // 期望的 voucher 签名者
  deposit: bigint                 // 链上 escrow 当前存款
  spent: bigint                   // 本地累计已扣
  units: number                   // 计费次数
  highestVoucherAmount: bigint    // 已接受的最高 voucher 金额
  highestVoucher:                 // 字节值（幂等 + idle close 用）
    | { cumulativeAmount: string; signature: Hex }
    | null
  challengeEcho: ChallengeEcho
  createdAt: string               // ISO 8601
}

DEFAULT_DOMAIN_NAME    = 'EVM Payment Channel'
DEFAULT_DOMAIN_VERSION = '1'

function verifyVoucher(params: {
  chainId: number
  escrowContract: Hex
  channelId: Hex
  cumulativeAmount: string | bigint
  signature: Hex
  expectedSigner: Hex
  domainName?: string             // 默认 "EVM Payment Channel"
  domainVersion?: string          // 默认 "1"
}): Promise<boolean>

function buildSettleAuth(p: AuthMessageParams): TypedDataDefinition
function buildCloseAuth(p: AuthMessageParams): TypedDataDefinition

interface AuthMessageParams {
  chainId: number
  escrowContract: Hex
  channelId: Hex
  cumulativeAmount: string | bigint
  nonce: string | bigint
  deadline: string | bigint
  domainName?: string
  domainVersion?: string
}

/** 256-bit 密码学安全随机数，十进制字符串。 */
function randomU256(): string

/** unix 秒，十进制字符串；默认当前时间 + 1 小时。 */
function unixDeadline(secondsFromNow?: number): string

new SaApiClient({
  apiKey: string
  secretKey: string
  passphrase: string
  baseUrl?: string                // 默认 "https://web3.okx.com"
  onError?: (info: SaApiErrorInfo) => void
})

interface SaApiErrorInfo {
  method: 'GET' | 'POST'
  path: string
  requestBody?: string
  httpStatus: number
  code?: number                   // SA 业务错误码；解析失败为 undefined
  msg?: string
  responseBody?: string
}

import { Errors } from '@okxweb3/mpp'

import { SA_ERROR_CODES, type SaErrorCode } from '@okxweb3/mpp/evm'

SA_ERROR_CODES[70004]   // "invalid_signature"