moltspay 2.0.0 → 2.4.0

package/dist/server/index.d.mts

@@ -23,22 +23,75 @@ interface ServiceConfig {
     /** Function name to import from skill's index.js (new skill-based approach) */
     function?: string;
     /**
-     * Alipay AI 收 per-service config (2.0.0+).
+     * Alipay AI Pay per-service config (2.0.0+).
      * Set when this service accepts CNY payments via the alipay rail.
      * The `price`/`currency` fields above still describe USDC pricing
      * for the x402 rails; `alipay.price_cny` is a separate CNY price.
      */
     alipay?: ServiceAlipayConfig;
+    /**
+     * WeChat Pay v3 Native per-service config (2.1.0+).
+     * Set when this service accepts CNY payments via the wechat rail.
+     * The `price`/`currency` fields above still describe USDC pricing for the
+     * x402 rails; `wechat.price_cny` is a separate CNY price.
+     */
+    wechat?: ServiceWechatConfig;
+    /**
+     * Custodial balance per-service config (2.2.0+).
+     * Set when this service accepts password-free deduction from
+     * server-custodied buyer balances. `balance.price` defaults to the
+     * service's top-level `price` when omitted.
+     */
+    balance?: ServiceBalanceConfig;
+}
+/**
+ * Per-service custodial balance configuration (2.2.0+).
+ *
+ * Sample:
+ * ```json
+ * "balance": {
+ *   "price": "3.99"
+ * }
+ * ```
+ */
+interface ServiceBalanceConfig {
+    /**
+     * Price in the ledger currency as a decimal string (e.g. `"3.99"`).
+     * Defaults to the service's top-level `price` when omitted.
+     * Must match `/^\d+(\.\d{1,2})?$/`.
+     */
+    price?: string;
+}
+/**
+ * Per-service WeChat Pay Native configuration (2.1.0+).
+ *
+ * Sample:
+ * ```json
+ * "wechat": {
+ *   "price_cny": "10.00",
+ *   "description": "Demo video - series one"
+ * }
+ * ```
+ */
+interface ServiceWechatConfig {
+    /**
+     * CNY price as a decimal string in **yuan** (e.g. `"10.00"` = 10 CNY).
+     * NOT fen: `"100"` means 100 yuan, not 100 fen.
+     * Must match `/^\d+(\.\d{1,2})?$/`.
+     */
+    price_cny: string;
+    /** Order description shown to the payer in the WeChat app. */
+    description: string;
 }
 /**
- * Per-service Alipay AI 收 configuration (2.0.0+).
+ * Per-service Alipay AI Pay configuration (2.0.0+).
  *
  * Sample:
  * ```json
  * "alipay": {
  *   "service_id": "API_0EA6DC4FC99A4DF7",
  *   "price_cny": "7.00",
- *   "goods_name": "产品演示视频 - 系列一"
+ *   "goods_name": "Product demo video - series 1"
  * }
  * ```
  */
