moltspay 1.6.0 → 2.4.0

package/README.md

@@ -25,6 +25,10 @@ MoltsPay enables agent-to-agent commerce using the [x402 protocol](https://www.x
 - **Payment Verification** - Automatic on-chain verification
 - **Secure Wallet** - Spending limits, whitelist, and audit logging
 - **Multi-chain** - Base, Polygon, Solana, BNB, Tempo (mainnet & testnet)
+- **Fiat Rail — Alipay (`2.0.0`)** - Accept CNY via Alipay AI Pay from China mainland merchants. CLI-only (Node), browser unsupported. See [`docs/ALIPAY-RAIL.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/docs/ALIPAY-RAIL.md)
+- **Fiat Rail — WeChat Pay (`2.1.0`)** - Accept CNY via WeChat Pay v3 Native (scan-to-pay). SDK-managed recoverable sessions persist QR/order context, poll in the background, and fulfill idempotently. See [`docs/WECHAT-RAIL-DESIGN.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/docs/WECHAT-RAIL-DESIGN.md)
+- **Balance Rail — Password-Free (`2.2.0`)** - Top up once, then pay with no signature or QR per transaction. Server-custodied SQLite ledger with atomic deducts, hard spending limits, and idempotent retries. See [`docs/WECHAT-BALANCE-PASSWORDLESS-DESIGN.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/docs/WECHAT-BALANCE-PASSWORDLESS-DESIGN.md)
+- **Balance Identity & Authentication (`2.4.0`)** - The balance rail gets a real user: accounts are anchored to the WeChat payer's `openid` at top-up, and each deduction is authorized by a per-request signature (`auth_mode: off` | `shadow` | `enforce`). Knowing a `buyer_id` is no longer enough to spend — closes the bearer hole. See [Balance Authentication](#balance-authentication-240) below
 - **Agent-to-Agent** - Complete A2A payment flow support
 - **Multi-VM** - EVM chains + Solana (SVM) with unified API
 - **MCP Server** - Expose wallet + payments to Claude Desktop, Cursor, and other MCP hosts
@@ -274,7 +278,7 @@ Servers advertising for the web need `cors` enabled; CLI callers are unaffected
 
 **Security posture.** No private key ever enters browser memory. No filesystem access, no `~/.moltspay/` — the wallet is always external. The `signer` object the client receives only has permission to sign typed data and (for BNB) submit one `approve` transaction, which the user explicitly confirms in the wallet UI.
 
-**Reference demo.** `examples/web/` is a runnable React + Vite app that exercises every path above. `cd examples/web && npm install && npm run dev` — it connects to `https://moltspay.com/a/zen7` by default. See [`examples/web/README.md`](examples/web/README.md) for the full matrix of tested wallets + chains.
+**Reference demo.** `examples/web/` is a runnable React + Vite app that exercises every path above. `cd examples/web && npm install && npm run dev` — it connects to `https://moltspay.com/a/zen7` by default. See [`examples/web/README.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/examples/web/README.md) for the full matrix of tested wallets + chains.
 
 ## MCP Server (For AI Assistants)
 
@@ -318,7 +322,7 @@ Each host has its own config file for registering stdio MCP servers — check yo
 2. **Dry-run mode** — launch with `--dry-run` and payments return a preview instead of signing.
 3. **Confirmation gate** — set `MOLTSPAY_MCP_REQUIRE_CONFIRM=1` to require a second tool call (`confirmed: true`) for any payment exceeding `maxPerTx / 10`.
 
-Private keys and mnemonics are never exposed over MCP — wallet creation stays on the CLI (`npx moltspay init`) by design. See [`docs/MCP-USAGE.md`](docs/MCP-USAGE.md) for full tool arguments and troubleshooting.
+Private keys and mnemonics are never exposed over MCP — wallet creation stays on the CLI (`npx moltspay init`) by design. See [`docs/MCP-USAGE.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/docs/MCP-USAGE.md) for full tool arguments and troubleshooting.
 
 ## Payment Protocols
 
@@ -330,6 +334,8 @@ MoltsPay supports multiple payment protocols, each optimized for different chain
 | x402 + SOL | Solana | Gasless (server pays) | HTTP 402 + SPL transfer |
 | x402 + BNB | BNB | Gasless (server pays) | HTTP 402 + EIP-712 intent signing |
 | MPP | Tempo | Gas-free native | HTTP 402 + WWW-Authenticate |
+| x402 + Alipay | Alipay | No blockchain gas | HTTP 402 + Alipay AI Pay proof |
+| x402 + WeChat Pay | WeChat Pay Native | No blockchain gas | HTTP 402 + scan-to-pay QR, poll-based verify |
 
 ### How x402 Protocol Works
 
@@ -568,10 +574,19 @@ npx moltspay faucet --chain solana_devnet   # Get Solana devnet USDC
 npx moltspay faucet --chain bnb_testnet     # Get BNB testnet USDC + tBNB
 npx moltspay faucet --chain tempo_moderato  # Get Tempo testnet tokens
 npx moltspay status                  # Check balance (all chains)
+npx moltspay transfer <to> <amount>  # Transfer USDC/USDT out to any address (e.g. an exchange)
 npx moltspay config                  # Update limits
 npx moltspay services <url>          # List provider's services
 npx moltspay pay <url> <service>     # Pay and execute service
 
+# === Transfer / Withdraw (2.4.0) ===
+# Move USDC/USDT out of your wallet to any address (e.g. an exchange deposit address).
+npx moltspay transfer <to> <amount>                       # 5 USDC on Base (default), interactive confirm
+npx moltspay transfer <to> 10 --token USDT --chain bnb     # USDT on BNB Chain
+npx moltspay transfer <to> 5 --chain polygon --yes --json  # non-interactive (agents/scripts)
+# EVM chains only (base/polygon/bnb/...); a normal on-chain transfer, so the wallet needs a
+# little native gas (ETH/BNB/POL). The transfer network must match the receiver's deposit network.
+
 # === Service Discovery ===
 npx moltspay services                           # List all from registry
 npx moltspay services https://provider.com      # List from specific provider
@@ -590,6 +605,38 @@ npx moltspay pay <url> <service> --chain solana_devnet # Pay on Solana devnet
 npx moltspay pay <url> <service> --chain bnb           # Pay on BNB
 npx moltspay pay <url> <service> --chain bnb_testnet   # Pay on BNB testnet
 npx moltspay pay <url> <service> --chain tempo_moderato # Pay on Tempo
+npx moltspay pay <url> <service> --rail alipay         # Pay with Alipay AI Pay
+npx moltspay pay <url> <service> --rail wechat         # Pay with WeChat Pay Native QR
+npx moltspay pay <url> <service> --rail balance        # Pay password-free from prepaid balance
+
+# === BNB One-Time Approve ===
+# BNB payments need a one-time spender approval first (the spender comes from the 402 response).
+npx moltspay approve --spender <address> --chain bnb   # Approve, then `pay --chain bnb` is gasless
+npx moltspay approve --spender <address>               # --chain defaults to bnb_testnet
+
+# === WeChat Recoverable Sessions ===
+npx moltspay wechat start <url> <service> --prompt "..."   # Start order, return QR metadata immediately
+npx moltspay wechat status <session-or-out_trade_no>        # Query/recover a pending session
+npx moltspay wechat fulfill <session-or-out_trade_no>       # Idempotently fulfill if paid
+npx moltspay wechat cancel <session-or-out_trade_no>        # Mark local session cancelled
+npx moltspay wechat list                                   # List persisted WeChat sessions
+
+# === Custodial Balance (Password-Free) ===
+npx moltspay balance set-buyer <id>                        # Persist the buyer id (account label)
+npx moltspay balance query <url>                           # Balance, limits, today's spend, bound signer/openid
+npx moltspay balance transactions <url>                    # Ledger history, newest first
+npx moltspay balance topup <url> <amount> --rail crypto --tx-hash 0x...   # Credit from a settled payment (crypto/wechat/alipay)
+
+# --- Identity & auth (2.4.0) ---
+npx moltspay balance whoami [url]                          # Show local signer address (and, vs a server, the account's bound signer/openid)
+npx moltspay balance bind <url>                            # Bind the local signer to an account (runs a minimal top-up to establish identity)
+
+# --- Recoverable WeChat-funded top-up (for chat agents; non-blocking) ---
+npx moltspay balance topup-order <url> --pack 2.00         # Mint a WeChat pack order, emit the QR, exit immediately
+npx moltspay balance topup-confirm <out_trade_no>          # Confirm + credit a pending order later (idempotent on out_trade_no)
+npx moltspay balance topup-status <out_trade_no>           # Query one pending order
+npx moltspay balance topup-list                            # List pending top-up orders
+npx moltspay balance topup-pack <url>                      # Blocking variant: mint pack, wait for the scan, credit inline
 
 # === Server Commands ===
 npx moltspay start <skill-dir>       # Start server
@@ -599,6 +646,7 @@ npx moltspay validate <path>         # Validate manifest
 # === Options ===
 --port <port>                        # Server port (default 3000)
 --chain <chain>                      # Chain: base, polygon, solana, bnb, tempo_moderato, + testnets
+--rail <rail>                        # Rail: alipay, wechat, or balance (password-free)
 --token <token>                      # Token: USDC, USDT
 --max-per-tx <amount>                # Spending limit per transaction
 --max-per-day <amount>               # Daily spending limit
@@ -777,15 +825,21 @@ npx moltspay pay https://server.com service-id --chain solana --prompt "test"
 
 BNB uses the **BNBFacilitator** with a pre-approval flow. Since CDP doesn't support BNB, we use a different approach:
 
-1. Client signs an EIP-712 payment intent (no gas needed)
-2. Server validates and executes the transfer
-3. Server sponsors gas (~$0.0001 per tx)
+1. Client approves a spender **once** (a one-time on-chain `approve`, costs ~0.001 BNB gas)
+2. Client signs an EIP-712 payment intent (no gas needed)
+3. Server validates and executes the transfer
+4. Server sponsors gas (~$0.0001 per tx)
 
 ```bash
 # Get free testnet USDC + tBNB for gas
 npx moltspay faucet --chain bnb_testnet
 
-# Pay on BNB (client pays no gas!)
+# One-time approve (required before the first BNB payment).
+# The spender address comes from the server's 402 response; a first `pay` also
+# prints it if you haven't approved yet.
+npx moltspay approve --spender 0xSPENDER --chain bnb_testnet
+
+# Pay on BNB (client pays no gas after the approve!)
 npx moltspay pay https://server.com service-id --chain bnb_testnet --prompt "test"
 
 # Check BNB balance
@@ -821,13 +875,418 @@ npx moltspay status
 
 **Explorer:** https://explore.testnet.tempo.xyz
 
+## Fiat Rail (Alipay / CNY)
+
+Since **`2.0.0`**, MoltsPay supports a **fiat payment rail via Alipay AI Pay**, settling in **CNY** alongside the existing USDC crypto rails. It uses the same HTTP 402 flow, so a service can price in USDC, CNY, or both — a purely additive change that leaves existing crypto-only services untouched.
+
+Unlike the crypto rails, `alipay` is a **fiat rail, not a blockchain**: there is no gas and no on-chain settlement — the buyer pays in the Alipay app and the merchant settles in CNY. The scheme is `alipay-aipay`, signed with RSA2.
+
+> ⚠️ **Node CLI only.** The Alipay client wraps the `alipay-bot` CLI and requires Node ≥ 22. The browser build (`moltspay/web`) throws `UnsupportedChainError` for `alipay`. Provider/server config is 100% native TypeScript.
+
+### Provider Setup (Selling in CNY)
+
+Add `"alipay"` to `chains`, configure `provider.alipay` with your merchant keys, and add a per-service `alipay` block with the CNY price. Crypto and fiat can coexist:
+
+```json
+{
+  "provider": {
+    "name": "My Service",
+    "wallet": "0x...",
+    "chains": ["base", "alipay"],
+    "alipay": {
+      "seller_id": "2088xxxxxxxxxxxx",
+      "app_id": "2021xxxxxxxxxxxx",
+      "seller_name": "My Shop",
+      "service_id_default": "API_XXXXXXXXXXXXXXXX",
+      "private_key_path": "./cert/app_private_key.pem",
+      "alipay_public_key_path": "./cert/alipay_public_key.pem"
+    }
+  },
+  "services": [{
+    "id": "my-service",
+    "function": "handleRequest",
+    "price": 0.50,
+    "currency": "USDC",
+    "alipay": { "price_cny": "7.00", "goods_name": "My Service" }
+  }]
+}
+```
+
+**`provider.alipay`** (required when `chains` includes `alipay`):
+
+| Field | Req | Description |
+|-------|-----|-------------|
+| `seller_id` | ✅ | Merchant Alipay ID (16 digits) |
+| `app_id` | ✅ | Application ID from the Alipay Open Platform (16 digits) |
+| `seller_name` | ✅ | Merchant display name (shown in the 402 challenge) |
+| `service_id_default` | ✅ | Default `service_id` for this provider (e.g. `API_XXXXXXXXXXXXXXXX`) |
+| `private_key_path` | ✅ | Path to the RSA2 merchant private key PEM (relative to the manifest) |
+| `alipay_public_key_path` | ✅ | Path to the Alipay platform public key PEM |
+| `gateway_url` | — | Open API gateway (default production; use the sandbox URL for testing) |
+| `sign_type` | — | Signature algorithm — only `RSA2` is supported |
+
+**`services[].alipay`** (set on each service that accepts CNY):
+
+| Field | Req | Description |
+|-------|-----|-------------|
+| `price_cny` | ✅ | CNY price as a decimal string in **yuan**, e.g. `"7.00"` = 7 CNY (**NOT cents**) |
+| `goods_name` | ✅ | Goods name shown to the buyer in the Alipay app |
+| `service_id` | — | Per-service override (defaults to `provider.alipay.service_id_default`) |
+
+> ⚠️ `price` (USDC) and `price_cny` (CNY) are **two independent prices** — MoltsPay does no FX conversion. You decide whether USDC `0.50` is equivalent to CNY `7.00`. The merchant-backend unit price must match `price_cny` or the challenge is rejected.
+
+### Client Usage (Paying in CNY)
+
+The Alipay client relies on the `alipay-bot` CLI, which is **auto-provisioned on install** from the official Alipay CDN (postinstall, best-effort). Set `MOLTSPAY_SKIP_CLI_INSTALL=1` to skip it, or install it manually later:
+
+```bash
+# Manual / CI install of the bundled CLI
+npx -y @alipay/agent-payment install-cli
+alipay-bot --version          # expect >= 0.3.15
+
+# One-time: open & authorize the Alipay wallet (scan the returned QR in the app)
+npx moltspay alipay apply
+npx moltspay alipay bind -c "<auth-code>"
+npx moltspay alipay check
+
+# Pay a service in CNY
+npx moltspay pay https://server.com my-service --rail alipay --prompt "..."
+```
+
+> 🔐 **Keep keys safe.** The RSA2 private key authorizes collection on your merchant account. Store the PEM files outside version control and reference them by path in the manifest.
+
+See [`docs/ALIPAY-RAIL.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/docs/ALIPAY-RAIL.md) for the full reference (402 flow, error codes, end-to-end example, and known issues).
+
+## Fiat Rail (WeChat Pay / CNY)
+
+Since **`2.1.0`**, MoltsPay supports a second **fiat payment rail via WeChat Pay v3 Native (scan-to-pay)**, settling in **CNY** alongside USDC and Alipay. It uses the same HTTP 402 flow, so a service can price in USDC, Alipay-CNY, WeChat-CNY, or any combination — purely additive.
+
+Like `alipay`, `wechat` is a **fiat rail, not a blockchain**. The scheme is `wechatpay-native`, requests are signed with **SHA256-RSA** (`WECHATPAY2-SHA256-RSA2048`), and amounts are sent to WeChat in **fen** (the manifest still uses **yuan** decimal strings for consistency).
+
+> ⚠️ **Not a fully autonomous payer.** WeChat Pay has no agent-payment product equivalent to Alipay's `alipay-bot`. The flow is: the server issues a **payer-agnostic `code_url`** (Native, no `openid` — anyone can scan), the SDK client persists the session and polls, a human scans and pays, and the server verifies the order (`trade_state === SUCCESS`). It is **one code, one payment** — issue a new code to collect again. See [`docs/WECHAT-RAIL-DESIGN.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/docs/WECHAT-RAIL-DESIGN.md).
+
+### Provider Setup (Selling in CNY)
+
+Add `"wechat"` to `chains`, configure `provider.wechat` with your merchant credentials, and add a per-service `wechat` block with the CNY price:
+
+```json
+{
+  "provider": {
+    "name": "My Service",
+    "wallet": "0x...",
+    "chains": ["base", "wechat"],
+    "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"
+    }
+  },
+  "services": [{
+    "id": "my-service",
+    "function": "handleRequest",
+    "price": 0.50,
+    "currency": "USDC",
+    "wechat": { "price_cny": "7.00", "description": "My Service" }
+  }]
+}
+```
+
+**`provider.wechat`** (required when `chains` includes `wechat`):
+
+| Field | Req | Description |
+|-------|-----|-------------|
+| `mchid` | ✅ | Merchant id |
+| `appid` | ✅ | App id (official account / mini-program / app) |
+| `serial_no` | ✅ | Merchant API certificate serial number |
+| `private_key_path` | ✅ | Path to the merchant RSA private key PEM (relative to the manifest) |
+| `notify_url` | ✅ | Async result notify URL (required by Native order create even when polling) |
+| `platform_public_key_path` | — | WeChat platform certificate / public key PEM — enables response signature verification |
+| `apiv3_key` | — | APIv3 key (32 bytes) — only needed for callback decryption (Phase 2) |
+| `api_base` | — | Open API base URL (default `https://api.mch.weixin.qq.com`) |
+
+**`services[].wechat`** (set on each service that accepts CNY):
+
+| Field | Req | Description |
+|-------|-----|-------------|
+| `price_cny` | ✅ | CNY price as a decimal string in **yuan**, e.g. `"7.00"` = 7 CNY (**NOT fen**) |
+| `description` | ✅ | Order description shown to the payer in the WeChat app |
+
+> ⚠️ `price` (USDC) and `price_cny` (CNY) are **independent prices** — MoltsPay does no FX conversion.
+
+### How It Works
+
+1. An unpaid request to `/execute` returns **402** with a `wechatpay-native` entry in `accepts[]`, carrying `extra.code_url` (`weixin://wxpay/bizpayurl?pr=...`) and `extra.out_trade_no`.
+2. The SDK client persists a payment session before surfacing the QR. A channel runtime can show the returned PNG/`MEDIA` image and continue independently of the original tool call.
+3. A human scans and pays. The Native `code_url` is a QR payload, not a normal HTTPS checkout link.
+4. The SDK client polls by re-requesting `/execute` with an `X-Payment` payload echoing `out_trade_no`; the server verifies via order query and, on `SUCCESS`, runs the skill and confirms settlement.
+5. If the process is interrupted, the session can be resumed by `payment_session_id` or `out_trade_no`; `fulfill` is idempotent and returns the stored result once completed.
+
+### Buyer SDK Usage
+
+Blocking terminal-style payment:
+
+```ts
+import { MoltsPayClient } from 'moltspay/client';
+
+const client = new MoltsPayClient();
+const result = await client.pay(
+  'https://server.com',
+  'my-service',
+  { prompt: 'hello' },
+  {
+    rail: 'wechat',
+    onPaymentPending: ({ paymentUrl, tradeNo }) => {
+      console.log('Render this as a QR:', paymentUrl, tradeNo);
+    },
+  },
+);
+```
+
+Recoverable channel/session payment:
+
+```ts
+const session = await client.startWechatPayment(
+  'https://server.com',
+  'my-service',
+  { prompt: 'hello' },
+  {
+    rail: 'wechat',
+    autoPoll: true,
+    onPaymentPending: ({ paymentUrl, tradeNo }) => {
+      // Render paymentUrl as QR and send it to the current channel.
+    },
+    onWechatPaymentCompleted: async (completed) => {
+      // Send completed.resultBody, parsed as needed, back to the channel.
+    },
+    onWechatPaymentFailed: async (failed) => {
+      // Notify timeout/cancel/failure.
+    },
+  },
+);
+
+console.log(session.paymentSessionId, session.outTradeNo);
+```
+
+CLI recoverable flow:
+
+```bash
+npx moltspay wechat start https://server.com my-service --prompt "hello" --json
+npx moltspay wechat status mpay_sess_...
+npx moltspay wechat fulfill mpay_sess_...
+```
+
+See [`examples/wechat-native-pay.ts`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/examples/wechat-native-pay.ts) for a runnable scenario-A demo (mock by default; `WECHAT_REAL=1` hits the live gateway).
+
+> 🔐 **Keep keys safe.** The merchant private key and APIv3 key authorize collection on your merchant account. Store them outside version control and reference them by path.
+
+## Balance Rail (Password-Free Payments)
+
+Since **`2.2.0`**, MoltsPay supports a third payment mode: a **custodial balance rail (password-free)**. A buyer tops up once — via any existing rail — and subsequent purchases are deducted from a server-custodied balance: **no signature, no QR scan, no password per transaction**. It uses the same HTTP 402 flow (scheme/network `balance`), so a service can offer crypto, Alipay-CNY, WeChat-CNY, and balance simultaneously — purely additive.
+
+Unlike the other rails, nothing settles externally at purchase time: the ledger lives in SQLite on the provider server (Node's built-in `node:sqlite`, zero new dependencies). Enabling the rail requires **Node.js >= 22.5** on the server; servers that don't enable it keep the package's `node >= 18` floor.
+
+> ⚠️ **Custodial trust model.** Buyer funds are held by the provider. Since **`2.4.0`**, spending is authorized by a **per-request signature**, not a bare `buyer_id` — see [Balance Authentication](#balance-authentication-240) below. With `auth_mode: enforce`, knowing a `buyer_id` is not enough to spend. (`auth_mode` defaults to `off` for backward compatibility, where the id retains bearer semantics.) See [`docs/WECHAT-BALANCE-PASSWORDLESS-DESIGN.md`](https://github.com/Yaqing2023/moltspay/blob/v2.4.0/docs/WECHAT-BALANCE-PASSWORDLESS-DESIGN.md).
+
+### Balance Authentication (`2.4.0`)
+
+Before 2.4.0 the balance rail identified a buyer by a single plaintext `buyer_id`: anyone who knew it could spend that balance (bearer semantics), and the same person writing it two ways split into two accounts. 2.4.0 gives the rail a real identity, in two complementary halves:
+
+- **Identity anchor = WeChat `openid`.** On a WeChat-funded top-up, the server extracts `payer.openid` from the (signature-verified) order query and records it on the account. Accounts are anchored to the person who actually paid, not to a self-reported string — this removes the account-splitting class of bug at the source. Binding is observational and never overwrites a conflicting openid.
+- **Spend credential = a per-request signature.** Each deduction carries an EIP-191 signature over a canonical message (domain `moltspay-balance-auth:v1` / `balance-deduct` / `buyer_id` / `request_id` / `service` / `timestamp`). The server recovers the signer address, TOFU-binds it to the account on first use, and verifies it thereafter. The amount is deliberately *not* signed (the service id fixes the price server-side); a `request_id` + a ±5-minute `timestamp` window bound replay.
+
+**`provider.balance.auth_mode`** — staged rollout, not on by default:
+
+| Mode | Behavior |
+|------|----------|
+| `off` (default) | Signature is not checked. Backward-compatible; `buyer_id` keeps bearer semantics. |
+| `shadow` | Verify and log what it *would* reject, without blocking. Use this to confirm every client is signing before tightening. |
+| `enforce` | Reject unsigned / invalid / wrong-signer requests with **401**. |
+
+The client signs with its EVM wallet, or — for balance-only clients with no crypto wallet — a per-configDir identity key auto-created at `<configDir>/balance-identity.key` (0600). Inspect and bind identity with `moltspay balance whoami` / `moltspay balance bind`.
+
+> **Foundation — WeChat response verification.** The `openid` anchor is only trustworthy if the order-query response is verified against the WeChat platform certificate. Configure `provider.wechat.platform_public_key_path` (present ⇒ every response is verified, and a verification failure throws); without it, the identity anchor is not trustworthy.
+
+> **Trust model — one agent key spends for all its users.** The shipped model is *agent-custodial*: a single agent key is bound to every account it tops up (`signer_address` is one-to-many). Accounts stay separated by openid, but **whoever holds the agent's key can spend every bound user's balance** — protect `balance-identity.key` accordingly. There is currently no revocation/freeze API (operator-only, via the ledger DB); per-user key isolation is a future upgrade.
+
+### WeChat-Funded Password-Free (Scan Once, Then Password-Free)
+
+Since **`2.3.0`**, the WeChat rail can **fund** the balance instead of charging per transaction. The buyer scans **once** to load a top-up pack (e.g. ¥20); every subsequent purchase deducts from the balance with **no scan, no password**, until it runs low and one more scan tops it up. WeChat has no autonomous payer, so "password-free" lives on the balance side — the first purchase against an empty balance still needs one scan, but it buys a pack, not a single item.
+
+Set the ledger currency to `CNY` (WeChat `payer_total` credits 1:1 as fen — no FX), define top-up packs, and the client handles the rest:
+
+```json
+{
+  "provider": {
+    "name": "My Service",
+    "wallet": "0x...",
+    "chains": ["balance", "wechat"],
+    "balance": {
+      "db_path": "./data/balance-cny.sqlite",
+      "currency": "CNY",
+      "single_limit": "50.00",
+      "daily_limit": "200.00",
+      "topup_packs": ["20.00", "50.00"],
+      "default_pack": "20.00",
+      "auto_topup_max": "50.00"
+    },
+    "wechat": {
+      "mchid": "1900000001",
+      "appid": "wx8888888888888888",
+      "serial_no": "...",
+      "private_key_path": "/abs/apiclient_key.pem",
+      "notify_url": "https://your-host/wechat/notify",
+      "platform_public_key_path": "/abs/wechat_platform_cert.pem",
+      "apiv3_key": "<32-byte apiv3 key>"
+    }
+  },
+  "services": [{
+    "id": "my-service",
+    "function": "handleRequest",
+    "price": 3.99,
+    "currency": "CNY",
+    "balance": { "price": "3.99" }
+  }]
+}
+```
+
+**New `provider.balance` fields (2.3.0):**
+
+| Field | Req | Description |
+|-------|-----|-------------|
+| `currency` | — | Set to `"CNY"` to fund via WeChat 1:1 (fen). A ledger remembers its currency and refuses to start on a mismatch |
+| `topup_packs` | — | Offered recharge amounts (yuan strings), e.g. `["20.00","50.00"]` |
+| `default_pack` | — | Pack the client auto-selects when funds are short (must be in `topup_packs`) |
+| `auto_topup_max` | — | Ceiling on client auto-top-up without explicit pack selection |
+
+Top-ups are confirmed by **polling the WeChat order query** (`trade_state === SUCCESS`) and credited idempotently on `out_trade_no`. The async callback webhook (`POST /wechat/notify`) is **not implemented yet** — polling is the only confirmation path today, which is safe but adds latency. Configure `platform_public_key_path` regardless: it makes the server verify WeChat's response signatures, which is what makes the `payer.openid` behind balance identity trustworthy. Usage — a single `pay` command:
+
+```bash
+npx moltspay balance set-buyer my-buyer-id
+# First purchase: prints a pack QR, waits for the scan, credits, completes.
+# Later purchases: password-free, no QR — deducted from the balance.
+npx moltspay pay https://server.com my-service '{"prompt":"hello"}'
+```
+
+### Money-Safety Design
+
+- **Integer-cent accounting** — no floating-point drift.
+- **Atomic check-and-deduct** — a single SQLite transaction (`UPDATE ... WHERE balance_sat >= ?`); a balance can never go negative under concurrency.
+- **Triple idempotency**, each enforced by a unique index: deducts replay on the client's `request_id`, top-ups replay on the external settlement reference, refunds replay per deduct. No retry can double-charge, double-credit, or double-refund.
+- **Server-side hard limits** per buyer: per-transaction (default `5.00`) and daily (default `10.00`).
+- **Automatic refund** — the deduct lands *before* the skill runs; if the skill fails, the server refunds it in the same request.
+- **Pure 402 challenges** — unlike the QR rails, a 402 response mints nothing, so unpaid challenges have no side effects.
+- **Full audit trail** — every top-up, deduct, and refund is a permanent ledger row, queryable per buyer.
+
+### Provider Setup
+
+Add `"balance"` to `chains`, configure `provider.balance`, and add a per-service `balance` block (its `price` defaults to the service's top-level price):
+
+```json
+{
+  "provider": {
+    "name": "My Service",
+    "wallet": "0x...",
+    "chains": ["base", "balance"],
+    "balance": {
+      "db_path": "./data/balance.sqlite",
+      "currency": "USD",
+      "single_limit": "5.00",
+      "daily_limit": "10.00"
+    }
+  },
+  "services": [{
+    "id": "my-service",
+    "function": "handleRequest",
+    "price": 3.99,
+    "currency": "USDC",
+    "balance": { "price": "3.99" }
+  }]
+}
+```
+
+**`provider.balance`** (required when `chains` includes `balance`):
+
+| Field | Req | Description |
+|-------|-----|-------------|
+| `db_path` | ✅ | SQLite ledger file path (relative to the manifest); created on first start |
+| `currency` | — | Ledger quote currency (default `USD`) |
+| `single_limit` | — | Default per-transaction limit for new buyers (default `"5.00"`) |
+| `daily_limit` | — | Default daily limit for new buyers (default `"10.00"`) |
+
+**`services[].balance`**:
+
+| Field | Req | Description |
+|-------|-----|-------------|
+| `price` | — | Price in the ledger currency as a decimal string; defaults to the service's `price` |
+
+The server also exposes balance-management endpoints:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /balance?buyer_id=` | Balance, limits, and today's spend |
+| `POST /balance/topup` | Verify an externally settled payment and credit the ledger |
+| `POST /balance/refund` | Reverse a deduct (operator/agent use) |
+| `GET /balance/transactions?buyer_id=` | Ledger history, newest first |
+
+> ⚠️ **Protect these endpoints** (reverse-proxy auth / IP allowlist). In particular, the `alipay` top-up path is operator-trusted in this MVP: Alipay AI-Pay verification requires the buyer-side `payment_proof`, so the server credits a reported `trade_no` without gateway verification. The `crypto` path verifies the `tx_hash` on-chain (receipt + transfer to the provider wallet + amount) and the `wechat` path queries the order for `SUCCESS`; all three are idempotent on the external reference.
+
+### How It Works
+
+1. An unpaid request to `/execute` returns **402** with a `balance` entry in `accepts[]` (pure — nothing is minted).
+2. The client re-requests with an `X-Payment` payload carrying `{ buyer_id, request_id }`, where `request_id` is a fresh client-generated UUID.
+3. The server **deducts atomically first** (idempotent on `request_id`), then runs the skill, and refunds automatically if the skill fails. This is the inverse of the QR rails (verify paid → run → confirm).
+4. The response carries the ledger transaction id in `X-Payment-Response`.
+
+### Buyer Usage
+
+```bash
+# One-time: persist your buyer id (account label). Under auth_mode=enforce, spending also
+# requires the bound signing key — see "Balance Authentication" above.
+npx moltspay balance set-buyer my-buyer-id
+
+# Top up once, via any settled rail
+npx moltspay balance topup https://server.com 10.00 --rail crypto --tx-hash 0xabc... --chain base
+npx moltspay balance topup https://server.com 10.00 --rail wechat --out-trade-no MP1719...
+npx moltspay balance topup https://server.com 10.00 --rail alipay --trade-no 2026...
+
+# Then pay password-free — no wallet, no QR
+npx moltspay pay https://server.com my-service '{"prompt":"hello"}' --rail balance
+
+# Check balance and history
+npx moltspay balance query https://server.com
+npx moltspay balance transactions https://server.com
+```
+
+SDK equivalent:
+
+```ts
+import { MoltsPayClient } from 'moltspay/client';
+
+const client = new MoltsPayClient();
+client.setBuyerId('my-buyer-id'); // persisted in config.json
+
+await client.topupBalance('https://server.com', {
+  rail: 'crypto', amount: '10.00', txHash: '0xabc...', chain: 'base',
+});
+
+const result = await client.pay('https://server.com', 'my-service',
+  { prompt: 'hello' }, { rail: 'balance' });
+
+const info = await client.getBuyerBalance('https://server.com');
+console.log(info.balance, info.today_spent);
+```
+
 ## Live Example: Zen7 Video Generation
 
 Live service at `https://moltspay.com/a/zen7`
 
 **Services:**
 - `text-to-video` - $0.01 USDC - Generate video from text prompt
-- `image-to-video` - $0.01 USDC - Animate a static image
+- `image-to-video` - $1.49 USDC - Animate a static image
 
 **Supported Chains:** Base, Polygon, Solana, BNB, Tempo (mainnet & testnet)