moltspay 2.0.0 → 2.4.0

package/dist/server/index.mjs

@@ -1,7 +1,8 @@
 // src/server/index.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { createServer } from "http";
-import * as path2 from "path";
+import * as path3 from "path";
+import crypto6 from "crypto";
 
 // src/facilitators/interface.ts
 var BaseFacilitator = class {
@@ -398,10 +399,28 @@ var CHAINS = {
     requiresApproval: true
   }
 };
+function getChain(name) {
+  const config = CHAINS[name];
+  if (!config) {
+    throw new Error(`Unsupported chain: ${name}. Supported: ${Object.keys(CHAINS).join(", ")}`);
+  }
+  return config;
+}
+function getChainById(chainId) {
+  return Object.values(CHAINS).find((c) => c.chainId === chainId);
+}
 var ALIPAY_CHAIN_ID = "alipay";
 function isAlipayChainId(id) {
   return id === ALIPAY_CHAIN_ID;
 }
+var WECHAT_CHAIN_ID = "wechat";
+function isWechatChainId(id) {
+  return id === WECHAT_CHAIN_ID;
+}
+var BALANCE_CHAIN_ID = "balance";
+function isBalanceChainId(id) {
+  return id === BALANCE_CHAIN_ID;
+}
 
 // src/facilitators/tempo.ts
 var TRANSFER_EVENT_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