@@ -46,8 +99,8 @@ interface ServiceAlipayConfig {
     /** Per-service service_id (defaults to provider.alipay.service_id_default). */
     service_id?: string;
     /**
-     * CNY price as decimal string in **元** (e.g. `"7.00"` = 7 CNY).
-     * NOT cents: `"100"` means 100 元, not 100 分.
+     * CNY price as decimal string in **yuan** (e.g. `"7.00"` = 7 CNY).
+     * NOT cents: `"100"` means 100 yuan, not 100 fen.
      * Must match `/^\d+(\.\d{1,2})?$/`.
      */
     price_cny: string;
@@ -77,15 +130,95 @@ interface ProviderConfig {
     chain?: string;
     chains?: ChainConfig[];
     /**
-     * Alipay AI 收 provider-level config (2.0.0+).
+     * Alipay AI Pay provider-level config (2.0.0+).
      * Required when `chains` includes `"alipay"`.
      * Server validates `private_key_path` / `alipay_public_key_path` are
      * readable + parse as RSA PEM at startup; rejects start otherwise.
      */
     alipay?: ProviderAlipayConfig;
+    /**
+     * WeChat Pay v3 provider-level config (2.1.0+).
+     * Required when `chains` includes `"wechat"`. The server resolves the PEM
+     * file paths + validates them at startup; rejects start otherwise.
+     */
+    wechat?: ProviderWechatConfig;
+    /**
+     * Custodial balance rail provider-level config (2.2.0+).
+     * Required when `chains` includes `"balance"`. Requires Node >= 22.5
+     * (node:sqlite); the server rejects start otherwise.
+     */
+    balance?: ProviderBalanceConfig;
 }
 /**
- * Provider-level Alipay AI 收 configuration (2.0.0+).
+ * Provider-level custodial balance rail configuration (2.2.0+).
+ *
+ * Sample:
+ * ```json
+ * "balance": {
+ *   "db_path": "./data/balance.sqlite",
+ *   "currency": "USD",
+ *   "single_limit": "5.00",
+ *   "daily_limit": "10.00"
+ * }
+ * ```
+ */
+interface ProviderBalanceConfig {
+    /** SQLite ledger file path (relative to moltspay.services.json). Created on first start. */
+    db_path: string;
+    /** Ledger quote currency. Defaults to `"USD"`. */
+    currency?: string;
+    /** Default per-transaction limit for new buyers, decimal string. Defaults to `"5.00"`. */
+    single_limit?: string;
+    /** Default daily limit for new buyers, decimal string. Defaults to `"10.00"`. */
+    daily_limit?: string;
+    /** Offered top-up pack amounts in ledger currency (2.3+), e.g. `["20.00","50.00"]`. */
+    topup_packs?: string[];
+    /** Pack the client auto-selects when a 402 finds an insufficient balance (2.3+). Must be one of `topup_packs`. */
+    default_pack?: string;
+    /** Ceiling on client auto-top-up without explicit pack selection (2.3+). */
+    auto_topup_max?: string;
+    /** User-auth rollout gate for deductions: `off` | `shadow` | `enforce`. Default `off`. */
+    auth_mode?: 'off' | 'shadow' | 'enforce';
+}
+/**
+ * Provider-level WeChat Pay v3 configuration (2.1.0+).
+ *
+ * The user-facing form uses FILE PATHS for the PEM keys; the server resolves
+ * them to PEM strings before constructing WechatFacilitator.
+ *
+ * Sample:
+ * ```json
+ * "wechat": {
+ *   "mchid": "1900000001",
+ *   "appid": "wx8888888888888888",
+ *   "serial_no": "5157F09EFDC096DE15EBE81A47057A72...",
+ *   "private_key_path": "./cert/wechat_apiclient_key.pem",
+ *   "platform_public_key_path": "./cert/wechat_platform_cert.pem",
+ *   "apiv3_key": "your32byteapiv3keyhere0123456789",
+ *   "notify_url": "https://your.host/wechat/notify"
+ * }
+ * ```
+ */
+interface ProviderWechatConfig {
+    /** Merchant id (mchid). */
+    mchid: string;
+    /** App id (official account / mini-program / app). */
+    appid: string;
+    /** Merchant API certificate serial number. */
+    serial_no: string;
+    /** Path to the merchant RSA private key PEM (relative to moltspay.services.json). */
+    private_key_path: string;
+    /** Path to the WeChat platform certificate public key PEM. Enables response verification. */
+    platform_public_key_path?: string;
+    /** APIv3 key (32 bytes). Only needed for callback decryption (Phase 2). */
+    apiv3_key?: string;
+    /** Async result notify URL. Required by Native order create even when polling. */
+    notify_url: string;
+    /** Open API base URL. Defaults to `"https://api.mch.weixin.qq.com"`. */
+    api_base?: string;
+}
+/**
+ * Provider-level Alipay AI Pay configuration (2.0.0+).
  *
  * The user-facing form uses FILE PATHS for both PEM keys; the server
  * resolves them to PEM strings before constructing AlipayFacilitator.
@@ -95,7 +228,7 @@ interface ProviderConfig {
  * "alipay": {
  *   "seller_id": "2088641494699428",
  *   "app_id": "2021006150642142",
- *   "seller_name": "上海超响应数字科技有限公司",
+ *   "seller_name": "Example Co., Ltd.",
  *   "service_id_default": "API_0EA6DC4FC99A4DF7",
  *   "private_key_path": "./cert/ALIPAY_PRIVATE_KEY.txt",
  *   "alipay_public_key_path": "./cert/ALIPAY_PUBLIC_KEY.txt"
@@ -223,8 +356,29 @@ declare class MoltsPayServer {
     private registry;
     private networkId;
     private 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). */
     private alipayFacilitator;
+    /** WeChat Pay Native facilitator instance, set when `provider.wechat` is configured (2.1.0). */
+    private wechatFacilitator;
+    /** Custodial balance facilitator instance, set when `provider.balance` is configured (2.2.0). */
+    private balanceFacilitator;
+    private balanceEndpoints;
+    /**
+     * 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.
+     */
+    private wechatPendingChallenges;
     constructor(servicesPath: string, options?: MoltsPayServerOptionsExtended);
     /**
      * Register a skill handler for a service
@@ -266,6 +420,29 @@ declare class MoltsPayServer {
      * Handle incoming request
      */
     private handleRequest;
+    /**
+     * 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.
+     */
+    private get publicBase();
+    /**
+     * 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.
+     */
+    private describeServicePricing;
+    /** Shared service-list entry for the discovery and /services endpoints. */
+    private buildDiscoveryService;
     /**
      * GET /.well-known/agent-services.json - Standard discovery endpoint
      */
@@ -283,7 +460,7 @@ declare class MoltsPayServer {
      */
     private handleExecute;
     /**
-     * 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
@@ -299,6 +476,70 @@ declare class MoltsPayServer {
      * 402 responders can dual-emit both the x402 and legacy alipay-bot formats.
      */
     private buildAlipayChallenge;
+    /**
+     * 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.
+     */
+    private handleWechatExecute;
+    /**
+     * 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).
+     */
+    private buildWechatChallenge;
+    /**
+     * 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.
+     */
+    private getOrCreatePendingWechatOrder;
+    /**
+     * 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).
+     */
+    private invalidateWechatChallenge;
+    /**
+     * 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]
+     */
+    private handleBalanceExecute;
+    /** The balance rail's requirements for a service (price defaults to `config.price`). */
+    private balanceRequirementsFor;
+    /**
+     * 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.
+     */
+    private buildBalanceChallenge;
+    /** 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
@@ -377,4 +618,4 @@ declare class MoltsPayServer {
     private sendProxyPaymentRequired;
 }
 
-export { type ChainConfig, type Charge, type ChargeStatus, type CorsOptions, type InputField, MoltsPayServer, type MoltsPayServerOptions, type MoltsPayServerOptionsExtended, type OutputField, type PaymentRequest, type ProviderAlipayConfig, type ProviderConfig, type RegisteredSkill, type ServiceAlipayConfig, type ServiceConfig, type ServicesManifest, type SkillFunction, type TokenSymbol, type VerifyRequest };
+export { type ChainConfig, type Charge, type ChargeStatus, type CorsOptions, type InputField, MoltsPayServer, type MoltsPayServerOptions, type MoltsPayServerOptionsExtended, type OutputField, type PaymentRequest, type ProviderAlipayConfig, type ProviderBalanceConfig, type ProviderConfig, type ProviderWechatConfig, type RegisteredSkill, type ServiceAlipayConfig, type ServiceBalanceConfig, type ServiceConfig, type ServiceWechatConfig, type ServicesManifest, type SkillFunction, type TokenSymbol, type VerifyRequest };

package/dist/server/index.d.ts

@@ -23,22 +23,75 @@ interface ServiceConfig {
     /** Function name to import from skill's index.js (new skill-based approach) */
     function?: string;
     /**
-     * Alipay AI 收 per-service config (2.0.0+).
+     * Alipay AI Pay per-service config (2.0.0+).
      * Set when this service accepts CNY payments via the alipay rail.
      * The `price`/`currency` fields above still describe USDC pricing
      * for the x402 rails; `alipay.price_cny` is a separate CNY price.
      */
     alipay?: ServiceAlipayConfig;
+    /**
+     * WeChat Pay v3 Native per-service config (2.1.0+).
+     * Set when this service accepts CNY payments via the wechat rail.
+     * The `price`/`currency` fields above still describe USDC pricing for the
+     * x402 rails; `wechat.price_cny` is a separate CNY price.
+     */
+    wechat?: ServiceWechatConfig;
+    /**
+     * Custodial balance per-service config (2.2.0+).
+     * Set when this service accepts password-free deduction from
+     * server-custodied buyer balances. `balance.price` defaults to the
+     * service's top-level `price` when omitted.
+     */
+    balance?: ServiceBalanceConfig;
+}
+/**
+ * Per-service custodial balance configuration (2.2.0+).
+ *
+ * Sample:
+ * ```json
+ * "balance": {
+ *   "price": "3.99"
+ * }
+ * ```
+ */
+interface ServiceBalanceConfig {
+    /**
+     * Price in the ledger currency as a decimal string (e.g. `"3.99"`).
+     * Defaults to the service's top-level `price` when omitted.
+     * Must match `/^\d+(\.\d{1,2})?$/`.
+     */
+    price?: string;
+}
+/**
+ * Per-service WeChat Pay Native configuration (2.1.0+).
+ *
+ * Sample:
+ * ```json
+ * "wechat": {
+ *   "price_cny": "10.00",
+ *   "description": "Demo video - series one"
+ * }
+ * ```
+ */
+interface ServiceWechatConfig {
+    /**
+     * CNY price as a decimal string in **yuan** (e.g. `"10.00"` = 10 CNY).
+     * NOT fen: `"100"` means 100 yuan, not 100 fen.
+     * Must match `/^\d+(\.\d{1,2})?$/`.
+     */
+    price_cny: string;
+    /** Order description shown to the payer in the WeChat app. */
+    description: string;
 }
 /**
- * Per-service Alipay AI 收 configuration (2.0.0+).
+ * Per-service Alipay AI Pay configuration (2.0.0+).
  *
  * Sample:
  * ```json
  * "alipay": {
  *   "service_id": "API_0EA6DC4FC99A4DF7",
  *   "price_cny": "7.00",
- *   "goods_name": "产品演示视频 - 系列一"
+ *   "goods_name": "Product demo video - series 1"
  * }
  * ```
  */
@@ -46,8 +99,8 @@ interface ServiceAlipayConfig {
     /** Per-service service_id (defaults to provider.alipay.service_id_default). */
     service_id?: string;
     /**
-     * CNY price as decimal string in **元** (e.g. `"7.00"` = 7 CNY).
-     * NOT cents: `"100"` means 100 元, not 100 分.
+     * CNY price as decimal string in **yuan** (e.g. `"7.00"` = 7 CNY).
+     * NOT cents: `"100"` means 100 yuan, not 100 fen.
      * Must match `/^\d+(\.\d{1,2})?$/`.
      */
     price_cny: string;
@@ -77,15 +130,95 @@ interface ProviderConfig {
     chain?: string;
     chains?: ChainConfig[];
     /**
-     * Alipay AI 收 provider-level config (2.0.0+).
+     * Alipay AI Pay provider-level config (2.0.0+).
      * Required when `chains` includes `"alipay"`.
      * Server validates `private_key_path` / `alipay_public_key_path` are
      * readable + parse as RSA PEM at startup; rejects start otherwise.
      */
     alipay?: ProviderAlipayConfig;
+    /**
+     * WeChat Pay v3 provider-level config (2.1.0+).
+     * Required when `chains` includes `"wechat"`. The server resolves the PEM
+     * file paths + validates them at startup; rejects start otherwise.
+     */
+    wechat?: ProviderWechatConfig;
+    /**
+     * Custodial balance rail provider-level config (2.2.0+).
+     * Required when `chains` includes `"balance"`. Requires Node >= 22.5
+     * (node:sqlite); the server rejects start otherwise.
+     */
+    balance?: ProviderBalanceConfig;
 }
 /**
- * Provider-level Alipay AI 收 configuration (2.0.0+).
+ * Provider-level custodial balance rail configuration (2.2.0+).
+ *
+ * Sample:
+ * ```json
+ * "balance": {
+ *   "db_path": "./data/balance.sqlite",
+ *   "currency": "USD",
+ *   "single_limit": "5.00",
+ *   "daily_limit": "10.00"
+ * }
+ * ```
+ */
+interface ProviderBalanceConfig {
+    /** SQLite ledger file path (relative to moltspay.services.json). Created on first start. */
+    db_path: string;
+    /** Ledger quote currency. Defaults to `"USD"`. */
+    currency?: string;
+    /** Default per-transaction limit for new buyers, decimal string. Defaults to `"5.00"`. */
+    single_limit?: string;
+    /** Default daily limit for new buyers, decimal string. Defaults to `"10.00"`. */
+    daily_limit?: string;
+    /** Offered top-up pack amounts in ledger currency (2.3+), e.g. `["20.00","50.00"]`. */
+    topup_packs?: string[];
+    /** Pack the client auto-selects when a 402 finds an insufficient balance (2.3+). Must be one of `topup_packs`. */
+    default_pack?: string;
+    /** Ceiling on client auto-top-up without explicit pack selection (2.3+). */
+    auto_topup_max?: string;
+    /** User-auth rollout gate for deductions: `off` | `shadow` | `enforce`. Default `off`. */
+    auth_mode?: 'off' | 'shadow' | 'enforce';
+}
+/**
+ * Provider-level WeChat Pay v3 configuration (2.1.0+).
+ *
+ * The user-facing form uses FILE PATHS for the PEM keys; the server resolves
+ * them to PEM strings before constructing WechatFacilitator.
+ *
+ * Sample:
+ * ```json
+ * "wechat": {
+ *   "mchid": "1900000001",
+ *   "appid": "wx8888888888888888",
+ *   "serial_no": "5157F09EFDC096DE15EBE81A47057A72...",
+ *   "private_key_path": "./cert/wechat_apiclient_key.pem",
+ *   "platform_public_key_path": "./cert/wechat_platform_cert.pem",
+ *   "apiv3_key": "your32byteapiv3keyhere0123456789",
+ *   "notify_url": "https://your.host/wechat/notify"
+ * }
+ * ```
+ */
+interface ProviderWechatConfig {
+    /** Merchant id (mchid). */
+    mchid: string;
+    /** App id (official account / mini-program / app). */
+    appid: string;
+    /** Merchant API certificate serial number. */
+    serial_no: string;
+    /** Path to the merchant RSA private key PEM (relative to moltspay.services.json). */
+    private_key_path: string;
+    /** Path to the WeChat platform certificate public key PEM. Enables response verification. */
+    platform_public_key_path?: string;
+    /** APIv3 key (32 bytes). Only needed for callback decryption (Phase 2). */
+    apiv3_key?: string;
+    /** Async result notify URL. Required by Native order create even when polling. */
+    notify_url: string;
+    /** Open API base URL. Defaults to `"https://api.mch.weixin.qq.com"`. */
+    api_base?: string;
+}
+/**
+ * Provider-level Alipay AI Pay configuration (2.0.0+).
  *
  * The user-facing form uses FILE PATHS for both PEM keys; the server
  * resolves them to PEM strings before constructing AlipayFacilitator.
@@ -95,7 +228,7 @@ interface ProviderConfig {
  * "alipay": {
  *   "seller_id": "2088641494699428",
  *   "app_id": "2021006150642142",
- *   "seller_name": "上海超响应数字科技有限公司",
+ *   "seller_name": "Example Co., Ltd.",
  *   "service_id_default": "API_0EA6DC4FC99A4DF7",
  *   "private_key_path": "./cert/ALIPAY_PRIVATE_KEY.txt",
  *   "alipay_public_key_path": "./cert/ALIPAY_PUBLIC_KEY.txt"
@@ -223,8 +356,29 @@ declare class MoltsPayServer {
     private registry;
     private networkId;
     private 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). */
     private alipayFacilitator;
+    /** WeChat Pay Native facilitator instance, set when `provider.wechat` is configured (2.1.0). */
+    private wechatFacilitator;
+    /** Custodial balance facilitator instance, set when `provider.balance` is configured (2.2.0). */
+    private balanceFacilitator;
+    private balanceEndpoints;
+    /**
+     * 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.
+     */
+    private wechatPendingChallenges;
     constructor(servicesPath: string, options?: MoltsPayServerOptionsExtended);
     /**
      * Register a skill handler for a service
@@ -266,6 +420,29 @@ declare class MoltsPayServer {
      * Handle incoming request
      */
     private handleRequest;
+    /**
+     * 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.
+     */
+    private get publicBase();
+    /**
+     * 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.
+     */
+    private describeServicePricing;
+    /** Shared service-list entry for the discovery and /services endpoints. */
+    private buildDiscoveryService;
     /**
      * GET /.well-known/agent-services.json - Standard discovery endpoint
      */
@@ -283,7 +460,7 @@ declare class MoltsPayServer {
      */
     private handleExecute;
     /**
-     * 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
@@ -299,6 +476,70 @@ declare class MoltsPayServer {
      * 402 responders can dual-emit both the x402 and legacy alipay-bot formats.
      */
     private buildAlipayChallenge;
+    /**
+     * 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.
+     */
+    private handleWechatExecute;
+    /**
+     * 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).
+     */
+    private buildWechatChallenge;
+    /**
+     * 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.
+     */
+    private getOrCreatePendingWechatOrder;
+    /**
+     * 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).
+     */
+    private invalidateWechatChallenge;
+    /**
+     * 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]
+     */
+    private handleBalanceExecute;
+    /** The balance rail's requirements for a service (price defaults to `config.price`). */
+    private balanceRequirementsFor;
+    /**
+     * 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.
+     */
+    private buildBalanceChallenge;
+    /** 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
@@ -377,4 +618,4 @@ declare class MoltsPayServer {
     private sendProxyPaymentRequired;
 }
 
-export { type ChainConfig, type Charge, type ChargeStatus, type CorsOptions, type InputField, MoltsPayServer, type MoltsPayServerOptions, type MoltsPayServerOptionsExtended, type OutputField, type PaymentRequest, type ProviderAlipayConfig, type ProviderConfig, type RegisteredSkill, type ServiceAlipayConfig, type ServiceConfig, type ServicesManifest, type SkillFunction, type TokenSymbol, type VerifyRequest };
+export { type ChainConfig, type Charge, type ChargeStatus, type CorsOptions, type InputField, MoltsPayServer, type MoltsPayServerOptions, type MoltsPayServerOptionsExtended, type OutputField, type PaymentRequest, type ProviderAlipayConfig, type ProviderBalanceConfig, type ProviderConfig, type ProviderWechatConfig, type RegisteredSkill, type ServiceAlipayConfig, type ServiceBalanceConfig, type ServiceConfig, type ServiceWechatConfig, type ServicesManifest, type SkillFunction, type TokenSymbol, type VerifyRequest };