@@ -860,12 +879,12 @@ var BNBFacilitator = class extends BaseFacilitator {
     return this.spenderAddress;
   }
   async getServerAddress() {
-    const { ethers: ethers2 } = await import("ethers");
-    const wallet = new ethers2.Wallet(this.serverPrivateKey);
+    const { ethers: ethers4 } = await import("ethers");
+    const wallet = new ethers4.Wallet(this.serverPrivateKey);
     return wallet.address;
   }
   async recoverIntentSigner(intent, chainId) {
-    const { ethers: ethers2 } = await import("ethers");
+    const { ethers: ethers4 } = await import("ethers");
     const domain = {
       ...EIP712_DOMAIN,
       chainId
@@ -879,7 +898,7 @@ var BNBFacilitator = class extends BaseFacilitator {
       nonce: intent.nonce,
       deadline: intent.deadline
     };
-    const recoveredAddress = ethers2.verifyTypedData(
+    const recoveredAddress = ethers4.verifyTypedData(
       domain,
       INTENT_TYPES,
       message,
@@ -923,10 +942,10 @@ var BNBFacilitator = class extends BaseFacilitator {
     return result.result || "0x0";
   }
   async executeTransferFrom(from, to, amount, token, rpcUrl) {
-    const { ethers: ethers2 } = await import("ethers");
-    const provider = new ethers2.JsonRpcProvider(rpcUrl);
-    const wallet = new ethers2.Wallet(this.serverPrivateKey, provider);
-    const tokenContract = new ethers2.Contract(token, [
+    const { ethers: ethers4 } = await import("ethers");
+    const provider = new ethers4.JsonRpcProvider(rpcUrl);
+    const wallet = new ethers4.Wallet(this.serverPrivateKey, provider);
+    const tokenContract = new ethers4.Contract(token, [
       "function transferFrom(address from, address to, uint256 amount) returns (bool)"
     ], wallet);
     const tx = await tokenContract.transferFrom(from, to, amount);
@@ -1262,7 +1281,7 @@ var ALIPAY_SIGNING_FIELDS = [
 ];
 var AlipayFacilitator = class extends BaseFacilitator {
   name = "alipay";
-  displayName = "Alipay AI \u6536";
+  displayName = "Alipay AI Pay";
   supportedNetworks = [ALIPAY_NETWORK];
   config;
   constructor(config) {
@@ -1281,7 +1300,7 @@ var AlipayFacilitator = class extends BaseFacilitator {
   async createPaymentRequirements(opts) {
     if (!ALIPAY_AMOUNT_REGEX.test(opts.priceCny)) {
       throw new Error(
-        `AlipayFacilitator.createPaymentRequirements: priceCny "${opts.priceCny}" does not match /^\\d+(\\.\\d{1,2})?$/ (unit is \u5143, not \u5206; e.g. "1.00" not "100")`
+        `AlipayFacilitator.createPaymentRequirements: priceCny "${opts.priceCny}" does not match /^\\d+(\\.\\d{1,2})?$/ (unit is yuan, not fen; e.g. "1.00" not "100")`
       );
     }
     const now = /* @__PURE__ */ new Date();
@@ -1394,7 +1413,7 @@ var AlipayFacilitator = class extends BaseFacilitator {
    * service resource has been returned to the buyer.
    *
    * Per the design (see ALIPAY-INTEGRATION-DESIGN.md §5.1, risk row
-   * "履约确认失败"), this is **fire-and-forget**: the caller (registry /
+   * (a fulfillment-confirm failure), this is **fire-and-forget**: the caller (registry /
    * server) is expected to log fulfillment failures but NOT roll back
    * the already-delivered resource.
    *
@@ -1531,210 +1550,1086 @@ function decodeProof(proofHeader) {
   return parsed;
 }
 
-// src/facilitators/registry.ts
-import { Keypair as Keypair2 } from "@solana/web3.js";
-import bs58 from "bs58";
-var FacilitatorRegistry = class {
-  factories = /* @__PURE__ */ new Map();
-  instances = /* @__PURE__ */ new Map();
-  selection;
-  roundRobinIndex = 0;
-  constructor(selection) {
-    this.registerFactory("cdp", (config) => new CDPFacilitator(config));
-    this.registerFactory("tempo", () => new TempoFacilitator());
-    this.registerFactory("bnb", (config) => new BNBFacilitator(config?.serverPrivateKey));
-    this.registerFactory("solana", (config) => {
-      let feePayerKeypair;
-      const feePayerKey = config?.feePayerPrivateKey || process.env.SOLANA_FEE_PAYER_KEY;
-      if (feePayerKey) {
-        try {
-          feePayerKeypair = Keypair2.fromSecretKey(bs58.decode(feePayerKey));
-        } catch (e) {
-          console.warn(`[SolanaFacilitator] Invalid fee payer key: ${e.message}`);
-        }
-      }
-      return new SolanaFacilitator({ feePayerKeypair });
-    });
-    this.registerFactory("alipay", (config) => new AlipayFacilitator(config));
-    this.selection = selection || { primary: "cdp", fallback: ["tempo", "bnb", "solana"], strategy: "failover" };
+// src/facilitators/wechat.ts
+import crypto4 from "crypto";
+
+// src/facilitators/wechat/sign.ts
+import crypto3 from "crypto";
+var WECHAT_AUTH_SCHEMA = "WECHATPAY2-SHA256-RSA2048";
+function buildRequestMessage(method, urlPath, timestamp, nonce, body) {
+  return `${method.toUpperCase()}
+${urlPath}
+${timestamp}
+${nonce}
+${body}
+`;
+}
+function wechatV3Sign(method, urlPath, timestamp, nonce, body, privateKeyPem) {
+  const message = buildRequestMessage(method, urlPath, timestamp, nonce, body);
+  const signer = crypto3.createSign("RSA-SHA256");
+  signer.update(message, "utf-8");
+  signer.end();
+  return signer.sign(privateKeyPem, "base64");
+}
+function buildAuthorizationToken(args) {
+  const fields = [
+    `mchid="${args.mchid}"`,
+    `nonce_str="${args.nonce}"`,
+    `signature="${args.signature}"`,
+    `timestamp="${args.timestamp}"`,
+    `serial_no="${args.serialNo}"`
+  ].join(",");
+  return `${WECHAT_AUTH_SCHEMA} ${fields}`;
+}
+function wechatV3VerifyResponse(timestamp, nonce, body, signature, platformPublicKeyPem) {
+  try {
+    const message = `${timestamp}
+${nonce}
+${body}
+`;
+    const verifier = crypto3.createVerify("RSA-SHA256");
+    verifier.update(message, "utf-8");
+    verifier.end();
+    return verifier.verify(platformPublicKeyPem, signature, "base64");
+  } catch {
+    return false;
   }
-  /**
-   * Register a new facilitator factory
-   */
-  registerFactory(name, factory) {
-    this.factories.set(name, factory);
+}
+function generateNonce() {
+  return crypto3.randomBytes(16).toString("hex");
+}
+
+// src/facilitators/wechat/api.ts
+var WECHAT_API_BASE = "https://api.mch.weixin.qq.com";
+var WechatApiError = class extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "WechatApiError";
+    this.status = status;
+    this.code = code;
   }
-  /**
-   * Get or create a facilitator instance
-   */
-  get(name, config) {
-    if (this.instances.has(name)) {
-      return this.instances.get(name);
+};
+async function wechatV3Call(method, urlPath, body, config) {
+  const base = config.api_base ?? WECHAT_API_BASE;
+  const bodyStr = body === null ? "" : JSON.stringify(body);
+  const timestamp = String(Math.floor(Date.now() / 1e3));
+  const nonce = generateNonce();
+  const signature = wechatV3Sign(
+    method,
+    urlPath,
+    timestamp,
+    nonce,
+    bodyStr,
+    config.private_key_pem
+  );
+  const authorization = buildAuthorizationToken({
+    mchid: config.mchid,
+    serialNo: config.serial_no,
+    nonce,
+    timestamp,
+    signature
+  });
+  const response = await fetch(`${base}${urlPath}`, {
+    method,
+    headers: {
+      Authorization: authorization,
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      // WeChat requires a non-empty UA; some edge nodes 403 a blank one.
+      "User-Agent": "moltspay-wechat/1.0"
+    },
+    body: method === "GET" ? void 0 : bodyStr
+  });
+  const text = await response.text();
+  if (config.platform_public_key_pem && text.length > 0) {
+    const ts = response.headers.get("Wechatpay-Timestamp");
+    const nc = response.headers.get("Wechatpay-Nonce");
+    const sig = response.headers.get("Wechatpay-Signature");
+    if (!ts || !nc || !sig) {
+      throw new Error(
+        `WeChat v3 ${method} ${urlPath}: response missing Wechatpay-Signature headers`
+      );
     }
-    const factory = this.factories.get(name);
-    if (!factory) {
-      throw new Error(`Unknown facilitator: ${name}. Available: ${Array.from(this.factories.keys()).join(", ")}`);
+    if (!wechatV3VerifyResponse(ts, nc, text, sig, config.platform_public_key_pem)) {
+      throw new Error(
+        `WeChat v3 ${method} ${urlPath}: response signature verification failed`
+      );
     }
-    const mergedConfig = {
-      ...this.selection.config?.[name],
-      ...config
-    };
-    const instance = factory(mergedConfig);
-    this.instances.set(name, instance);
-    return instance;
   }
-  /**
-   * Get all configured facilitator names
-   */
-  getConfiguredNames() {
-    const names = [this.selection.primary];
-    if (this.selection.fallback) {
-      names.push(...this.selection.fallback);
+  let json = {};
+  if (text.length > 0) {
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(
+        `WeChat v3 ${method} ${urlPath}: non-JSON response (HTTP ${response.status}): ${text.slice(0, 300)}`
+      );
     }
-    return names;
+  }
+  if (!response.ok) {
+    const code = typeof json.code === "string" ? json.code : void 0;
+    const message = typeof json.message === "string" ? json.message : text.slice(0, 300);
+    throw new WechatApiError(
+      `WeChat v3 ${method} ${urlPath} failed: HTTP ${response.status}${code ? ` ${code}` : ""}: ${message}`,
+      response.status,
+      code
+    );
+  }
+  return { status: response.status, body: json };
+}
+
+// src/facilitators/wechat.ts
+var WECHAT_NETWORK = "wechat";
+var WECHAT_SCHEME = "wechatpay-native";
+var WECHAT_AMOUNT_REGEX = /^\d+(\.\d{1,2})?$/;
+var WECHAT_TIME_EXPIRE_MS = 5 * 60 * 1e3;
+var WechatFacilitator = class extends BaseFacilitator {
+  name = "wechat";
+  displayName = "WeChat Pay";
+  supportedNetworks = [WECHAT_NETWORK];
+  config;
+  constructor(config) {
+    super();
+    this.config = { api_base: WECHAT_API_BASE, ...config };
   }
   /**
-   * Get list of facilitators based on selection strategy
+   * Place a Native order and build the 402 challenge. The returned
+   * `code_url` is payer-agnostic — any WeChat user may scan it.
    */
-  async getOrderedFacilitators(network) {
-    const names = this.getConfiguredNames();
-    const facilitators = [];
-    for (const name of names) {
-      try {
-        const f = this.get(name);
-        if (f.supportsNetwork(network)) {
-          facilitators.push(f);
-        }
-      } catch (err) {
-        console.warn(`[Registry] Failed to get facilitator ${name}:`, err);
-      }
-    }
-    if (facilitators.length === 0) {
-      throw new Error(`No facilitators available for network: ${network}`);
+  async createPaymentRequirements(opts) {
+    if (!WECHAT_AMOUNT_REGEX.test(opts.priceCny)) {
+      throw new Error(
+        `WechatFacilitator.createPaymentRequirements: priceCny "${opts.priceCny}" does not match /^\\d+(\\.\\d{1,2})?$/ (unit is yuan; e.g. "10.00")`
+      );
     }
-    switch (this.selection.strategy) {
-      case "random":
-        return this.shuffle(facilitators);
-      case "roundrobin":
-        this.roundRobinIndex = (this.roundRobinIndex + 1) % facilitators.length;
-        return [
-          ...facilitators.slice(this.roundRobinIndex),
-          ...facilitators.slice(0, this.roundRobinIndex)
-        ];
-      case "cheapest":
-        return this.sortByCheapest(facilitators);
-      case "fastest":
-        return this.sortByFastest(facilitators);
-      case "failover":
-      default:
-        return facilitators;
+    const total = cnyToFen(opts.priceCny);
+    if (total < 1) {
+      throw new Error(
+        `WechatFacilitator.createPaymentRequirements: amount ${total} fen is below the 1 fen minimum`
+      );
     }
-  }
-  shuffle(array) {
-    const result = [...array];
-    for (let i = result.length - 1; i > 0; i--) {
-      const j = Math.floor(Math.random() * (i + 1));
-      [result[i], result[j]] = [result[j], result[i]];
+    const outTradeNo = opts.outTradeNo ?? generateOutTradeNo2();
+    const expiresInMs = opts.expiresInMs ?? WECHAT_TIME_EXPIRE_MS;
+    const body = {
+      appid: this.config.appid,
+      mchid: this.config.mchid,
+      description: opts.description,
+      out_trade_no: outTradeNo,
+      notify_url: this.config.notify_url,
+      time_expire: formatTimeExpire(new Date(Date.now() + expiresInMs)),
+      amount: { total, currency: "CNY" }
+    };
+    if (opts.attach) {
+      const attachStr = JSON.stringify(opts.attach);
+      if (Buffer.byteLength(attachStr, "utf8") > 128) {
+        throw new Error(
+          `WechatFacilitator.createPaymentRequirements: attach exceeds WeChat's 128-byte limit (${Buffer.byteLength(attachStr, "utf8")} bytes)`
+        );
+      }
+      body.attach = attachStr;
     }
-    return result;
-  }
-  async sortByCheapest(facilitators) {
-    const withFees = await Promise.all(
-      facilitators.map(async (f) => {
-        try {
-          const fee = await f.getFee?.();
-          return { facilitator: f, perTx: fee?.perTx ?? Infinity };
-        } catch {
-          return { facilitator: f, perTx: Infinity };
-        }
-      })
-    );
-    withFees.sort((a, b) => a.perTx - b.perTx);
-    return withFees.map((w) => w.facilitator);
-  }
-  async sortByFastest(facilitators) {
-    const withLatency = await Promise.all(
-      facilitators.map(async (f) => {
-        try {
-          const health = await f.healthCheck();
-          return { facilitator: f, latency: health.latencyMs ?? Infinity };
-        } catch {
-          return { facilitator: f, latency: Infinity };
-        }
-      })
+    const { body: resp } = await wechatV3Call(
+      "POST",
+      "/v3/pay/transactions/native",
+      body,
+      this.getApiConfig()
     );
-    withLatency.sort((a, b) => a.latency - b.latency);
-    return withLatency.map((w) => w.facilitator);
+    const codeUrl = resp.code_url;
+    if (typeof codeUrl !== "string" || codeUrl.length === 0) {
+      throw new Error(
+        `WeChat Native order returned no code_url: ${JSON.stringify(resp).slice(0, 300)}`
+      );
+    }
+    const x402Accepts = {
+      scheme: WECHAT_SCHEME,
+      network: WECHAT_NETWORK,
+      asset: "CNY",
+      amount: opts.priceCny,
+      payTo: this.config.mchid,
+      maxTimeoutSeconds: Math.floor(expiresInMs / 1e3),
+      extra: {
+        code_url: codeUrl,
+        out_trade_no: outTradeNo
+      }
+    };
+    return { x402Accepts, codeUrl, outTradeNo };
   }
   /**
-   * Verify payment using configured facilitators
+   * Poll an order: `trade_state === 'SUCCESS'` ⇒ paid. All failure modes
+   * (missing out_trade_no, gateway error, not-yet-paid) return
+   * `{ valid: false, error }`; no exception escapes.
    */
   async verify(paymentPayload, requirements) {
-    const network = paymentPayload.accepted?.network || paymentPayload.network || requirements.network;
-    const facilitators = await this.getOrderedFacilitators(network);
-    let lastError;
-    for (const f of facilitators) {
-      try {
-        console.log(`[Registry] Trying ${f.name} for verify...`);
-        const result = await f.verify(paymentPayload, requirements);
-        if (result.valid) {
-          console.log(`[Registry] ${f.name} verify succeeded`);
-          return { ...result, facilitator: f.name };
-        }
-        lastError = result.error;
-        console.log(`[Registry] ${f.name} verify failed: ${result.error}`);
-        if (this.selection.strategy === "failover" && !this.isTransientError(result.error)) {
-          break;
-        }
-      } catch (err) {
-        lastError = err.message;
-        console.error(`[Registry] ${f.name} error:`, err.message);
+    try {
+      const outTradeNo = extractOutTradeNo(paymentPayload, requirements);
+      const resp = await this.queryOrder(outTradeNo);
+      const tradeState = resp.trade_state;
+      if (tradeState !== "SUCCESS") {
+        return {
+          valid: false,
+          error: `wechat trade_state ${tradeState ?? "UNKNOWN"}`,
+          details: { trade_state: tradeState, out_trade_no: outTradeNo }
+        };
       }
+      return {
+        valid: true,
+        details: {
+          trade_state: tradeState,
+          transaction_id: resp.transaction_id,
+          out_trade_no: resp.out_trade_no ?? outTradeNo,
+          amount: resp.amount,
+          attach: resp.attach,
+          // Payer identity, gateway-attested. Present on a SUCCESS Native
+          // order even though order creation was payer-agnostic; anchors the
+          // custodial balance to a real WeChat user. @see WECHAT fiat auth design.
+          openid: resp.payer?.openid
+        }
+      };
+    } catch (e) {
+      return { valid: false, error: e instanceof Error ? e.message : String(e) };
     }
-    return {
-      valid: false,
-      error: lastError || "All facilitators failed",
-      facilitator: "none"
-    };
   }
   /**
-   * Settle payment using configured facilitators
+   * Confirm settlement. Native captures funds at SUCCESS, so this is an
+   * idempotent re-confirm that returns the `transaction_id`. Like Alipay's
+   * fulfillment confirm, failures are surfaced but non-fatal to an
+   * already-delivered resource (caller logs, does not roll back).
    */
   async settle(paymentPayload, requirements) {
-    const network = paymentPayload.accepted?.network || paymentPayload.network || requirements.network;
-    const facilitators = await this.getOrderedFacilitators(network);
-    let lastError;
-    for (const f of facilitators) {
-      try {
-        console.log(`[Registry] Trying ${f.name} for settle...`);
-        const result = await f.settle(paymentPayload, requirements);
-        if (result.success) {
-          console.log(`[Registry] ${f.name} settle succeeded: ${result.transaction}`);
-          return { ...result, facilitator: f.name };
-        }
-        lastError = result.error;
-        console.log(`[Registry] ${f.name} settle failed: ${result.error}`);
-      } catch (err) {
-        lastError = err.message;
-        console.error(`[Registry] ${f.name} error:`, err.message);
+    try {
+      const outTradeNo = extractOutTradeNo(paymentPayload, requirements);
+      const resp = await this.queryOrder(outTradeNo);
+      const tradeState = resp.trade_state;
+      const transactionId = resp.transaction_id;
+      if (tradeState !== "SUCCESS") {
+        return {
+          success: false,
+          transaction: transactionId,
+          error: `wechat trade_state ${tradeState ?? "UNKNOWN"} (expected SUCCESS)`,
+          status: tradeState
+        };
       }
+      return { success: true, transaction: transactionId, status: "fulfilled" };
+    } catch (e) {
+      return { success: false, error: e instanceof Error ? e.message : String(e) };
     }
-    return {
-      success: false,
-      error: lastError || "All facilitators failed",
-      facilitator: "none"
-    };
   }
   /**
-   * Check health of all configured facilitators
+   * Validate keys parse, apiv3 key length, and gateway reachability. Does
+   * NOT make a business API call.
    */
-  async healthCheckAll() {
-    const results = {};
-    for (const name of this.getConfiguredNames()) {
-      try {
-        const f = this.get(name);
-        results[name] = await f.healthCheck();
-      } catch (err) {
+  async healthCheck() {
+    const start = Date.now();
+    try {
+      crypto4.createPrivateKey(this.config.private_key_pem);
+    } catch (e) {
+      return {
+        healthy: false,
+        error: `merchant private_key_pem parse failed: ${e instanceof Error ? e.message : String(e)}`
+      };
+    }
+    if (this.config.platform_public_key_pem) {
+      try {
+        crypto4.createPublicKey(this.config.platform_public_key_pem);
+      } catch (e) {
+        return {
+          healthy: false,
+          error: `platform_public_key_pem parse failed: ${e instanceof Error ? e.message : String(e)}`
+        };
+      }
+    }
+    if (this.config.apiv3_key !== void 0 && Buffer.byteLength(this.config.apiv3_key, "utf-8") !== 32) {
+      return { healthy: false, error: "apiv3_key must be exactly 32 bytes" };
+    }
+    const base = this.config.api_base ?? WECHAT_API_BASE;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5e3);
+    const response = await fetch(base, { method: "HEAD", signal: controller.signal }).catch(() => null);
+    clearTimeout(timeout);
+    const latencyMs = Date.now() - start;
+    if (!response) {
+      return { healthy: false, error: `gateway unreachable: ${base}`, latencyMs };
+    }
+    return { healthy: true, latencyMs };
+  }
+  /** Query a Native order by out_trade_no. The query string is part of the signed path. */
+  async queryOrder(outTradeNo) {
+    const path4 = `/v3/pay/transactions/out-trade-no/${encodeURIComponent(outTradeNo)}?mchid=${encodeURIComponent(this.config.mchid)}`;
+    const { body } = await wechatV3Call("GET", path4, null, this.getApiConfig());
+    return body;
+  }
+  /** Project the facilitator config down to what api.ts needs. */
+  getApiConfig() {
+    return {
+      mchid: this.config.mchid,
+      serial_no: this.config.serial_no,
+      private_key_pem: this.config.private_key_pem,
+      platform_public_key_pem: this.config.platform_public_key_pem,
+      api_base: this.config.api_base
+    };
+  }
+};
+function cnyToFen(cny) {
+  return Math.round(parseFloat(cny) * 100);
+}
+function generateOutTradeNo2() {
+  return "WX" + crypto4.randomBytes(15).toString("hex");
+}
+function parseWechatAttach(attach) {
+  if (typeof attach !== "string" || attach.length === 0) return null;
+  try {
+    const parsed = JSON.parse(attach);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function formatTimeExpire(d) {
+  const pad = (n) => String(n).padStart(2, "0");
+  const offMin = -d.getTimezoneOffset();
+  const sign = offMin >= 0 ? "+" : "-";
+  const abs = Math.abs(offMin);
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+}
+function extractOutTradeNo(paymentPayload, requirements) {
+  const p = paymentPayload?.payload;
+  if (typeof p === "string" && p.length > 0) return p;
+  if (p !== null && typeof p === "object") {
+    const obj = p;
+    const cand = obj.out_trade_no ?? obj.outTradeNo;
+    if (typeof cand === "string" && cand.length > 0) return cand;
+  }
+  const fromReq = requirements?.extra?.out_trade_no;
+  if (typeof fromReq === "string" && fromReq.length > 0) return fromReq;
+  throw new Error(
+    "wechat payment payload must carry out_trade_no (string, {out_trade_no}/{outTradeNo}, or requirements.extra.out_trade_no)"
+  );
+}
+
+// src/facilitators/balance/ledger.ts
+import { randomUUID } from "crypto";
+var DEFAULT_SINGLE_LIMIT_SAT = 500;
+var DEFAULT_DAILY_LIMIT_SAT = 1e3;
+function toSat(amount) {
+  const s = typeof amount === "number" ? amount.toFixed(2) : amount.trim();
+  if (!/^\d+(\.\d{1,2})?$/.test(s)) {
+    throw new Error(`Invalid amount "${amount}": expected a non-negative decimal with <= 2 places`);
+  }
+  const [whole, frac = ""] = s.split(".");
+  return parseInt(whole, 10) * 100 + parseInt(frac.padEnd(2, "0") || "0", 10);
+}
+function fromSat(sat) {
+  return (sat / 100).toFixed(2);
+}
+var BalanceLedger = class {
+  db;
+  defaultSingleLimitSat;
+  defaultDailyLimitSat;
+  constructor(config) {
+    const getBuiltin = process.getBuiltinModule;
+    const sqlite = getBuiltin?.("node:sqlite");
+    if (!sqlite?.DatabaseSync) {
+      throw new Error(
+        `The balance rail requires the node:sqlite module (Node.js >= 22.5). Current version: ${process.version}. Upgrade Node or disable provider.balance.`
+      );
+    }
+    const { DatabaseSync } = sqlite;
+    this.db = new DatabaseSync(config.dbPath);
+    this.defaultSingleLimitSat = config.defaultSingleLimitSat ?? DEFAULT_SINGLE_LIMIT_SAT;
+    this.defaultDailyLimitSat = config.defaultDailyLimitSat ?? DEFAULT_DAILY_LIMIT_SAT;
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS buyers (
+        buyer_id TEXT PRIMARY KEY,
+        display_name TEXT,
+        balance_sat INTEGER NOT NULL DEFAULT 0,
+        total_topup_sat INTEGER NOT NULL DEFAULT 0,
+        total_spent_sat INTEGER NOT NULL DEFAULT 0,
+        daily_limit_sat INTEGER NOT NULL,
+        single_limit_sat INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE TABLE IF NOT EXISTS ledger_transactions (
+        id TEXT PRIMARY KEY,
+        buyer_id TEXT NOT NULL REFERENCES buyers(buyer_id),
+        type TEXT NOT NULL,
+        amount_sat INTEGER NOT NULL,
+        service TEXT,
+        description TEXT,
+        request_id TEXT,
+        external_ref TEXT,
+        refunds_tx_id TEXT,
+        status TEXT NOT NULL DEFAULT 'completed',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_ledger_request_id
+        ON ledger_transactions(request_id) WHERE request_id IS NOT NULL;
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_ledger_external_ref
+        ON ledger_transactions(external_ref) WHERE external_ref IS NOT NULL;
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_ledger_refunds_tx
+        ON ledger_transactions(refunds_tx_id) WHERE refunds_tx_id IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_ledger_buyer_time
+        ON ledger_transactions(buyer_id, created_at);
+      CREATE TABLE IF NOT EXISTS ledger_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+    const cols = this.db.prepare("PRAGMA table_info(buyers)").all().map((c) => c.name);
+    if (!cols.includes("signer_address")) {
+      this.db.exec("ALTER TABLE buyers ADD COLUMN signer_address TEXT");
+    }
+    if (!cols.includes("wechat_openid")) {
+      this.db.exec("ALTER TABLE buyers ADD COLUMN wechat_openid TEXT");
+    }
+    const currency = config.currency ?? "USD";
+    const existingCurrency = this.db.prepare(`SELECT value FROM ledger_meta WHERE key = 'currency'`).get();
+    if (existingCurrency) {
+      if (existingCurrency.value !== currency) {
+        throw new Error(
+          `Balance ledger currency mismatch: db=${existingCurrency.value} config=${currency}. Use a separate db_path for a different currency; do not reinterpret an existing ledger.`
+        );
+      }
+    } else {
+      this.db.prepare(`INSERT INTO ledger_meta (key, value) VALUES ('currency', ?)`).run(currency);
+    }
+  }
+  /** Fetch a buyer, or null. */
+  getBuyer(buyerId) {
+    const row = this.db.prepare("SELECT * FROM buyers WHERE buyer_id = ?").get(buyerId);
+    return row ?? null;
+  }
+  /** Fetch a buyer, creating an empty active account on first sight. */
+  getOrCreateBuyer(buyerId, displayName) {
+    const existing = this.getBuyer(buyerId);
+    if (existing) return existing;
+    this.db.prepare(
+      `INSERT INTO buyers (buyer_id, display_name, daily_limit_sat, single_limit_sat)
+         VALUES (?, ?, ?, ?)`
+    ).run(buyerId, displayName ?? null, this.defaultDailyLimitSat, this.defaultSingleLimitSat);
+    return this.getBuyer(buyerId);
+  }
+  /**
+   * Record the gateway-attested WeChat payer openid that funded a buyer, on
+   * top-up confirm. Idempotent and observational (stage 1a): it never
+   * overwrites an existing binding with a *different* openid — a conflict is
+   * reported to the caller (possible account sharing / spoof) but not
+   * enforced here. Creates the buyer if absent.
+   */
+  bindOpenid(buyerId, openid) {
+    const buyer = this.getOrCreateBuyer(buyerId);
+    if (buyer.wechat_openid === openid) {
+      return { bound: true, conflict: false, existing: openid };
+    }
+    if (buyer.wechat_openid && buyer.wechat_openid !== openid) {
+      return { bound: false, conflict: true, existing: buyer.wechat_openid };
+    }
+    this.db.prepare(`UPDATE buyers SET wechat_openid = ?, updated_at = datetime('now') WHERE buyer_id = ?`).run(openid, buyerId);
+    return { bound: true, conflict: false, existing: null };
+  }
+  /**
+   * TOFU-bind the account's spending signer address (EVM, lowercase). First
+   * signed request records it; later requests must match. A mismatch is
+   * reported (`conflict`) so the caller can reject under `enforce` — it is
+   * never silently overwritten. Creates the buyer if absent.
+   */
+  bindSigner(buyerId, address) {
+    const a = address.toLowerCase();
+    const buyer = this.getOrCreateBuyer(buyerId);
+    if (buyer.signer_address === a) return { bound: true, conflict: false, existing: a };
+    if (buyer.signer_address && buyer.signer_address !== a) {
+      return { bound: false, conflict: true, existing: buyer.signer_address };
+    }
+    this.db.prepare(`UPDATE buyers SET signer_address = ?, updated_at = datetime('now') WHERE buyer_id = ?`).run(a, buyerId);
+    return { bound: true, conflict: false, existing: null };
+  }
+  /** Sum of today's (UTC) completed deducts minus refunds issued against them. */
+  spentTodaySat(buyerId) {
+    const row = this.db.prepare(
+      `SELECT COALESCE(SUM(CASE type WHEN 'deduct' THEN amount_sat ELSE -amount_sat END), 0) AS spent
+         FROM ledger_transactions
+         WHERE buyer_id = ? AND type IN ('deduct','refund') AND date(created_at) = date('now')`
+    ).get(buyerId);
+    return Math.max(0, row.spent);
+  }
+  /**
+   * Read-only deduction precheck (the rail's `verify`). Never mutates.
+   * Returns the same error codes `deduct` would.
+   */
+  checkDeduct(buyerId, amountSat) {
+    const buyer = this.getBuyer(buyerId);
+    if (!buyer) return { success: false, error: "buyer_not_found" };
+    if (buyer.status !== "active") return { success: false, error: "buyer_not_active" };
+    if (amountSat > buyer.single_limit_sat) {
+      return { success: false, error: "exceeds_single_limit", limitSat: buyer.single_limit_sat };
+    }
+    const spent = this.spentTodaySat(buyerId);
+    if (spent + amountSat > buyer.daily_limit_sat) {
+      return { success: false, error: "exceeds_daily_limit", limitSat: buyer.daily_limit_sat };
+    }
+    if (buyer.balance_sat < amountSat) {
+      return { success: false, error: "insufficient_balance", balanceSat: buyer.balance_sat };
+    }
+    return { success: true, balanceSat: buyer.balance_sat };
+  }
+  /**
+   * Atomic deduction (the rail's `settle`). Check + UPDATE run inside one
+   * SQLite transaction; a `request_id` replay returns the original tx
+   * without charging again.
+   */
+  deduct(opts) {
+    if (!Number.isInteger(opts.amountSat) || opts.amountSat <= 0) {
+      throw new Error(`deduct amountSat must be a positive integer, got ${opts.amountSat}`);
+    }
+    if (opts.requestId) {
+      const prior = this.db.prepare(`SELECT * FROM ledger_transactions WHERE request_id = ?`).get(opts.requestId);
+      if (prior) {
+        const buyer = this.getBuyer(prior.buyer_id);
+        return { success: true, txId: prior.id, replayed: true, balanceSat: buyer.balance_sat };
+      }
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const check = this.checkDeduct(opts.buyerId, opts.amountSat);
+      if (!check.success) {
+        this.db.exec("ROLLBACK");
+        return check;
+      }
+      const updated = this.db.prepare(
+        `UPDATE buyers SET
+             balance_sat = balance_sat - ?,
+             total_spent_sat = total_spent_sat + ?,
+             updated_at = datetime('now')
+           WHERE buyer_id = ? AND balance_sat >= ? AND status = 'active'`
+      ).run(opts.amountSat, opts.amountSat, opts.buyerId, opts.amountSat);
+      if (Number(updated.changes) !== 1) {
+        this.db.exec("ROLLBACK");
+        return { success: false, error: "insufficient_balance" };
+      }
+      const txId = `btx_${randomUUID()}`;
+      this.db.prepare(
+        `INSERT INTO ledger_transactions (id, buyer_id, type, amount_sat, service, description, request_id)
+           VALUES (?, ?, 'deduct', ?, ?, ?, ?)`
+      ).run(txId, opts.buyerId, opts.amountSat, opts.service ?? null, opts.description ?? null, opts.requestId ?? null);
+      this.db.exec("COMMIT");
+      const buyer = this.getBuyer(opts.buyerId);
+      return { success: true, txId, balanceSat: buyer.balance_sat };
+    } catch (err) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+  }
+  /**
+   * Credit a top-up. `externalRef` is the settlement proof reference
+   * (on-chain tx hash / fiat trade number) and is unique: replaying the same
+   * reference returns the original row without crediting twice.
+   */
+  topup(opts) {
+    if (!Number.isInteger(opts.amountSat) || opts.amountSat <= 0) {
+      throw new Error(`topup amountSat must be a positive integer, got ${opts.amountSat}`);
+    }
+    const prior = this.db.prepare(`SELECT * FROM ledger_transactions WHERE external_ref = ?`).get(opts.externalRef);
+    if (prior) {
+      const buyer2 = this.getBuyer(prior.buyer_id);
+      return { txId: prior.id, balanceSat: buyer2.balance_sat, replayed: true };
+    }
+    this.getOrCreateBuyer(opts.buyerId);
+    const txId = `btx_${randomUUID()}`;
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db.prepare(
+        `UPDATE buyers SET
+             balance_sat = balance_sat + ?,
+             total_topup_sat = total_topup_sat + ?,
+             updated_at = datetime('now')
+           WHERE buyer_id = ?`
+      ).run(opts.amountSat, opts.amountSat, opts.buyerId);
+      this.db.prepare(
+        `INSERT INTO ledger_transactions (id, buyer_id, type, amount_sat, description, external_ref)
+           VALUES (?, ?, 'topup', ?, ?, ?)`
+      ).run(txId, opts.buyerId, opts.amountSat, opts.description ?? null, opts.externalRef);
+      this.db.exec("COMMIT");
+    } catch (err) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+    const buyer = this.getBuyer(opts.buyerId);
+    return { txId, balanceSat: buyer.balance_sat };
+  }
+  /**
+   * Reverse a deduct (service failed after the charge). Idempotent: the
+   * unique index on `refunds_tx_id` means a second refund of the same deduct
+   * returns the original refund row.
+   */
+  refund(deductTxId, reason) {
+    const deductRow = this.db.prepare(`SELECT * FROM ledger_transactions WHERE id = ?`).get(deductTxId);
+    if (!deductRow) return { success: false, error: "tx_not_found" };
+    if (deductRow.type !== "deduct") return { success: false, error: "not_a_deduct" };
+    const priorRefund = this.db.prepare(`SELECT * FROM ledger_transactions WHERE refunds_tx_id = ?`).get(deductTxId);
+    if (priorRefund) {
+      const buyer = this.getBuyer(deductRow.buyer_id);
+      return { success: true, txId: priorRefund.id, balanceSat: buyer.balance_sat, replayed: true };
+    }
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db.prepare(
+        `UPDATE buyers SET
+             balance_sat = balance_sat + ?,
+             total_spent_sat = total_spent_sat - ?,
+             updated_at = datetime('now')
+           WHERE buyer_id = ?`
+      ).run(deductRow.amount_sat, deductRow.amount_sat, deductRow.buyer_id);
+      this.db.prepare(`UPDATE ledger_transactions SET status = 'refunded' WHERE id = ?`).run(deductTxId);
+      const txId = `btx_${randomUUID()}`;
+      this.db.prepare(
+        `INSERT INTO ledger_transactions (id, buyer_id, type, amount_sat, description, refunds_tx_id)
+           VALUES (?, ?, 'refund', ?, ?, ?)`
+      ).run(txId, deductRow.buyer_id, deductRow.amount_sat, reason ?? null, deductTxId);
+      this.db.exec("COMMIT");
+      const buyer = this.getBuyer(deductRow.buyer_id);
+      return { success: true, txId, balanceSat: buyer.balance_sat };
+    } catch (err) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {
+      }
+      throw err;
+    }
+  }
+  /** Paged transaction history, newest first (rowid breaks same-second ties). */
+  listTransactions(buyerId, limit = 20, offset = 0) {
+    return this.db.prepare(
+      `SELECT * FROM ledger_transactions WHERE buyer_id = ?
+         ORDER BY created_at DESC, rowid DESC LIMIT ? OFFSET ?`
+    ).all(buyerId, limit, offset);
+  }
+  /** Quick integrity probe for healthCheck(). */
+  integrityOk() {
+    const row = this.db.prepare(`PRAGMA quick_check`).get();
+    return row.quick_check === "ok";
+  }
+  close() {
+    this.db.close();
+  }
+};
+
+// src/facilitators/balance/auth.ts
+import { ethers as ethers2 } from "ethers";
+var BALANCE_AUTH_DOMAIN = "moltspay-balance-auth:v1";
+var BALANCE_AUTH_MAX_SKEW_MS = 5 * 60 * 1e3;
+function extractBalanceAuth(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const a = raw;
+  if (typeof a.signature === "string" && a.signature && typeof a.timestamp === "number" && Number.isFinite(a.timestamp)) {
+    return { timestamp: a.timestamp, signature: a.signature };
+  }
+  return null;
+}
+function buildDeductMessage(f) {
+  return [BALANCE_AUTH_DOMAIN, "balance-deduct", f.buyerId, f.requestId, f.service, String(f.timestamp)].join("\n");
+}
+function verifyDeductAuth(opts) {
+  const { auth } = opts;
+  if (!auth) return { ok: false, reason: "no_signature" };
+  if (!auth.signature || !Number.isFinite(auth.timestamp)) return { ok: false, reason: "malformed" };
+  if (Math.abs(opts.nowMs - auth.timestamp * 1e3) > BALANCE_AUTH_MAX_SKEW_MS) {
+    return { ok: false, reason: "timestamp_skew" };
+  }
+  const message = buildDeductMessage({
+    buyerId: opts.buyerId,
+    requestId: opts.requestId,
+    service: opts.service,
+    timestamp: auth.timestamp
+  });
+  try {
+    const recovered = ethers2.verifyMessage(message, auth.signature).toLowerCase();
+    return { ok: true, recovered };
+  } catch {
+    return { ok: false, reason: "bad_signature" };
+  }
+}
+
+// src/facilitators/balance.ts
+var BALANCE_NETWORK = "balance";
+var BALANCE_SCHEME = "balance";
+function extractBalancePayload(payment) {
+  const p = payment.payload;
+  if (p && typeof p.buyer_id === "string" && p.buyer_id.length > 0) {
+    return {
+      buyer_id: p.buyer_id,
+      request_id: typeof p.request_id === "string" ? p.request_id : void 0,
+      auth: extractBalanceAuth(p.auth) ?? void 0
+    };
+  }
+  return null;
+}
+var BalanceFacilitator = class extends BaseFacilitator {
+  name = "balance";
+  displayName = "Custodial Balance";
+  supportedNetworks = [BALANCE_NETWORK];
+  currency;
+  /** User-auth rollout gate for deductions (off | shadow | enforce). */
+  authMode;
+  ledger;
+  constructor(config) {
+    super();
+    this.currency = config.currency ?? "USD";
+    this.authMode = config.auth_mode ?? "off";
+    const ledgerConfig = {
+      dbPath: config.db_path,
+      defaultSingleLimitSat: config.single_limit ? toSat(config.single_limit) : DEFAULT_SINGLE_LIMIT_SAT,
+      defaultDailyLimitSat: config.daily_limit ? toSat(config.daily_limit) : DEFAULT_DAILY_LIMIT_SAT,
+      currency: this.currency
+    };
+    this.ledger = new BalanceLedger(ledgerConfig);
+  }
+  /** Direct ledger access for the server's balance-management endpoints. */
+  getLedger() {
+    return this.ledger;
+  }
+  /**
+   * Build the `accepts[]` entry for a service. Pure — no I/O, nothing minted.
+   */
+  createPaymentRequirements(opts) {
+    toSat(opts.price);
+    return {
+      scheme: BALANCE_SCHEME,
+      network: BALANCE_NETWORK,
+      asset: this.currency,
+      amount: opts.price,
+      payTo: "custodial",
+      maxTimeoutSeconds: 30,
+      extra: opts.serviceId ? { service_id: opts.serviceId } : void 0
+    };
+  }
+  /** Read-only funds/limits precheck. Never mutates the ledger. */
+  async verify(paymentPayload, requirements) {
+    const payload = extractBalancePayload(paymentPayload);
+    if (!payload) {
+      return { valid: false, error: "Missing buyer_id in balance payment payload" };
+    }
+    let amountSat;
+    try {
+      amountSat = toSat(requirements.amount);
+    } catch (err) {
+      return { valid: false, error: err.message };
+    }
+    const check = this.ledger.checkDeduct(payload.buyer_id, amountSat);
+    if (!check.success) {
+      return {
+        valid: false,
+        error: this.describeDeductError(check),
+        details: { code: check.error, balance: check.balanceSat !== void 0 ? fromSat(check.balanceSat) : void 0 }
+      };
+    }
+    return { valid: true, details: { balance: fromSat(check.balanceSat) } };
+  }
+  /**
+   * The atomic deduction. Idempotent on `request_id`; the returned
+   * `transaction` is the ledger tx id (usable for `refund`).
+   */
+  async settle(paymentPayload, requirements) {
+    const payload = extractBalancePayload(paymentPayload);
+    if (!payload) {
+      return { success: false, error: "Missing buyer_id in balance payment payload" };
+    }
+    let amountSat;
+    try {
+      amountSat = toSat(requirements.amount);
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+    const serviceId = typeof requirements.extra?.service_id === "string" ? requirements.extra.service_id : void 0;
+    let result;
+    try {
+      result = this.ledger.deduct({
+        buyerId: payload.buyer_id,
+        amountSat,
+        requestId: payload.request_id,
+        service: serviceId
+      });
+    } catch (err) {
+      return { success: false, error: `Ledger deduct failed: ${err.message}` };
+    }
+    if (!result.success) {
+      return { success: false, error: this.describeDeductError(result), status: result.error };
+    }
+    return {
+      success: true,
+      transaction: result.txId,
+      status: result.replayed ? "replayed" : "deducted"
+    };
+  }
+  /** Reverse a deduct after a downstream failure. Idempotent per deduct. */
+  refund(deductTxId, reason) {
+    return this.ledger.refund(deductTxId, reason);
+  }
+  /**
+   * Credit a gateway-verified external settlement to a buyer's balance. The
+   * single entry point for every funding path -- WeChat callback, WeChat
+   * polling, and the operator `/balance/topup` endpoint -- so they share one
+   * idempotency boundary: `externalRef` is unique in the ledger, so a replay
+   * credits nothing and returns the original transaction (`replayed: true`).
+   * Callers must pass a gateway-verified `amountSat`, never a client-declared
+   * amount.
+   */
+  credit(opts) {
+    const result = this.ledger.topup({
+      buyerId: opts.buyerId,
+      amountSat: opts.amountSat,
+      externalRef: opts.externalRef,
+      description: opts.description
+    });
+    return {
+      txId: result.txId,
+      balance: fromSat(result.balanceSat),
+      balanceSat: result.balanceSat,
+      replayed: result.replayed ?? false
+    };
+  }
+  async healthCheck() {
+    const start = Date.now();
+    try {
+      const ok = this.ledger.integrityOk();
+      return ok ? { healthy: true, latencyMs: Date.now() - start } : { healthy: false, error: "SQLite quick_check failed" };
+    } catch (err) {
+      return { healthy: false, error: err.message };
+    }
+  }
+  describeDeductError(result) {
+    switch (result.error) {
+      case "buyer_not_found":
+        return "Unknown buyer: top up first to create an account";
+      case "buyer_not_active":
+        return "Buyer account is frozen or banned";
+      case "insufficient_balance":
+        return `Insufficient balance${result.balanceSat !== void 0 ? ` (have ${fromSat(result.balanceSat)})` : ""}`;
+      case "exceeds_single_limit":
+        return `Amount exceeds the per-transaction limit${result.limitSat !== void 0 ? ` of ${fromSat(result.limitSat)}` : ""}`;
+      case "exceeds_daily_limit":
+        return `Amount exceeds the daily spending limit${result.limitSat !== void 0 ? ` of ${fromSat(result.limitSat)}` : ""}`;
+      default:
+        return "Deduction failed";
+    }
+  }
+};
+
+// src/facilitators/registry.ts
+import { Keypair as Keypair2 } from "@solana/web3.js";
+import bs58 from "bs58";
+var FacilitatorRegistry = class {
+  factories = /* @__PURE__ */ new Map();
+  instances = /* @__PURE__ */ new Map();
+  selection;
+  roundRobinIndex = 0;
+  constructor(selection) {
+    this.registerFactory("cdp", (config) => new CDPFacilitator(config));
+    this.registerFactory("tempo", () => new TempoFacilitator());
+    this.registerFactory("bnb", (config) => new BNBFacilitator(config?.serverPrivateKey));
+    this.registerFactory("solana", (config) => {
+      let feePayerKeypair;
+      const feePayerKey = config?.feePayerPrivateKey || process.env.SOLANA_FEE_PAYER_KEY;
+      if (feePayerKey) {
+        try {
+          feePayerKeypair = Keypair2.fromSecretKey(bs58.decode(feePayerKey));
+        } catch (e) {
+          console.warn(`[SolanaFacilitator] Invalid fee payer key: ${e.message}`);
+        }
+      }
+      return new SolanaFacilitator({ feePayerKeypair });
+    });
+    this.registerFactory("alipay", (config) => new AlipayFacilitator(config));
+    this.registerFactory("wechat", (config) => new WechatFacilitator(config));
+    this.registerFactory("balance", (config) => new BalanceFacilitator(config));
+    this.selection = selection || { primary: "cdp", fallback: ["tempo", "bnb", "solana"], strategy: "failover" };
+  }
+  /**
+   * Register a new facilitator factory
+   */
+  registerFactory(name, factory) {
+    this.factories.set(name, factory);
+  }
+  /**
+   * Get or create a facilitator instance
+   */
+  get(name, config) {
+    if (this.instances.has(name)) {
+      return this.instances.get(name);
+    }
+    const factory = this.factories.get(name);
+    if (!factory) {
+      throw new Error(`Unknown facilitator: ${name}. Available: ${Array.from(this.factories.keys()).join(", ")}`);
+    }
+    const mergedConfig = {
+      ...this.selection.config?.[name],
+      ...config
+    };
+    const instance = factory(mergedConfig);
+    this.instances.set(name, instance);
+    return instance;
+  }
+  /**
+   * Get all configured facilitator names
+   */
+  getConfiguredNames() {
+    const names = [this.selection.primary];
+    if (this.selection.fallback) {
+      names.push(...this.selection.fallback);
+    }
+    return names;
+  }
+  /**
+   * Get list of facilitators based on selection strategy
+   */
+  async getOrderedFacilitators(network) {
+    const names = this.getConfiguredNames();
+    const facilitators = [];
+    for (const name of names) {
+      try {
+        const f = this.get(name);
+        if (f.supportsNetwork(network)) {
+          facilitators.push(f);
+        }
+      } catch (err) {
+        console.warn(`[Registry] Failed to get facilitator ${name}:`, err);
+      }
+    }
+    if (facilitators.length === 0) {
+      throw new Error(`No facilitators available for network: ${network}`);
+    }
+    switch (this.selection.strategy) {
+      case "random":
+        return this.shuffle(facilitators);
+      case "roundrobin":
+        this.roundRobinIndex = (this.roundRobinIndex + 1) % facilitators.length;
+        return [
+          ...facilitators.slice(this.roundRobinIndex),
+          ...facilitators.slice(0, this.roundRobinIndex)
+        ];
+      case "cheapest":
+        return this.sortByCheapest(facilitators);
+      case "fastest":
+        return this.sortByFastest(facilitators);
+      case "failover":
+      default:
+        return facilitators;
+    }
+  }
+  shuffle(array) {
+    const result = [...array];
+    for (let i = result.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+  }
+  async sortByCheapest(facilitators) {
+    const withFees = await Promise.all(
+      facilitators.map(async (f) => {
+        try {
+          const fee = await f.getFee?.();
+          return { facilitator: f, perTx: fee?.perTx ?? Infinity };
+        } catch {
+          return { facilitator: f, perTx: Infinity };
+        }
+      })
+    );
+    withFees.sort((a, b) => a.perTx - b.perTx);
+    return withFees.map((w) => w.facilitator);
+  }
+  async sortByFastest(facilitators) {
+    const withLatency = await Promise.all(
+      facilitators.map(async (f) => {
+        try {
+          const health = await f.healthCheck();
+          return { facilitator: f, latency: health.latencyMs ?? Infinity };
+        } catch {
+          return { facilitator: f, latency: Infinity };
+        }
+      })
+    );
+    withLatency.sort((a, b) => a.latency - b.latency);
+    return withLatency.map((w) => w.facilitator);
+  }
+  /**
+   * Verify payment using configured facilitators
+   */
+  async verify(paymentPayload, requirements) {
+    const network = paymentPayload.accepted?.network || paymentPayload.network || requirements.network;
+    const facilitators = await this.getOrderedFacilitators(network);
+    let lastError;
+    for (const f of facilitators) {
+      try {
+        console.log(`[Registry] Trying ${f.name} for verify...`);
+        const result = await f.verify(paymentPayload, requirements);
+        if (result.valid) {
+          console.log(`[Registry] ${f.name} verify succeeded`);
+          return { ...result, facilitator: f.name };
+        }
+        lastError = result.error;
+        console.log(`[Registry] ${f.name} verify failed: ${result.error}`);
+        if (this.selection.strategy === "failover" && !this.isTransientError(result.error)) {
+          break;
+        }
+      } catch (err) {
+        lastError = err.message;
+        console.error(`[Registry] ${f.name} error:`, err.message);
+      }
+    }
+    return {
+      valid: false,
+      error: lastError || "All facilitators failed",
+      facilitator: "none"
+    };
+  }
+  /**
+   * Settle payment using configured facilitators
+   */
+  async settle(paymentPayload, requirements) {
+    const network = paymentPayload.accepted?.network || paymentPayload.network || requirements.network;
+    const facilitators = await this.getOrderedFacilitators(network);
+    let lastError;
+    for (const f of facilitators) {
+      try {
+        console.log(`[Registry] Trying ${f.name} for settle...`);
+        const result = await f.settle(paymentPayload, requirements);
+        if (result.success) {
+          console.log(`[Registry] ${f.name} settle succeeded: ${result.transaction}`);
+          return { ...result, facilitator: f.name };
+        }
+        lastError = result.error;
+        console.log(`[Registry] ${f.name} settle failed: ${result.error}`);
+      } catch (err) {
+        lastError = err.message;
+        console.error(`[Registry] ${f.name} error:`, err.message);
+      }
+    }
+    return {
+      success: false,
+      error: lastError || "All facilitators failed",
+      facilitator: "none"
+    };
+  }
+  /**
+   * Check health of all configured facilitators
+   */
+  async healthCheckAll() {
+    const results = {};
+    for (const name of this.getConfiguredNames()) {
+      try {
+        const f = this.get(name);
+        results[name] = await f.healthCheck();
+      } catch (err) {
         results[name] = { healthy: false, error: err.message };
       }
     }
@@ -1772,7 +2667,95 @@ var FacilitatorRegistry = class {
   }
 };
 
-// src/server/index.ts
+// src/server/balance-endpoints.ts
+import crypto5 from "crypto";
+
+// src/verify/index.ts
+import { ethers as ethers3 } from "ethers";
+var TRANSFER_EVENT_TOPIC3 = ethers3.id("Transfer(address,address,uint256)");
+async function verifyPayment(params) {
+  const { txHash, expectedAmount, expectedTo, expectedToken } = params;
+  let chain;
+  try {
+    if (typeof params.chain === "number") {
+      chain = getChainById(params.chain);
+    } else {
+      chain = getChain(params.chain || "base");
+    }
+    if (!chain) {
+      return { verified: false, error: `Unsupported chain: ${params.chain}` };
+    }
+  } catch (e) {
+    return { verified: false, error: `Unsupported chain: ${params.chain}` };
+  }
+  try {
+    const provider = new ethers3.JsonRpcProvider(chain.rpc);
+    const receipt = await provider.getTransactionReceipt(txHash);
+    if (!receipt) {
+      return { verified: false, error: "Transaction not found or not confirmed" };
+    }
+    if (receipt.status !== 1) {
+      return { verified: false, error: "Transaction failed" };
+    }
+    const tokenAddresses = {};
+    if (!expectedToken || expectedToken === "USDC") {
+      tokenAddresses[chain.tokens.USDC.address.toLowerCase()] = "USDC";
+    }
+    if (!expectedToken || expectedToken === "USDT") {
+      tokenAddresses[chain.tokens.USDT.address.toLowerCase()] = "USDT";
+    }
+    if (Object.keys(tokenAddresses).length === 0) {
+      return { verified: false, error: `No token addresses configured for ${chain.name}` };
+    }
+    for (const log of receipt.logs) {
+      const logAddress = log.address.toLowerCase();
+      const detectedToken = tokenAddresses[logAddress];
+      if (!detectedToken) {
+        continue;
+      }
+      if (log.topics.length < 3 || log.topics[0] !== TRANSFER_EVENT_TOPIC3) {
+        continue;
+      }
+      const from = "0x" + log.topics[1].slice(-40);
+      const to = "0x" + log.topics[2].slice(-40);
+      const amountRaw = BigInt(log.data);
+      const tokenConfig = chain.tokens[detectedToken];
+      const amount = Number(amountRaw) / 10 ** tokenConfig.decimals;
+      if (expectedTo && to.toLowerCase() !== expectedTo.toLowerCase()) {
+        continue;
+      }
+      if (amount < expectedAmount) {
+        return {
+          verified: false,
+          error: `Insufficient amount: received ${amount} ${detectedToken}, expected ${expectedAmount}`,
+          amount,
+          token: detectedToken,
+          from,
+          to,
+          txHash,
+          blockNumber: receipt.blockNumber
+        };
+      }
+      return {
+        verified: true,
+        amount,
+        token: detectedToken,
+        from,
+        to,
+        txHash,
+        blockNumber: receipt.blockNumber
+      };
+    }
+    const tokenList = expectedToken ? expectedToken : "USDC/USDT";
+    return { verified: false, error: `No ${tokenList} transfer found` };
+  } catch (e) {
+    return { verified: false, error: e.message || String(e) };
+  }
+}
+
+// src/server/internal.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import * as path2 from "path";
 var X402_VERSION2 = 2;
 var PAYMENT_REQUIRED_HEADER = "x-payment-required";
 var PAYMENT_HEADER = "x-payment";
@@ -1785,6 +2768,15 @@ var ALIPAY_PAYMENT_PROOF_HEADER = "payment-proof";
 function headerSafe(value) {
   return String(value ?? "").replace(/[^\x20-\x7E]/g, (ch) => encodeURIComponent(ch)).replace(/"/g, "%22");
 }
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalJson).join(",") + "]";
+  }
+  return "{" + Object.keys(value).sort().map((k) => JSON.stringify(k) + ":" + canonicalJson(value[k])).join(",") + "}";
+}
 var TOKEN_ADDRESSES = {
   "eip155:8453": {
     USDC: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
@@ -1875,44 +2867,377 @@ var TOKEN_DOMAINS = {
     USDC: { name: "USD Coin", version: "1" },
     USDT: { name: "Tether USD", version: "1" }
   }
-};
-function getTokenDomain(network, token) {
-  const networkDomains = TOKEN_DOMAINS[network] || TOKEN_DOMAINS["eip155:8453"];
-  return networkDomains[token] || { name: "USD Coin", version: "2" };
-}
-function getAcceptedCurrencies(config) {
-  return config.acceptedCurrencies ?? [config.currency];
-}
-function loadEnvFile2() {
-  const envPaths = [
-    path2.join(process.cwd(), ".env"),
-    path2.join(process.env.HOME || "", ".moltspay", ".env")
-  ];
-  for (const envPath of envPaths) {
-    if (existsSync2(envPath)) {
-      try {
-        const content = readFileSync2(envPath, "utf-8");
-        for (const line of content.split("\n")) {
-          const trimmed = line.trim();
-          if (!trimmed || trimmed.startsWith("#")) continue;
-          const eqIndex = trimmed.indexOf("=");
-          if (eqIndex === -1) continue;
-          const key = trimmed.slice(0, eqIndex).trim();
-          let value = trimmed.slice(eqIndex + 1).trim();
-          if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
-            value = value.slice(1, -1);
-          }
-          if (!process.env[key]) {
-            process.env[key] = value;
-          }
-        }
-        console.log(`[MoltsPay] Loaded config from ${envPath}`);
-        break;
-      } catch {
+};
+function getTokenDomain(network, token) {
+  const networkDomains = TOKEN_DOMAINS[network] || TOKEN_DOMAINS["eip155:8453"];
+  return networkDomains[token] || { name: "USD Coin", version: "2" };
+}
+function getAcceptedCurrencies(config) {
+  return config.acceptedCurrencies ?? [config.currency];
+}
+function loadEnvFile2() {
+  const envPaths = [
+    path2.join(process.cwd(), ".env"),
+    path2.join(process.env.HOME || "", ".moltspay", ".env")
+  ];
+  for (const envPath of envPaths) {
+    if (existsSync2(envPath)) {
+      try {
+        const content = readFileSync2(envPath, "utf-8");
+        for (const line of content.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith("#")) continue;
+          const eqIndex = trimmed.indexOf("=");
+          if (eqIndex === -1) continue;
+          const key = trimmed.slice(0, eqIndex).trim();
+          let value = trimmed.slice(eqIndex + 1).trim();
+          if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+            value = value.slice(1, -1);
+          }
+          if (!process.env[key]) {
+            process.env[key] = value;
+          }
+        }
+        console.log(`[MoltsPay] Loaded config from ${envPath}`);
+        break;
+      } catch {
+      }
+    }
+  }
+}
+
+// src/server/balance-endpoints.ts
+var BalanceEndpoints = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /** GET /balance?buyer_id= -- balance, limits, and today's spend. */
+  handleQuery(url, res) {
+    const { balance, sendJson } = this.deps;
+    const buyerId = url.searchParams.get("buyer_id");
+    if (!buyerId) {
+      return sendJson(res, 400, { error: "buyer_id query parameter is required" });
+    }
+    const ledger = balance.getLedger();
+    const buyer = ledger.getBuyer(buyerId);
+    if (!buyer) {
+      return sendJson(res, 200, {
+        buyer_id: buyerId,
+        balance: "0.00",
+        currency: balance.currency,
+        exists: false
+      });
+    }
+    sendJson(res, 200, {
+      buyer_id: buyerId,
+      balance: fromSat(buyer.balance_sat),
+      currency: balance.currency,
+      single_limit: fromSat(buyer.single_limit_sat),
+      daily_limit: fromSat(buyer.daily_limit_sat),
+      today_spent: fromSat(ledger.spentTodaySat(buyerId)),
+      status: buyer.status,
+      wechat_openid: buyer.wechat_openid ?? null,
+      signer_address: buyer.signer_address ?? null,
+      exists: true
+    });
+  }
+  /**
+   * Extract the gateway-confirmed paid amount (fen) from a WeChat verify
+   * result. `payer_total` is what the buyer actually paid; falls back to
+   * `total`. Returns null if no usable positive integer is present, so the
+   * client-declared amount can never be trusted for crediting.
+   */
+  wechatPaidFen(check) {
+    const amount = check.details?.amount;
+    const paid = amount?.payer_total ?? amount?.total;
+    return typeof paid === "number" && Number.isFinite(paid) && paid > 0 ? paid : null;
+  }
+  /**
+   * POST /balance/topup/order -- mint a buyer-bound WeChat Native order for a
+   * configured top-up pack. The buyer_id rides in the WeChat `attach` so the
+   * later confirm/callback credits the correct balance. Reuses the pending
+   * order cache (keyed by buyer_id + pack) so concurrent requests share one
+   * order. Body: `{ buyer_id, pack? }`. Returns `{ code_url, out_trade_no,
+   * pack, max_timeout_seconds }`.
+   */
+  async handleTopupOrder(body, res) {
+    const { manifest, wechat, sendJson, getOrCreatePendingWechatOrder } = this.deps;
+    const { buyer_id, pack } = body || {};
+    if (typeof buyer_id !== "string" || !buyer_id) {
+      return sendJson(res, 400, { error: "buyer_id is required" });
+    }
+    const signerAddress = typeof body?.signer_address === "string" && /^0x[0-9a-fA-F]{40}$/.test(body.signer_address) ? body.signer_address.toLowerCase() : void 0;
+    if (!wechat) {
+      return sendJson(res, 400, { error: "WeChat rail not configured on this server" });
+    }
+    const balCfg = manifest.provider.balance;
+    const packs = balCfg?.topup_packs ?? [];
+    const chosen = typeof pack === "string" && pack ? pack : balCfg?.default_pack;
+    if (!chosen) {
+      return sendJson(res, 400, { error: "no pack specified and no default_pack configured" });
+    }
+    let chosenSat;
+    try {
+      chosenSat = toSat(chosen);
+      if (chosenSat <= 0) throw new Error("pack must be positive");
+    } catch (err) {
+      return sendJson(res, 400, { error: `Invalid pack: ${err.message}` });
+    }
+    const withinMax = balCfg?.auto_topup_max ? chosenSat <= toSat(balCfg.auto_topup_max) : false;
+    if (!packs.includes(chosen) && !withinMax) {
+      return sendJson(res, 400, {
+        error: `pack "${chosen}" is not an offered top-up pack and exceeds auto_topup_max`
+      });
+    }
+    const nonce = crypto5.randomBytes(8).toString("hex");
+    const attach = signerAddress ? { buyer_id, signer: signerAddress } : { buyer_id, nonce };
+    const cacheKey = crypto5.createHash("sha256").update(`topup|${buyer_id}|${chosen}|${signerAddress ?? ""}`).digest("hex");
+    const result = await getOrCreatePendingWechatOrder(
+      cacheKey,
+      `topup:${buyer_id}`,
+      () => wechat.createPaymentRequirements({
+        priceCny: chosen,
+        description: `Balance top-up ${chosen}`,
+        attach
+      })
+    );
+    if (!result) {
+      return sendJson(res, 502, { error: "failed to create WeChat top-up order" });
+    }
+    return sendJson(res, 200, {
+      code_url: result.codeUrl,
+      out_trade_no: result.outTradeNo,
+      pack: chosen,
+      max_timeout_seconds: result.accepts.maxTimeoutSeconds
+    });
+  }
+  /**
+   * POST /balance/topup/confirm -- the polling-fallback credit path. The client
+   * polls this after a scan; the server verifies the order with the WeChat
+   * gateway and, on SUCCESS, credits the buyer bound in `attach` with the
+   * gateway-confirmed `payer_total` (never a client-declared amount).
+   * Idempotent on `wechat:<out_trade_no>`. Body: `{ out_trade_no }`.
+   */
+  async handleTopupConfirm(body, res) {
+    const { manifest, balance, wechat, sendJson, invalidateWechatChallenge } = this.deps;
+    const outTradeNo = body?.out_trade_no;
+    if (typeof outTradeNo !== "string" || !outTradeNo) {
+      return sendJson(res, 400, { error: "out_trade_no is required" });
+    }
+    if (!wechat) {
+      return sendJson(res, 400, { error: "WeChat rail not configured on this server" });
+    }
+    const wxPayload = {
+      x402Version: X402_VERSION2,
+      scheme: WECHAT_SCHEME,
+      network: WECHAT_NETWORK,
+      payload: { out_trade_no: outTradeNo }
+    };
+    const wxReqs = {
+      scheme: WECHAT_SCHEME,
+      network: WECHAT_NETWORK,
+      asset: "CNY",
+      amount: "0",
+      payTo: manifest.provider.wechat?.mchid || "",
+      maxTimeoutSeconds: 30,
+      extra: { out_trade_no: outTradeNo }
+    };
+    const check = await wechat.verify(wxPayload, wxReqs);
+    if (!check.valid) {
+      return sendJson(res, 200, { credited: false, pending: true, reason: check.error });
+    }
+    const paidFen = this.wechatPaidFen(check);
+    if (paidFen === null) {
+      return sendJson(res, 502, { error: "WeChat order verification did not return a usable paid amount" });
+    }
+    const attach = parseWechatAttach(check.details?.attach);
+    const buyerId = attach?.buyer_id;
+    if (!buyerId) {
+      return sendJson(res, 422, {
+        error: "top-up order has no buyer binding (attach.buyer_id missing)"
+      });
+    }
+    const credited = balance.credit({
+      buyerId,
+      amountSat: paidFen,
+      externalRef: `wechat:${outTradeNo}`,
+      description: `wechat topup out_trade_no=${outTradeNo} fiat=${JSON.stringify(check.details?.amount ?? null)}`
+    });
+    invalidateWechatChallenge(outTradeNo);
+    const openid = check.details?.openid;
+    let openidBinding;
+    if (typeof openid === "string" && openid) {
+      openidBinding = balance.getLedger().bindOpenid(buyerId, openid);
+      if (openidBinding.conflict) {
+        console.warn(
+          `[MoltsPay] Balance top-up openid conflict for buyer=${buyerId}: already bound to ${openidBinding.existing}, this payment from ${openid} \u2014 recorded, not enforced`
+        );
+      }
+    }
+    const signer = attach?.signer;
+    if (typeof signer === "string" && /^0x[0-9a-fA-F]{40}$/.test(signer)) {
+      const sb = balance.getLedger().bindSigner(buyerId, signer);
+      if (sb.conflict) {
+        console.warn(
+          `[MoltsPay] Balance top-up signer conflict for buyer=${buyerId}: already bound to ${sb.existing}, this order signed for ${signer.toLowerCase()} \u2014 recorded, not enforced`
+        );
+      }
+    }
+    console.log(
+      `[MoltsPay] Balance top-up credited buyer=${buyerId} +${fromSat(paidFen)} (${outTradeNo})${credited.replayed ? " [replayed]" : ""}${typeof openid === "string" && openid ? ` openid=${openid}${openidBinding?.conflict ? " [CONFLICT]" : ""}` : ""}`
+    );
+    return sendJson(res, 200, {
+      credited: true,
+      buyer_id: buyerId,
+      tx_id: credited.txId,
+      balance: credited.balance,
+      replayed: credited.replayed,
+      openid_bound: openidBinding?.bound ?? false,
+      openid_conflict: openidBinding?.conflict ?? false
+    });
+  }
+  /**
+   * POST /balance/topup -- verify an externally settled payment and credit the
+   * buyer's ledger balance (operator/recovery path). Per rail: `crypto`
+   * verifies the tx on-chain; `wechat` queries the order and credits the
+   * gateway-confirmed payer_total (never the client-declared amount);
+   * `alipay` is operator-trusted in this MVP. Idempotent on the external ref.
+   */
+  async handleTopup(body, res) {
+    const { manifest, balance, wechat, sendJson } = this.deps;
+    const { buyer_id, rail, amount } = body || {};
+    if (typeof buyer_id !== "string" || !buyer_id) {
+      return sendJson(res, 400, { error: "buyer_id is required" });
+    }
+    let amountSat;
+    try {
+      amountSat = toSat(String(amount));
+      if (amountSat <= 0) throw new Error("amount must be positive");
+    } catch (err) {
+      return sendJson(res, 400, { error: `Invalid amount: ${err.message}` });
+    }
+    let externalRef;
+    let description;
+    if (rail === "crypto") {
+      const txHash = body.tx_hash;
+      if (typeof txHash !== "string" || !txHash) {
+        return sendJson(res, 400, { error: 'tx_hash is required for rail "crypto"' });
+      }
+      const check = await verifyPayment({
+        txHash,
+        expectedAmount: amountSat / 100,
+        expectedTo: manifest.provider.wallet,
+        chain: body.chain || "base"
+      });
+      if (!check.verified) {
+        return sendJson(res, 402, { error: `On-chain verification failed: ${check.error}` });
+      }
+      externalRef = txHash.toLowerCase();
+      description = `crypto topup ${check.amount} ${check.token} on ${body.chain || "base"}`;
+    } else if (rail === "wechat") {
+      const outTradeNo = body.out_trade_no;
+      if (typeof outTradeNo !== "string" || !outTradeNo) {
+        return sendJson(res, 400, { error: 'out_trade_no is required for rail "wechat"' });
+      }
+      if (!wechat) {
+        return sendJson(res, 400, { error: "WeChat rail not configured on this server" });
+      }
+      const wxPayload = {
+        x402Version: X402_VERSION2,
+        scheme: WECHAT_SCHEME,
+        network: WECHAT_NETWORK,
+        payload: { out_trade_no: outTradeNo }
+      };
+      const wxReqs = {
+        scheme: WECHAT_SCHEME,
+        network: WECHAT_NETWORK,
+        asset: "CNY",
+        amount: "0",
+        payTo: manifest.provider.wechat?.mchid || "",
+        maxTimeoutSeconds: 30,
+        extra: { out_trade_no: outTradeNo }
+      };
+      const check = await wechat.verify(wxPayload, wxReqs);
+      if (!check.valid) {
+        return sendJson(res, 402, { error: `WeChat order verification failed: ${check.error}` });
+      }
+      const paidFen = this.wechatPaidFen(check);
+      if (paidFen === null) {
+        return sendJson(res, 502, { error: "WeChat order verification did not return a usable paid amount" });
       }
+      if (paidFen !== amountSat) {
+        console.warn(
+          `[MoltsPay] WeChat topup amount mismatch for ${outTradeNo}: client declared ${fromSat(amountSat)}, gateway confirms ${fromSat(paidFen)} paid -- crediting the verified amount`
+        );
+      }
+      amountSat = paidFen;
+      externalRef = `wechat:${outTradeNo}`;
+      description = `wechat topup out_trade_no=${outTradeNo} fiat=${JSON.stringify(check.details?.amount ?? null)}`;
+      console.log(`[MoltsPay] WeChat topup verified: ${description}`);
+    } else if (rail === "alipay") {
+      const tradeNo = body.trade_no;
+      if (typeof tradeNo !== "string" || !tradeNo) {
+        return sendJson(res, 400, { error: 'trade_no is required for rail "alipay"' });
+      }
+      externalRef = `alipay:${tradeNo}`;
+      description = `alipay topup trade_no=${tradeNo} (operator-confirmed, unverified)`;
+      console.warn(`[MoltsPay] Alipay topup credited without gateway verification: ${tradeNo}`);
+    } else {
+      return sendJson(res, 400, { error: 'rail must be one of "crypto" | "alipay" | "wechat"' });
     }
+    const result = balance.getLedger().topup({ buyerId: buyer_id, amountSat, externalRef, description });
+    sendJson(res, 200, {
+      success: true,
+      tx_id: result.txId,
+      balance: fromSat(result.balanceSat),
+      replayed: result.replayed ?? false
+    });
   }
-}
+  /** POST /balance/refund -- reverse a deduct (operator/agent use). */
+  handleRefund(body, res) {
+    const { balance, sendJson } = this.deps;
+    const { tx_id, reason } = body || {};
+    if (typeof tx_id !== "string" || !tx_id) {
+      return sendJson(res, 400, { error: "tx_id is required" });
+    }
+    const result = balance.refund(tx_id, typeof reason === "string" ? reason : void 0);
+    if (!result.success) {
+      return sendJson(res, result.error === "tx_not_found" ? 404 : 400, { error: result.error });
+    }
+    sendJson(res, 200, {
+      success: true,
+      tx_id: result.txId,
+      balance: fromSat(result.balanceSat),
+      replayed: result.replayed ?? false
+    });
+  }
+  /** GET /balance/transactions?buyer_id=&limit=&offset= -- history, newest first. */
+  handleTransactions(url, res) {
+    const { balance, sendJson } = this.deps;
+    const buyerId = url.searchParams.get("buyer_id");
+    if (!buyerId) {
+      return sendJson(res, 400, { error: "buyer_id query parameter is required" });
+    }
+    const limit = Math.min(parseInt(url.searchParams.get("limit") || "20", 10) || 20, 100);
+    const offset = parseInt(url.searchParams.get("offset") || "0", 10) || 0;
+    const rows = balance.getLedger().listTransactions(buyerId, limit, offset);
+    sendJson(res, 200, {
+      buyer_id: buyerId,
+      transactions: rows.map((r) => ({
+        tx_id: r.id,
+        type: r.type,
+        amount: fromSat(r.amount_sat),
+        service: r.service,
+        description: r.description,
+        external_ref: r.external_ref,
+        status: r.status,
+        created_at: r.created_at
+      }))
+    });
+  }
+};
+
+// src/server/index.ts
 var MoltsPayServer = class {
   manifest;
   skills = /* @__PURE__ */ new Map();
@@ -1920,11 +3245,32 @@ var MoltsPayServer = class {
   registry;
   networkId;
   useMainnet;
-  /** Alipay AI 收 facilitator instance, set when `provider.alipay` is configured (2.0.0). */
+  /** Alipay AI Pay facilitator instance, set when `provider.alipay` is configured (2.0.0). */
   alipayFacilitator = null;
+  /** WeChat Pay Native facilitator instance, set when `provider.wechat` is configured (2.1.0). */
+  wechatFacilitator = null;
+  /** Custodial balance facilitator instance, set when `provider.balance` is configured (2.2.0). */
+  balanceFacilitator = null;
+  balanceEndpoints = null;
+  /**
+   * Pending WeChat Native order cache — the double-charge fix.
+   *
+   * Every `buildWechatChallenge` used to place a NEW Native order, so a client
+   * that received two 402s (e.g. initial challenge + one poll re-request that
+   * raced ahead of payment) could surface two live QRs and a buyer could pay
+   * both (confirmed ¥0.07×2 on 2026-07-02). Now the unpaid order is cached
+   * under a content-derived key — sha256(service id | canonical params |
+   * price_cny) — and reused until it is paid or its `time_expire` window
+   * nears expiry, so any number of 402 emits for the same purchase intent
+   * share ONE order, even across separate client processes.
+   * Storing the in-flight promise also dedupes concurrent 402 builds.
+   * In-memory by design: on restart the worst case is one extra unpaid order,
+   * which expires server-side per `time_expire` — never a double charge.
+   */
+  wechatPendingChallenges = /* @__PURE__ */ new Map();
   constructor(servicesPath, options = {}) {
     loadEnvFile2();
-    const content = readFileSync2(servicesPath, "utf-8");
+    const content = readFileSync3(servicesPath, "utf-8");
     this.manifest = JSON.parse(content);
     this.options = {
       port: options.port || 3e3,
@@ -1946,8 +3292,8 @@ var MoltsPayServer = class {
     const providerAlipay = this.manifest.provider.alipay;
     if (providerAlipay) {
       try {
-        const baseDir = path2.dirname(servicesPath);
-        const resolvePem = (p, kind) => toPem(readFileSync2(path2.isAbsolute(p) ? p : path2.resolve(baseDir, p), "utf-8"), kind);
+        const baseDir = path3.dirname(servicesPath);
+        const resolvePem = (p, kind) => toPem(readFileSync3(path3.isAbsolute(p) ? p : path3.resolve(baseDir, p), "utf-8"), kind);
         const alipayFacilitatorConfig = {
           seller_id: providerAlipay.seller_id,
           app_id: providerAlipay.app_id,
@@ -1970,10 +3316,73 @@ var MoltsPayServer = class {
         throw new Error(`[MoltsPay] Alipay rail configured but key load failed: ${err.message}`);
       }
     }
+    const providerWechat = this.manifest.provider.wechat;
+    if (providerWechat) {
+      try {
+        const baseDir = path3.dirname(servicesPath);
+        const readPem = (p) => readFileSync3(path3.isAbsolute(p) ? p : path3.resolve(baseDir, p), "utf-8");
+        const toPublicKeyPem = (pem) => pem.includes("BEGIN CERTIFICATE") ? new crypto6.X509Certificate(pem).publicKey.export({ type: "spki", format: "pem" }).toString() : pem;
+        const wechatFacilitatorConfig = {
+          mchid: providerWechat.mchid,
+          appid: providerWechat.appid,
+          serial_no: providerWechat.serial_no,
+          private_key_pem: readPem(providerWechat.private_key_path),
+          platform_public_key_pem: providerWechat.platform_public_key_path ? toPublicKeyPem(readPem(providerWechat.platform_public_key_path)) : void 0,
+          apiv3_key: providerWechat.apiv3_key,
+          notify_url: providerWechat.notify_url,
+          api_base: providerWechat.api_base
+        };
+        facilitatorConfig.config = {
+          ...facilitatorConfig.config,
+          wechat: wechatFacilitatorConfig
+        };
+        facilitatorConfig.fallback = facilitatorConfig.fallback || [];
+        if (facilitatorConfig.primary !== "wechat" && !facilitatorConfig.fallback.includes("wechat")) {
+          facilitatorConfig.fallback.push("wechat");
+        }
+      } catch (err) {
+        throw new Error(`[MoltsPay] WeChat rail configured but key load failed: ${err.message}`);
+      }
+    }
+    const providerBalance = this.manifest.provider.balance;
+    if (providerBalance) {
+      const baseDir = path3.dirname(servicesPath);
+      const balanceFacilitatorConfig = {
+        db_path: providerBalance.db_path === ":memory:" ? providerBalance.db_path : path3.isAbsolute(providerBalance.db_path) ? providerBalance.db_path : path3.resolve(baseDir, providerBalance.db_path),
+        currency: providerBalance.currency,
+        single_limit: providerBalance.single_limit,
+        daily_limit: providerBalance.daily_limit,
+        auth_mode: providerBalance.auth_mode
+      };
+      facilitatorConfig.config = {
+        ...facilitatorConfig.config,
+        balance: balanceFacilitatorConfig
+      };
+      facilitatorConfig.fallback = facilitatorConfig.fallback || [];
+      if (facilitatorConfig.primary !== "balance" && !facilitatorConfig.fallback.includes("balance")) {
+        facilitatorConfig.fallback.push("balance");
+      }
+    }
     this.registry = new FacilitatorRegistry(facilitatorConfig);
     if (providerAlipay) {
       this.alipayFacilitator = this.registry.get("alipay");
-      console.log(`[MoltsPay] Alipay AI \u6536 rail enabled (seller ${providerAlipay.seller_id})`);
+      console.log(`[MoltsPay] Alipay AI Pay rail enabled (seller ${providerAlipay.seller_id})`);
+    }
+    if (providerWechat) {
+      this.wechatFacilitator = this.registry.get("wechat");
+      console.log(`[MoltsPay] WeChat Pay rail enabled (mchid ${providerWechat.mchid})`);
+    }
+    if (providerBalance) {
+      this.balanceFacilitator = this.registry.get("balance");
+      this.balanceEndpoints = new BalanceEndpoints({
+        manifest: this.manifest,
+        balance: this.balanceFacilitator,
+        wechat: this.wechatFacilitator,
+        sendJson: (res, status, data) => this.sendJson(res, status, data),
+        getOrCreatePendingWechatOrder: (cacheKey, logLabel, create) => this.getOrCreatePendingWechatOrder(cacheKey, logLabel, create),
+        invalidateWechatChallenge: (outTradeNo) => this.invalidateWechatChallenge(outTradeNo)
+      });
+      console.log(`[MoltsPay] Custodial balance rail enabled (ledger ${providerBalance.db_path})`);
     }
     const primaryFacilitator = this.registry.get(facilitatorConfig.primary);
     console.log(`[MoltsPay] Loaded ${this.manifest.services.length} services from ${servicesPath}`);
@@ -2015,7 +3424,10 @@ var MoltsPayServer = class {
       return provider.wallet;
     };
     if (provider.chains && provider.chains.length > 0) {
-      return provider.chains.map((c) => {
+      return provider.chains.filter((c) => {
+        const chainName = typeof c === "string" ? c : c.chain;
+        return !isAlipayChainId(chainName) && !isWechatChainId(chainName) && !isBalanceChainId(chainName);
+      }).map((c) => {
         const chainName = typeof c === "string" ? c : c.chain;
         const explicitWallet = typeof c === "object" ? c.wallet : null;
         return {
@@ -2134,9 +3546,36 @@ var MoltsPayServer = class {
       if (url.pathname === "/.well-known/agent-services.json" && req.method === "GET") {
         return this.handleAgentServicesDiscovery(res);
       }
+      if (url.pathname === "/" && req.method === "GET") {
+        return this.handleAgentServicesDiscovery(res);
+      }
       if (url.pathname === "/health" && req.method === "GET") {
         return await this.handleHealthCheck(res);
       }
+      if (url.pathname.startsWith("/balance") && this.balanceEndpoints) {
+        if (url.pathname === "/balance" && req.method === "GET") {
+          return this.balanceEndpoints.handleQuery(url, res);
+        }
+        if (url.pathname === "/balance/topup/order" && req.method === "POST") {
+          const body = await this.readBody(req);
+          return await this.balanceEndpoints.handleTopupOrder(body, res);
+        }
+        if (url.pathname === "/balance/topup/confirm" && req.method === "POST") {
+          const body = await this.readBody(req);
+          return await this.balanceEndpoints.handleTopupConfirm(body, res);
+        }
+        if (url.pathname === "/balance/topup" && req.method === "POST") {
+          const body = await this.readBody(req);
+          return await this.balanceEndpoints.handleTopup(body, res);
+        }
+        if (url.pathname === "/balance/refund" && req.method === "POST") {
+          const body = await this.readBody(req);
+          return this.balanceEndpoints.handleRefund(body, res);
+        }
+        if (url.pathname === "/balance/transactions" && req.method === "GET") {
+          return this.balanceEndpoints.handleTransactions(url, res);
+        }
+      }
       if (url.pathname === "/execute" && req.method === "POST") {
         const body = await this.readBody(req);
         const paymentHeader = req.headers[PAYMENT_HEADER];
@@ -2162,27 +3601,78 @@ var MoltsPayServer = class {
         const proofHeader = req.headers[ALIPAY_PAYMENT_PROOF_HEADER];
         return await this.handleMPPRequest(skill, body, authHeader, x402Header, res, proofHeader);
       }
-      this.sendJson(res, 404, { error: "Not found" });
+      this.sendJson(res, 404, {
+        error: "Not found",
+        discovery: `${this.publicBase}/.well-known/agent-services.json`,
+        endpoints: [`${this.publicBase}/health`, `${this.publicBase}/services`, `${this.publicBase}/execute`]
+      });
     } catch (err) {
       console.error("[MoltsPay] Error:", err);
       this.sendJson(res, 500, { error: err.message || "Internal error" });
     }
   }
   /**
-   * GET /.well-known/agent-services.json - Standard discovery endpoint
+   * Public base URL prefix for self-describing links, from PUBLIC_BASE_URL
+   * (trailing slash stripped). Empty when unset, so emitted paths stay
+   * root-relative — behavior is unchanged for local / no-prefix deploys.
+   *
+   * Needed because nginx rewrites the deployment prefix (e.g.
+   * `/t/moltspay-server`) away before proxying, so the process cannot infer
+   * its own public prefix; a root-relative `/services` would otherwise
+   * resolve against the domain root and hit the wrong backend.
    */
-  handleAgentServicesDiscovery(res) {
-    const services = this.manifest.services.map((s) => ({
+  get publicBase() {
+    return (process.env.PUBLIC_BASE_URL || "").replace(/\/+$/, "");
+  }
+  /**
+   * Per-service pricing across every configured rail, for the discovery
+   * payloads. The top-level `price`/`currency` (crypto/USDC) stay unchanged
+   * for back-compat; this surfaces the fiat + balance rails (CNY) that were
+   * previously invisible in discovery even though the manifest defines them
+   * and the 402 challenge already quotes them. `acceptedCurrencies` becomes
+   * the union across rails so a client can see CNY is accepted without
+   * first triggering a 402.
+   */
+  describeServicePricing(s) {
+    const pricing = [];
+    if (this.getProviderChains().length > 0) {
+      for (const currency of getAcceptedCurrencies(s)) {
+        pricing.push({ rail: "crypto", currency, amount: String(s.price) });
+      }
+    }
+    if (s.alipay) pricing.push({ rail: "alipay", currency: "CNY", amount: s.alipay.price_cny });
+    if (s.wechat) pricing.push({ rail: "wechat", currency: "CNY", amount: s.wechat.price_cny });
+    if (s.balance) {
+      pricing.push({
+        rail: "balance",
+        currency: this.manifest.provider.balance?.currency ?? "CNY",
+        amount: s.balance.price ?? s.price.toFixed(2)
+      });
+    }
+    return { acceptedCurrencies: [...new Set(pricing.map((p) => p.currency))], pricing };
+  }
+  /** Shared service-list entry for the discovery and /services endpoints. */
+  buildDiscoveryService(s) {
+    const { acceptedCurrencies, pricing } = this.describeServicePricing(s);
+    const headline = pricing.find((p) => p.rail === "crypto") ?? pricing[0];
+    return {
       id: s.id,
       name: s.name,
       description: s.description,
-      price: s.price,
-      currency: s.currency,
-      acceptedCurrencies: getAcceptedCurrencies(s),
+      price: headline ? Number(headline.amount) : s.price,
+      currency: headline ? headline.currency : s.currency,
+      acceptedCurrencies,
+      pricing,
       input: s.input,
       output: s.output,
       available: this.skills.has(s.id)
-    }));
+    };
+  }
+  /**
+   * GET /.well-known/agent-services.json - Standard discovery endpoint
+   */
+  handleAgentServicesDiscovery(res) {
+    const services = this.manifest.services.map((s) => this.buildDiscoveryService(s));
     this.sendJson(res, 200, {
       version: "1.0",
       provider: {
@@ -2195,9 +3685,9 @@ var MoltsPayServer = class {
       },
       services,
       endpoints: {
-        services: "/services",
-        execute: "/execute",
-        health: "/health"
+        services: `${this.publicBase}/services`,
+        execute: `${this.publicBase}/execute`,
+        health: `${this.publicBase}/health`
       },
       payment: {
         protocol: "x402",
@@ -2212,17 +3702,7 @@ var MoltsPayServer = class {
    * GET /services - List available services
    */
   handleGetServices(res) {
-    const services = this.manifest.services.map((s) => ({
-      id: s.id,
-      name: s.name,
-      description: s.description,
-      price: s.price,
-      currency: s.currency,
-      acceptedCurrencies: getAcceptedCurrencies(s),
-      input: s.input,
-      output: s.output,
-      available: this.skills.has(s.id)
-    }));
+    const services = this.manifest.services.map((s) => this.buildDiscoveryService(s));
     const selection = this.registry.getSelection();
     this.sendJson(res, 200, {
       provider: this.manifest.provider,
@@ -2281,7 +3761,7 @@ var MoltsPayServer = class {
       return this.handleAlipayExecute(skill, params || {}, alipayPayment, res);
     }
     if (!paymentHeader) {
-      return this.sendPaymentRequired(skill.config, res);
+      return this.sendPaymentRequired(skill.config, res, params || {});
     }
     let payment;
     try {
@@ -2295,6 +3775,12 @@ var MoltsPayServer = class {
     if (payScheme === ALIPAY_SCHEME || (payNetwork ? isAlipayChainId(payNetwork) : false)) {
       return this.handleAlipayExecute(skill, params || {}, payment, res);
     }
+    if (payScheme === WECHAT_SCHEME || (payNetwork ? isWechatChainId(payNetwork) : false)) {
+      return this.handleWechatExecute(skill, params || {}, payment, res);
+    }
+    if (payScheme === BALANCE_SCHEME || (payNetwork ? isBalanceChainId(payNetwork) : false)) {
+      return this.handleBalanceExecute(skill, params || {}, payment, res);
+    }
     const validation = this.validatePayment(payment, skill.config);
     if (!validation.valid) {
       return this.sendJson(res, 402, { error: validation.error });
@@ -2388,7 +3874,7 @@ var MoltsPayServer = class {
     }, responseHeaders);
   }
   /**
-   * Execute a service paid via the Alipay AI 收 fiat rail (2.0.0).
+   * Execute a service paid via the Alipay AI Pay fiat rail (2.0.0).
    *
    * Differs from the EVM/SVM path: no token detection, no EIP-3009/permit
    * validation. Verify hits the Alipay Open API (`payment.verify`). Settlement
@@ -2482,6 +3968,290 @@ var MoltsPayServer = class {
       return null;
     }
   }
+  /**
+   * Execute a service paid via the WeChat Pay v3 Native fiat rail (2.1.0).
+   *
+   * Differs from the EVM/SVM path: no token detection, no EIP-3009/permit
+   * validation. The buyer (a human) scanned the Native QR and paid; the
+   * client re-requests carrying `out_trade_no` in the X-Payment payload.
+   * Verify queries the order (`trade_state === SUCCESS`). Settlement is an
+   * idempotent re-confirm and is FIRE-AND-FORGET (mirrors the Alipay path):
+   * a confirm failure is logged but does NOT fail the delivered response —
+   * the order was already verified SUCCESS.
+   */
+  async handleWechatExecute(skill, params, payment, res) {
+    if (!this.wechatFacilitator) {
+      return this.sendJson(res, 402, { error: "WeChat rail not configured on this server" });
+    }
+    const outTradeNo = typeof payment.accepted?.extra?.out_trade_no === "string" ? payment.accepted.extra.out_trade_no : void 0;
+    const requirements = {
+      scheme: WECHAT_SCHEME,
+      network: WECHAT_NETWORK,
+      asset: "CNY",
+      amount: skill.config.wechat?.price_cny || "0",
+      payTo: this.manifest.provider.wechat?.mchid || "",
+      maxTimeoutSeconds: 300,
+      extra: outTradeNo ? { out_trade_no: outTradeNo } : void 0
+    };
+    console.log(`[MoltsPay] Verifying WeChat payment...`);
+    const verifyResult = await this.registry.verify(payment, requirements);
+    if (!verifyResult.valid) {
+      return this.sendJson(res, 402, {
+        error: `Payment verification failed: ${verifyResult.error}`,
+        facilitator: verifyResult.facilitator
+      });
+    }
+    console.log(`[MoltsPay] WeChat payment verified by ${verifyResult.facilitator}`);
+    if (outTradeNo) {
+      this.invalidateWechatChallenge(outTradeNo);
+    }
+    const timeoutSeconds = parseInt(process.env.SKILL_TIMEOUT_SECONDS || "1200");
+    console.log(`[MoltsPay] Executing skill: ${skill.id} (timeout: ${timeoutSeconds}s)`);
+    let result;
+    try {
+      result = await Promise.race([
+        skill.handler(params),
+        new Promise(
+          (_, reject) => setTimeout(() => reject(new Error(`Skill timeout after ${timeoutSeconds}s`)), timeoutSeconds * 1e3)
+        )
+      ]);
+    } catch (err) {
+      console.error("[MoltsPay] Skill execution failed:", err.message);
+      return this.sendJson(res, 500, {
+        error: "Service execution failed",
+        message: err.message
+      });
+    }
+    let settlement;
+    try {
+      settlement = await this.registry.settle(payment, requirements);
+      if (settlement.success) {
+        console.log(`[MoltsPay] WeChat settlement confirmed: ${settlement.transaction}`);
+      } else {
+        console.error(`[MoltsPay] WeChat settlement confirm failed (non-fatal): ${settlement.error}`);
+      }
+    } catch (err) {
+      console.error(`[MoltsPay] WeChat settlement confirm threw (non-fatal): ${err.message}`);
+      settlement = { success: false, error: err.message, facilitator: "wechat" };
+    }
+    const responseHeaders = {};
+    if (settlement.success) {
+      responseHeaders[PAYMENT_RESPONSE_HEADER] = Buffer.from(JSON.stringify({
+        success: true,
+        transaction: settlement.transaction,
+        network: WECHAT_NETWORK,
+        facilitator: settlement.facilitator
+      })).toString("base64");
+    }
+    this.sendJson(res, 200, {
+      success: true,
+      result,
+      payment: settlement.success ? { transaction: settlement.transaction, status: "fulfilled", facilitator: settlement.facilitator } : { status: "delivered_unconfirmed", error: settlement.error }
+    }, responseHeaders);
+  }
+  /**
+   * Build the WeChat 402 challenge for a service, or null when the wechat rail
+   * isn't configured for this server or this service. Placing a Native order
+   * is a network call that returns a fresh `code_url` + `out_trade_no`; the
+   * x402 `accepts[]` entry carries both in `extra` so the client can render
+   * the QR and later echo `out_trade_no` back for verification.
+   *
+   * DOUBLE-CHARGE FIX: the unpaid order is cached per service id (see
+   * `wechatPendingChallenges`), so repeated 402 emits within the order's
+   * `time_expire` window return the SAME `code_url`/`out_trade_no` instead of
+   * minting a new payable order each time. The entry is dropped once the
+   * order is paid (`invalidateWechatChallenge`) or shortly before it expires
+   * (refresh margin, so clients never receive a nearly-dead QR). A build
+   * failure is not cached and degrades gracefully (the other rails'
+   * accepts[] still ship).
+   */
+  async buildWechatChallenge(config, params) {
+    if (!this.wechatFacilitator || !config.wechat) return null;
+    const cacheKey = crypto6.createHash("sha256").update(`${config.id}|${canonicalJson(params ?? {})}|${config.wechat.price_cny}`).digest("hex");
+    const result = await this.getOrCreatePendingWechatOrder(
+      cacheKey,
+      config.id,
+      () => this.wechatFacilitator.createPaymentRequirements({
+        priceCny: config.wechat.price_cny,
+        description: config.wechat.description
+      })
+    );
+    return result ? { accepts: result.accepts } : null;
+  }
+  /**
+   * Get-or-create a pending WeChat Native order under `cacheKey`, deduping
+   * concurrent builds and reusing an unpaid order until it nears expiry.
+   * Shared by the 402 challenge path ({@link buildWechatChallenge}) and the
+   * balance top-up order path ({@link handleBalanceTopupOrder}). See the
+   * `wechatPendingChallenges` doc for the double-charge rationale.
+   */
+  async getOrCreatePendingWechatOrder(cacheKey, logLabel, create) {
+    const now = Date.now();
+    const cached = this.wechatPendingChallenges.get(cacheKey);
+    if (cached) {
+      if (now < cached.expiresAtMs) {
+        const hit = await cached.promise;
+        if (hit) {
+          console.log(`[MoltsPay] Reusing pending WeChat order ${hit.outTradeNo} for ${logLabel}`);
+          return hit;
+        }
+      }
+      this.wechatPendingChallenges.delete(cacheKey);
+    }
+    const orderTtlMs = WECHAT_TIME_EXPIRE_MS;
+    const cacheTtlMs = Math.max(orderTtlMs - 3e4, Math.floor(orderTtlMs / 2));
+    const entry = {
+      expiresAtMs: now + cacheTtlMs,
+      promise: Promise.resolve(null)
+    };
+    entry.promise = (async () => {
+      try {
+        const req = await create();
+        entry.outTradeNo = req.outTradeNo;
+        return { accepts: req.x402Accepts, codeUrl: req.codeUrl, outTradeNo: req.outTradeNo };
+      } catch (err) {
+        console.error(`[MoltsPay] WeChat order build failed for ${logLabel}: ${err.message}`);
+        this.wechatPendingChallenges.delete(cacheKey);
+        return null;
+      }
+    })();
+    this.wechatPendingChallenges.set(cacheKey, entry);
+    return entry.promise;
+  }
+  /**
+   * Drop the cached pending WeChat order that matches a paid `out_trade_no`,
+   * so the next 402 mints a fresh order instead of re-serving a consumed one
+   * (Native is one-code-one-payment).
+   */
+  invalidateWechatChallenge(outTradeNo) {
+    for (const [cacheKey, entry] of this.wechatPendingChallenges) {
+      if (entry.outTradeNo === outTradeNo) {
+        this.wechatPendingChallenges.delete(cacheKey);
+      }
+    }
+  }
+  /**
+   * Handle /execute for the custodial balance rail (2.2.0).
+   *
+   * Execution order is INVERTED relative to the QR rails: the deduction IS
+   * the settlement, so it must land before the skill runs, and a skill
+   * failure refunds it. `settle()` is idempotent on the client's
+   * `request_id`, so a retried request never double-charges.
+   *
+   *   QR rails:  verify(paid?) → run skill → settle (confirm, fire-and-forget)
+   *   balance:   verify implicit in settle (atomic deduct) → run skill → [fail → refund]
+   */
+  async handleBalanceExecute(skill, params, payment, res) {
+    if (!this.balanceFacilitator) {
+      return this.sendJson(res, 402, { error: "Balance rail not configured on this server" });
+    }
+    const requirements = this.balanceRequirementsFor(skill.config);
+    const authMode = this.balanceFacilitator.authMode;
+    if (authMode !== "off") {
+      const bp = extractBalancePayload(payment);
+      const buyerId = bp?.buyer_id ?? "";
+      const requestId = bp?.request_id ?? "";
+      const av = verifyDeductAuth({
+        auth: bp?.auth ?? null,
+        buyerId,
+        requestId,
+        service: skill.id,
+        nowMs: Date.now()
+      });
+      const ledger = this.balanceFacilitator.getLedger();
+      let denyReason;
+      if (av.ok && av.recovered) {
+        const bind = ledger.bindSigner(buyerId, av.recovered);
+        if (bind.conflict) denyReason = `wrong signer (account bound to ${bind.existing}, got ${av.recovered})`;
+      } else {
+        denyReason = `signature ${av.reason}`;
+      }
+      if (denyReason) {
+        if (authMode === "enforce") {
+          console.warn(`[MoltsPay] Balance auth DENY (enforce) buyer=${buyerId} svc=${skill.id}: ${denyReason}`);
+          return this.sendJson(res, 401, { error: `Balance auth failed: ${denyReason}`, facilitator: "balance" });
+        }
+        console.warn(`[MoltsPay] Balance auth would-deny (shadow) buyer=${buyerId} svc=${skill.id}: ${denyReason}`);
+      } else {
+        console.log(`[MoltsPay] Balance auth ok (${authMode}) buyer=${buyerId} signer=${av.recovered}`);
+      }
+    }
+    console.log(`[MoltsPay] Deducting balance for ${skill.id}...`);
+    const settlement = await this.balanceFacilitator.settle(payment, requirements);
+    if (!settlement.success) {
+      return this.sendJson(res, 402, {
+        error: `Balance deduction failed: ${settlement.error}`,
+        code: settlement.status,
+        facilitator: "balance"
+      });
+    }
+    console.log(`[MoltsPay] Balance deducted (tx ${settlement.transaction}${settlement.status === "replayed" ? ", replayed" : ""})`);
+    const timeoutSeconds = parseInt(process.env.SKILL_TIMEOUT_SECONDS || "1200");
+    console.log(`[MoltsPay] Executing skill: ${skill.id} (timeout: ${timeoutSeconds}s)`);
+    let result;
+    try {
+      result = await Promise.race([
+        skill.handler(params),
+        new Promise(
+          (_, reject) => setTimeout(() => reject(new Error(`Skill timeout after ${timeoutSeconds}s`)), timeoutSeconds * 1e3)
+        )
+      ]);
+    } catch (err) {
+      console.error("[MoltsPay] Skill execution failed:", err.message);
+      const refund = this.balanceFacilitator.refund(settlement.transaction, `skill_failed: ${err.message}`.slice(0, 200));
+      if (!refund.success) {
+        console.error(`[MoltsPay] Balance refund FAILED for ${settlement.transaction}: ${refund.error} \u2014 manual reconciliation needed`);
+      } else {
+        console.log(`[MoltsPay] Balance refunded (tx ${refund.txId})`);
+      }
+      return this.sendJson(res, 500, {
+        error: "Service execution failed",
+        message: err.message,
+        refunded: refund.success
+      });
+    }
+    const responseHeaders = {
+      [PAYMENT_RESPONSE_HEADER]: Buffer.from(JSON.stringify({
+        success: true,
+        transaction: settlement.transaction,
+        network: "balance",
+        facilitator: "balance"
+      })).toString("base64")
+    };
+    this.sendJson(res, 200, {
+      success: true,
+      result,
+      payment: { transaction: settlement.transaction, status: "fulfilled", facilitator: "balance" }
+    }, responseHeaders);
+  }
+  /** The balance rail's requirements for a service (price defaults to `config.price`). */
+  balanceRequirementsFor(config) {
+    const price = config.balance?.price ?? config.price.toFixed(2);
+    return {
+      scheme: BALANCE_SCHEME,
+      network: "balance",
+      asset: this.balanceFacilitator?.currency ?? "USD",
+      amount: price,
+      payTo: "custodial",
+      maxTimeoutSeconds: 30,
+      extra: { service_id: config.id }
+    };
+  }
+  /**
+   * Build the balance 402 challenge for a service, or null when the rail
+   * isn't configured for this server or this service. Pure — nothing is
+   * minted, so unlike the QR rails a 402 emit has no side effects.
+   */
+  buildBalanceChallenge(config) {
+    if (!this.balanceFacilitator || !config.balance) return null;
+    try {
+      return { accepts: this.balanceRequirementsFor(config) };
+    } catch (err) {
+      console.error(`[MoltsPay] Balance challenge build failed for ${config.id}: ${err.message}`);
+      return null;
+    }
+  }
+  /** GET /balance?buyer_id= — balance, limits, and today's spend. */
   /**
    * Handle MPP (Machine Payments Protocol) request
    * Supports both x402 and MPP protocols on service endpoints
@@ -2498,7 +4268,7 @@ var MoltsPayServer = class {
     if (authHeader && authHeader.toLowerCase().startsWith("payment ")) {
       return await this.handleMPPPayment(skill, params, authHeader, res);
     }
-    return this.sendMPPPaymentRequired(config, res);
+    return this.sendMPPPaymentRequired(config, res, params);
   }
   /**
    * Handle MPP payment verification and service execution
@@ -2597,7 +4367,7 @@ var MoltsPayServer = class {
   /**
    * Return 402 with both x402 and MPP payment requirements
    */
-  async sendMPPPaymentRequired(config, res) {
+  async sendMPPPaymentRequired(config, res, params) {
     const acceptedTokens = getAcceptedCurrencies(config);
     const providerChains = this.getProviderChains();
     const accepts = [];
@@ -2612,6 +4382,14 @@ var MoltsPayServer = class {
     if (alipayChallenge) {
       accepts.push(alipayChallenge.accepts);
     }
+    const wechatChallenge = await this.buildWechatChallenge(config, params);
+    if (wechatChallenge) {
+      accepts.push(wechatChallenge.accepts);
+    }
+    const balanceChallenge = this.buildBalanceChallenge(config);
+    if (balanceChallenge) {
+      accepts.push(balanceChallenge.accepts);
+    }
     const x402PaymentRequired = {
       x402Version: X402_VERSION2,
       accepts,
@@ -2677,7 +4455,7 @@ var MoltsPayServer = class {
    * Return 402 with x402 payment requirements (v2 format)
    * Includes requirements for all chains and all accepted currencies
    */
-  async sendPaymentRequired(config, res) {
+  async sendPaymentRequired(config, res, params) {
     const acceptedTokens = getAcceptedCurrencies(config);
     const providerChains = this.getProviderChains();
     const accepts = [];
@@ -2692,6 +4470,14 @@ var MoltsPayServer = class {
     if (alipayChallenge) {
       accepts.push(alipayChallenge.accepts);
     }
+    const wechatChallenge = await this.buildWechatChallenge(config, params);
+    if (wechatChallenge) {
+      accepts.push(wechatChallenge.accepts);
+    }
+    const balanceChallenge = this.buildBalanceChallenge(config);
+    if (balanceChallenge) {
+      accepts.push(balanceChallenge.accepts);
+    }
     const acceptedChains = providerChains.map((c) => {
       if (c.network === "eip155:8453") return "base";
       if (c.network === "eip155:137") return "polygon";
@@ -2703,7 +4489,7 @@ var MoltsPayServer = class {
       acceptedCurrencies: acceptedTokens,
       acceptedChains,
       resource: {
-        url: `/execute?service=${config.id}`,
+        url: `${this.publicBase}/execute?service=${config.id}`,
         description: `${config.name} - $${config.price} ${config.currency}`,
         mimeType: "application/json"
       }
@@ -2716,11 +4502,13 @@ var MoltsPayServer = class {
     if (alipayChallenge) {
       headers[ALIPAY_PAYMENT_NEEDED_HEADER] = alipayChallenge.paymentNeededHeader;
     }
+    const offered = this.describeServicePricing(config);
+    const message = offered.pricing.length ? `Payment required \u2014 ${offered.pricing.map((p) => `${p.rail}: ${p.amount} ${p.currency}`).join(" | ")}` : `Service requires $${config.price} ${config.currency}`;
     res.writeHead(402, headers);
     res.end(JSON.stringify({
       error: "Payment required",
-      message: `Service requires $${config.price} ${config.currency}`,
-      acceptedCurrencies: acceptedTokens,
+      message,
+      acceptedCurrencies: offered.acceptedCurrencies,
       acceptedChains,
       x402: paymentRequired
     }, null, 2));