@aeon-ai-pay/aigateway 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.5] — 2026-05-19
+
+### Changed
+- **Removed all Chinese-language content from source files**. All comments,
+  docstrings, log messages, and SKILL.md guidance are now English-only.
+  `normalizeWalletError` no longer matches CJK error strings from localised
+  wallet apps; those fall through to the generic `WALLET_ERROR` code.
+- SKILL.md's "Wording Discipline" section is now language-neutral: instead
+  of listing Chinese phrasings, it instructs translators to keep the "wallet
+  top-up" verb / noun lexically distinct from the "card face value" verb /
+  noun in every target language.
+
+### Removed
+- `test/create-logic.test.mjs` — stale unit tests inherited from `aicard`
+  that referenced internal functions removed during the merge (e.g.
+  `inlineWalletConnectTopup`, now replaced by `funding.mjs::fundSessionKey`).
+  The file was never published to npm (`test/` is not in `files`).
+
 ## [0.1.4] — 2026-05-19
 
 ### Added
@@ -44,14 +62,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 ## [0.1.2] — 2026-05-19
 
 ### Changed
-- **SKILL.md wording discipline**: `wallet-topup` ask and `create-card` ask now have
-  enforced lexical separation. Step 2 (`wallet-topup`) explicitly says "load USDT
-  **into your session wallet**" / "往**本地钱包**充值 USDT". Step 3a (`create-card`)
-  says "card **face value**" / "**开多少美元的卡** / 卡的面额", and explicitly
-  forbids translating it as "充值". Fixes a UX confusion where a user with a
-  funded wallet would be asked "请问您想充值多少美元到虚拟卡上?" and reasonably
-  wonder if it was another wallet top-up prompt.
-- New "Wording Discipline" section in SKILL.md `## Copy Constraints` to lock this in.
+- **SKILL.md wording discipline**: the `wallet-topup` and `create-card` prompts
+  now enforce strict lexical separation. Step 2 (`wallet-topup`) says "load USDT
+  **into your session wallet**"; Step 3a (`create-card`) says "card
+  **face value**" / "issue a card with how much". When translating to any
+  non-English language, the verb / noun for each concept must remain distinct
+  so users cannot conflate them.
+- New "Wording Discipline" section in SKILL.md `## Copy Constraints` to lock
+  this in.
 
 ## [0.1.1] — 2026-05-19
 

package/bin/cli.mjs

@@ -7,8 +7,9 @@ if (major < 25) {
   process.exit(1);
 }
 
-// WalletConnect v2 SDK 已知缺陷：relay 偶发 null WebSocket 帧导致
-// isJsonRpcPayload 内部 'id' in null 抛 TypeError，不影响业务流程，静默忽略
+// Known WalletConnect v2 SDK quirk: the relay occasionally emits null WebSocket frames,
+// causing `'id' in null` inside isJsonRpcPayload to throw a TypeError. It does not
+// affect business logic, so silently ignore it.
 process.on("uncaughtException", (err) => {
   if (
     err instanceof TypeError &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeon-ai-pay/aigateway",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "AI Agents discover, invoke, and settle paid LLMs, APIs, and Skills — starting with Skill Boss. No manual key setup. No prepayment. Pay-per-call via x402 or Agent Card.",
   "type": "module",
   "bin": {

package/scripts/postinstall.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * npm install -g 后自动安装 skill 到所有已检测的 AI 编码工具
+ * After `npm install -g`, automatically install the skill into every detected AI coding tool.
  *
- * 优先使用 `npx skills add` (Vercel Labs) 统一安装到所有工具
- * 失败时 fallback 到手动复制 Claude Code skills 目录
+ * Prefer `npx skills add` (Vercel Labs) so the skill is registered across all tools at once.
+ * If that fails, fall back to manually copying the skill into the Claude Code skills directory.
  */
 
 import { cpSync, existsSync, mkdirSync } from 'node:fs';
@@ -20,7 +20,7 @@ if (!existsSync(skillSrc)) {
   process.exit(0);
 }
 
-// 尝试用 skills CLI 安装到所有工具
+// Try installing into every tool via the skills CLI
 try {
   execFileSync('npx', ['skills', 'add', skillSrc, '-g', '-y', '--copy'], {
     stdio: 'inherit',
@@ -30,10 +30,10 @@ try {
   console.log('✔ aigateway skill installed via skills CLI (all detected tools)');
   process.exit(0);
 } catch {
-  // skills CLI 不可用或失败，fallback
+  // skills CLI unavailable or failed — fall back
 }
 
-// Fallback: 手动复制到 Claude Code
+// Fallback: copy manually into Claude Code
 const dest = join(homedir(), '.claude', 'skills', 'aigateway');
 mkdirSync(dirname(dest), { recursive: true });
 cpSync(skillSrc, dest, { recursive: true, force: true });

package/skills/aigateway/SKILL.md

@@ -16,7 +16,7 @@ description: >
 emoji: "🛰️"
 homepage: https://github.com/AEON-Project/aigateway
 metadata:
-  version: "0.1.4"
+  version: "0.1.5"
   author: AEON-Project
   openclaw:
     requires:
@@ -163,12 +163,10 @@ Trigger: `wallet-init` envelope reports `needsTopup: true` (any of `no_prior_fun
 This is a **session-wallet top-up** in USDT (NOT card face value). Make the wording unambiguously about the wallet to avoid the user confusing it with the card face value asked in Step 3a.
 
 - Presets: **5 / 10 / 20 / 50 USDT**. Custom amounts must be ≥ 5 USDT.
-- Ask the user **before** running the command. **Make "wallet" / "钱包" explicit in the question:**
+- Ask the user **before** running the command. **Make the noun "wallet" explicit in the question** (when translating to other languages, the translated noun must also unambiguously mean *session wallet*, never *card*):
 
   > How much USDT would you like to load **into your session wallet**? (presets: 5 / 10 / 20 / 50, or any custom amount ≥ 5)
 
-  (Suggested Chinese phrasing: "请问要往**本地钱包**充值多少 USDT？预设 5 / 10 / 20 / 50，或自定义 ≥ 5。")
-
 - Once the user picks an amount, run:
 
 ```bash
@@ -211,13 +209,10 @@ Trigger: user wants to **buy / create / get a virtual card** *and* Step 1 envelo
 
 ### Amount confirmation
 
-This is the **card face value** the user wants to issue (NOT a wallet top-up). Amount must be in `amountLimits.min ~ amountLimits.max` (from Step 1; never hardcode). If user did not specify, ask once — **use the word "card face value" / "面额", never "充值" / "top up"** to avoid confusing it with the `wallet-topup` step:
+This is the **card face value** the user wants to issue (NOT a wallet top-up). Amount must be in `amountLimits.min ~ amountLimits.max` (from Step 1; never hardcode). If the user did not specify a value, ask once — use the phrase **"card face value"** (or in any non-English language, the equivalent for *the amount loaded onto a new card*), never the verb used for *wallet top-up*:
 
 > What card face value would you like to issue? Allowed range: ${min}~${max} USD.
 
-(Suggested Chinese phrasing: "请问要开多少美元的卡？允许范围 $${min} ~ $${max}。"
-**Do not** translate this as "充值多少美元" — that wording belongs to `wallet-topup` and confuses users.)
-
 Once specified, **execute immediately**.
 
 ### Execute
@@ -460,11 +455,11 @@ Address rendering: always `0x0...{last4}` (first 3 + ellipsis + last 4 chars).
 
 ### Wording Discipline: "wallet top-up" vs "card face value"
 
-These two amounts are **different concepts** asked at **different steps**. Translators must keep them lexically distinct so users don't conflate them:
+These two amounts are **different concepts** asked at **different steps**. Translators (to any non-English language) must keep them **lexically distinct** so users do not conflate them:
 
-| Step | Concept | Required wording (English) | Suggested Chinese | Forbidden mix-ups |
-| --- | --- | --- | --- | --- |
-| Step 2 (`wallet-topup`) | USDT into the **session wallet** | "load USDT **into your session wallet**" | "往**本地钱包**充值 USDT" | Don't say "充值到卡里" / "load onto the card" — that's Step 3a |
-| Step 3a (`create-card`) | USD **face value** loaded onto a new card | "card **face value**" / "issue a card with how much" | "**开多少美元的卡** / 卡的面额" | Don't say "充值多少" / "充值到卡" without strong "card" qualifier — confuses with Step 2 |
+| Step | Concept | Required English wording | Forbidden mix-ups |
+| --- | --- | --- | --- |
+| Step 2 (`wallet-topup`) | USDT into the **session wallet** | "load USDT **into your session wallet**" | Never say "load onto the card" — that's Step 3a |
+| Step 3a (`create-card`) | USD **face value** loaded onto a new card | "card **face value**" / "issue a card with how much" | Never use the same verb you used for *wallet top-up* without a strong "card" qualifier |
 
-**Rule of thumb**: if the agent's question contains the word "充值" (top up), the noun *must* be "钱包" (wallet); if the question is about a card's amount, prefer "**面额**" or "**开多少美元的卡**", never "充值".
+**Rule of thumb**: if a question is about the *wallet* (Step 2), the target noun must mean *session wallet*. If a question is about a *card amount* (Step 3a), prefer wording that means *face value* / *the amount loaded onto a new card*. The verb for one concept must never be reused for the other concept in the same language.

package/src/balance.mjs

@@ -1,5 +1,5 @@
 /**
- * 钱包余额查询（共享模块）
+ * Wallet balance lookup (shared module)
  */
 import { privateKeyToAccount } from "viem/accounts";
 import { createPublicClient, http, formatUnits } from "viem";
@@ -42,8 +42,8 @@ function getClient() {
 }
 
 /**
- * 通过地址查询 BNB 和 USDT 余额（不需要私钥）
- * @param {string} address - EVM 地址
+ * Query BNB and USDT balance by address (no private key required).
+ * @param {string} address - EVM address
  */
 export async function getBalanceByAddress(address) {
   const client = getClient();
@@ -68,7 +68,7 @@ export async function getBalanceByAddress(address) {
 }
 
 /**
- * 通过私钥查询钱包 BNB 和 USDT 余额
+ * Query a wallet's BNB and USDT balance by private key.
  * @param {string} privateKey
  */
 export async function getWalletBalance(privateKey) {
@@ -77,9 +77,9 @@ export async function getWalletBalance(privateKey) {
 }
 
 /**
- * 查询 session key 对 facilitator 的 USDT allowance
- * @param {string} ownerAddress - session key 地址
- * @returns {bigint} 当前 allowance（wei）
+ * Query the session key's USDT allowance for the facilitator.
+ * @param {string} ownerAddress - session key address
+ * @returns {bigint} current allowance (in wei)
  */
 export async function getAllowance(ownerAddress) {
   const client = getClient();

package/src/commands/clean.mjs

@@ -8,7 +8,7 @@ export async function clean() {
   const home = homedir();
   const removed = [];
 
-  // 1. 用 skills CLI 移除（覆盖所有工具）
+  // 1. Remove via the skills CLI (covers every tool)
   try {
     execFileSync("npx", ["skills", "remove", "aigateway", "-g", "-y"], {
       stdio: "inherit",
@@ -17,7 +17,7 @@ export async function clean() {
     logInfo("Removed aigateway skill via skills CLI");
     removed.push("skills");
   } catch {
-    // skills CLI 不可用，手动清理 Claude Code
+    // skills CLI unavailable — clean Claude Code manually
     const skillDir = join(home, ".claude", "skills", "aigateway");
     if (existsSync(skillDir)) {
       rmSync(skillDir, { recursive: true, force: true });
@@ -26,7 +26,7 @@ export async function clean() {
     }
   }
 
-  // 2. 卸载全局包
+  // 2. Uninstall the global package
   try {
     execFileSync("npm", ["uninstall", "-g", "@aeon-ai-pay/aigateway"], {
       stdio: "inherit",
@@ -38,7 +38,7 @@ export async function clean() {
     logInfo("Global package not installed, skipping uninstall");
   }
 
-  // 3. 清理 npm 缓存
+  // 3. Clean npm cache
   try {
     execFileSync("npm", ["cache", "clean", "--force"], {
       stdio: "inherit",
@@ -50,7 +50,7 @@ export async function clean() {
     logError("Failed to clean npm cache, skipping");
   }
 
-  // 4. 清理 npx 缓存
+  // 4. Clean npx cache
   const npxCache = join(home, ".npm", "_npx");
   if (existsSync(npxCache)) {
     rmSync(npxCache, { recursive: true, force: true });

package/src/commands/create-card.mjs

@@ -1,10 +1,10 @@
 /**
- * create-card：通过 x402 协议在 BSC 上用 USDT 支付，发一张一次性虚拟卡
+ * create-card: issue a one-time virtual card by paying with USDT on BSC over the x402 protocol.
  *
- * 服务端路径：GET {serviceUrl}/open/ai/x402/card/create?amount=<usd>&appId=<merchant>
- * 流程：fetch payment requirements → balance + allowance 检查
- *      → （余额不足时）走 funding.mjs/fundSessionKey 充值
- *      → x402 EIP-712 签名提交 → 可选轮询 status
+ * Server endpoint: GET {serviceUrl}/open/ai/x402/card/create?amount=<usd>&appId=<merchant>
+ * Flow: fetch payment requirements -> check balance + allowance
+ *       -> (if balance is insufficient) top up via funding.mjs/fundSessionKey
+ *       -> submit x402 EIP-712 signature -> optionally poll status
  */
 import { createX402Api, decodePaymentResponse, fetchPaymentRequirements } from "../x402.mjs";
 import { resolve } from "../config.mjs";
@@ -163,7 +163,7 @@ export async function createCard(opts) {
     return;
   }
 
-  // Dry-run：跑完前置检查就退出
+  // Dry-run: exit after preflight checks complete
   if (dryRun) {
     const preview = {
       dryRun: true,
@@ -191,7 +191,7 @@ export async function createCard(opts) {
     return;
   }
 
-  // WalletConnect 充值
+  // WalletConnect top-up
   if (needTopup || needGas) {
     logInfo("Funding flow triggered...");
     try {

package/src/commands/create-image.mjs

@@ -1,10 +1,10 @@
 /**
- * create-image：通过 x402 调用 Skill Boss 生成 AI 图像
+ * create-image: generate an AI image via Skill Boss using the x402 protocol.
  *
- * 服务端路径：GET {serviceUrl}/open/ai/x402/skillBoss/create?body=<urlencoded-json>&appId=<merchant>
- * 流程：fetch payment requirements → balance + allowance 检查
- *      → （余额不足时）走 funding.mjs/fundSessionKey 充值
- *      → x402 EIP-712 签名提交 → 下载图片到本地
+ * Server endpoint: GET {serviceUrl}/open/ai/x402/skillBoss/create?body=<urlencoded-json>&appId=<merchant>
+ * Flow: fetch payment requirements -> check balance + allowance
+ *       -> (if balance is insufficient) top up via funding.mjs/fundSessionKey
+ *       -> submit x402 EIP-712 signature -> download the image locally
  */
 import { createX402Api, decodePaymentResponse, fetchPaymentRequirements } from "../x402.mjs";
 import { resolve } from "../config.mjs";

package/src/commands/wallet-gas.mjs

@@ -1,5 +1,6 @@
 /**
- * gas 命令：通过 WalletConnect 从主钱包向本地钱包转 BNB（withdraw 时支付 gas）
+ * gas command: transfer BNB from the main wallet to the local wallet via WalletConnect
+ * (used to pay gas during withdraw).
  */
 import { loadConfig } from "../config.mjs";
 import { getBalanceByAddress } from "../balance.mjs";

package/src/commands/wallet-init.mjs

@@ -1,16 +1,16 @@
 /**
- * wallet-init：本地 session 钱包 check / 创建 + 链上状态评估
+ * wallet-init: check / create the local session wallet and assess its on-chain status.
  *
- * 步骤：
- *   1. 若 ~/.aigateway/config.json 缺 privateKey → 用 viem.generatePrivateKey() 生成
- *   2. 查 USDT / BNB 余额（除非刚 created，则跳过查询直接判定为 needsTopup）
- *   3. 查 facilitator allowance（同上规则）
- *   4. 综合判定 needsTopup 与原因，返回完整就绪状态供 agent 决策
+ * Steps:
+ *   1. If ~/.aigateway/config.json has no privateKey → generate one with viem.generatePrivateKey().
+ *   2. Query USDT / BNB balance (skipped when the wallet was just created — it must be empty).
+ *   3. Query the facilitator allowance (same rule).
+ *   4. Decide needsTopup with the reason and return the full readiness state for the agent to act on.
  *
- * 设计意图：agent 跑完 wallet-init 一条命令就拿到决策依据：
- *   - data.ready=true 表示钱包私钥可用
- *   - data.needsTopup=true → 必须先 wallet-topup（envelope 里附带 presets / minTopup / reason）
- *   - data.needsTopup=false → 可直接 create-card / create-image
+ * Design intent: with a single wallet-init call, the agent gets every decision input it needs:
+ *   - data.ready=true → the session private key is usable
+ *   - data.needsTopup=true → wallet-topup must run first (the envelope includes presets / minTopup / reason)
+ *   - data.needsTopup=false → can proceed directly to create-card / create-image
  */
 import { loadConfig, saveConfig } from "../config.mjs";
 import { MIN_AMOUNT, MAX_AMOUNT } from "../constants.mjs";
@@ -41,7 +41,7 @@ export async function initWallet(opts) {
     logInfo(`Wallet: ${config.address}`);
   }
 
-  // 链上状态评估
+  // On-chain status check
   let usdt = "0";
   let bnb = "0";
   let usdtNum = 0;
@@ -50,7 +50,7 @@ export async function initWallet(opts) {
   let chainCheckError = null;
 
   if (created) {
-    // 刚建好的钱包余额必然为 0，跳过链上查询节省 ~500ms
+    // A freshly created wallet is guaranteed to be empty; skip the chain query to save ~500ms.
     logInfo("Fresh wallet — skipping balance lookup (assumed empty).");
   } else {
     try {
@@ -68,18 +68,19 @@ export async function initWallet(opts) {
     }
   }
 
-  // 决策：是否需要 topup —— 只看链上真实状态，不依赖 config.mainWallet 字段。
-  // 之前用 !config.mainWallet 当判断条件是错的：mainWallet 只是 withdraw 默认目标地址，
-  // 即使为 null（如用户外部转账 / 旧版本未记录），只要链上 USDT/allowance 充足就应该
-  // 直接允许付费调用，不要强制再走一次 wallet-topup。
+  // Decision: needsTopup. Use only real on-chain state — do NOT depend on config.mainWallet.
+  // The previous logic `created || !config.mainWallet` was wrong: mainWallet is purely the default
+  // destination for withdraw. If USDT / allowance on-chain are sufficient — even when mainWallet
+  // is null (external CEX deposit / older versions that didn't record it) — paid calls should be
+  // allowed without forcing another wallet-topup round.
   let needsTopup = false;
   let topupReason = null;
   if (created) {
-    // 刚生成的 session key 必然没钱，无需查链
+    // A freshly generated session key has no funds — no point querying the chain.
     needsTopup = true;
     topupReason = "first_time";
   } else if (!chainCheckOk) {
-    // 链上查询失败 —— 保守标记需要 topup 由用户决定下一步
+    // Chain probe failed — conservatively flag needsTopup so the user can decide what to do.
     needsTopup = true;
     topupReason = "chain_check_failed";
   } else if (usdtNum < LOW_BALANCE_THRESHOLD) {
@@ -102,7 +103,7 @@ export async function initWallet(opts) {
     bnb,
     allowance: allowance.toString(),
     needsTopup,
-    topupReason,            // "no_prior_funding" | "low_balance" | "no_approve" | null
+    topupReason,            // "first_time" | "low_balance" | "no_approve" | "chain_check_failed" | null
     minTopup: MIN_TOPUP_USDT,
     presets: TOPUP_PRESETS,
     amountLimits: { min: MIN_AMOUNT, max: MAX_AMOUNT },

package/src/commands/wallet-topup.mjs

@@ -1,15 +1,15 @@
 /**
- * topup：充值 + 一次性 approve facilitator
+ * wallet-topup: top up the session wallet and run the one-time facilitator approve.
  *
- * 流程：
- *   1. 校验 session key 已存在（来自 aigateway wallet-init）
- *   2. 检查 USDT 余额 + facilitator allowance
- *   3. 如果 USDT < LOW_BALANCE_THRESHOLD（1 USDT）或 allowance == 0，触发 WalletConnect 充值
- *      - 充值 amount: TTY 模式交互选择 presets [5, 10, 20, 50] 或自定义；
- *                    非 TTY 模式需要传 --amount <usdt>，否则报 TOPUP_REQUIRED
- *      - 同时按需转 0.0003 BNB 用作 approve gas
- *   4. session key 自己广播 ERC20.approve(facilitator, MaxUint256)
- *   5. 重新查余额 / allowance，返回最终状态
+ * Flow:
+ *   1. Verify the session key exists (created earlier by `aigateway wallet-init`).
+ *   2. Check USDT balance + facilitator allowance.
+ *   3. If USDT < LOW_BALANCE_THRESHOLD (1 USDT) or allowance == 0, open WalletConnect to fund:
+ *      - Top-up amount: TTY mode picks interactively from presets [5, 10, 20, 50] or a custom value;
+ *                       non-TTY mode requires `--amount <usdt>`, otherwise TOPUP_REQUIRED is emitted.
+ *      - 0.0003 BNB is transferred too when an approve transaction is needed.
+ *   4. The session key broadcasts ERC20.approve(facilitator, MaxUint256) once.
+ *   5. Re-query balance / allowance and return the final state.
  */
 import { resolve } from "../config.mjs";
 import { getWalletBalance, getAllowance } from "../balance.mjs";
@@ -71,7 +71,7 @@ export async function topup(opts) {
   const needApprove = allowance === 0n;
   const needGas = needApprove && bnbRaw === 0n;
 
-  // 已就绪：余额够 + 已 approve
+  // Already prepared: balance is sufficient and facilitator is approved
   if (!needTopup && !needApprove) {
     logInfo("Wallet already prepared (balance ≥ minimum, facilitator approved).");
     const data = {
@@ -89,7 +89,7 @@ export async function topup(opts) {
     return;
   }
 
-  // 决定充值金额
+  // Decide the top-up amount
   let topupAmount = null;
   if (needTopup) {
     if (balanceLow) {
@@ -134,7 +134,7 @@ export async function topup(opts) {
     }
   }
 
-  // WalletConnect 充值（USDT + 按需 BNB gas）
+  // WalletConnect top-up (USDT + optional BNB for approve gas)
   if (needTopup || needGas) {
     const willTransfer = [];
     if (needTopup) willTransfer.push(`${topupAmount} USDT`);
@@ -161,7 +161,7 @@ export async function topup(opts) {
     }
   }
 
-  // session key 一次性 approve facilitator
+  // Session key broadcasts the one-time facilitator approve
   let approveTx = null;
   if (needApprove) {
     let postBnbRaw = bnbRaw;
@@ -193,7 +193,7 @@ export async function topup(opts) {
     }
   }
 
-  // 最终查余额 + allowance
+  // Final balance + allowance re-check
   let finalUsdt = usdt;
   let finalBnb = bnb;
   let finalAllowance = allowance;

package/src/commands/wallet-withdraw.mjs

@@ -1,5 +1,5 @@
 /**
- * withdraw 命令：将 session key 中的资金转回主钱包（USDT + BNB）
+ * wallet-withdraw: move the session key's funds (USDT + BNB) back to the main wallet.
  */
 import { createPublicClient, createWalletClient, http, parseUnits, formatUnits, encodeFunctionData } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
@@ -54,7 +54,7 @@ export async function withdraw(opts) {
 
   const isWithdrawAll = !opts.amount;
 
-  // 无任何资金
+  // No funds at all
   if (balance.usdtRaw === 0n && balance.bnbRaw === 0n) {
     emitErr("wallet-withdraw", "NO_FUNDS", { message: "No funds to withdraw.", appId });
     return;
@@ -63,9 +63,9 @@ export async function withdraw(opts) {
   let usdtTxHash = null;
   let bnbTxHash = null;
 
-  // 1. 赎回 USDT（有 USDT 才执行）
+  // 1. Reclaim USDT (only when USDT balance > 0)
   if (balance.usdtRaw > 0n) {
-    // USDT 转账需要 BNB 作 gas
+    // USDT transfer needs BNB for gas
     if (balance.bnbRaw === 0n) {
       emitErr("wallet-withdraw", "INSUFFICIENT_BNB", {
         message: "No BNB for gas. Withdraw is a normal on-chain transfer and requires BNB to pay gas.",
@@ -119,7 +119,7 @@ export async function withdraw(opts) {
     }
   }
 
-  // 2. 赎回剩余 BNB（仅赎回全部时）
+  // 2. Reclaim remaining BNB (only when withdrawing everything)
   if (isWithdrawAll) {
     const freshBalance = balance.usdtRaw > 0n
       ? await getBalanceByAddress(sessionAddress)
@@ -128,7 +128,7 @@ export async function withdraw(opts) {
     if (freshBalance.bnbRaw > 0n) {
       try {
         const gasPrice = await publicClient.getGasPrice();
-        // 预留 20% buffer 应对 gas price 波动
+        // Reserve a 20% buffer to absorb gas-price fluctuations
         const gasCost = BNB_TRANSFER_GAS * (gasPrice * 120n / 100n);
         const sendable = freshBalance.bnbRaw - gasCost;
 
@@ -159,7 +159,7 @@ export async function withdraw(opts) {
     }
   }
 
-  // 查询最终余额
+  // Final balance lookup
   let finalBalance;
   try {
     finalBalance = await getBalanceByAddress(sessionAddress);

package/src/config.mjs

@@ -1,9 +1,10 @@
 /**
- * 配置管理：~/.aigateway/config.json
- * 优先级：CLI 参数 > 环境变量 > config.json
+ * Config management: ~/.aigateway/config.json
+ * Resolution priority: CLI args > env vars > config.json
  *
- * AEON AI Gateway 统一使用同一个 x402 服务端（ai-api.aeon.xyz），
- * 不同能力（虚拟卡 / Skill Boss 调用）走不同的路径前缀。
+ * AEON AI Gateway uses a single x402 service (ai-api.aeon.xyz);
+ * different capabilities (virtual card / Skill Boss calls) share the host
+ * but use distinct path prefixes.
  */
 import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
 import { join } from "path";
@@ -31,7 +32,7 @@ export function saveConfig(config) {
 }
 
 /**
- * 解析配置值，优先级：cliValue > envKey > config[configKey]
+ * Resolve a value with priority: cliValue > envKey > config[configKey]
  */
 export function resolve(cliValue, envKey, configKey) {
   if (cliValue) return cliValue;

package/src/error-codes.mjs

@@ -1,16 +1,16 @@
 /**
- * 错误码常量表 —— CLI 与文档的单一事实源
+ * Error-code registry — single source of truth shared by the CLI and the docs.
  *
- * 退出码语义：
- *   0 成功
- *   1 用户错误（参数、余额、配置、用户拒绝）
- *   2 超时（轮询、WalletConnect、签名、链上）
- *   3 服务端 / 网络
- *   4 内部错误
+ * Exit-code semantics:
+ *   0  success
+ *   1  user error (bad argument, insufficient balance, configuration, user reject)
+ *   2  timeout (polling, WalletConnect, signature, on-chain wait)
+ *   3  service / network
+ *   4  internal error
  */
 
 export const ERROR_CODES = {
-  // ===== 用户错误（exit 1）=====
+  // ===== User error (exit 1) =====
   WALLET_NOT_CONFIGURED:  { exit: 1, message: "Wallet not configured. Run: aigateway wallet-init" },
   SERVICE_URL_MISSING:    { exit: 1, message: "Service URL not configured." },
   AMOUNT_INVALID:         { exit: 1, message: "Invalid amount." },
@@ -25,13 +25,13 @@ export const ERROR_CODES = {
   TOPUP_AMOUNT_TOO_SMALL: { exit: 1, message: "Top-up amount is below the minimum." },
   PAYMENT_REJECTED:       { exit: 1, message: "Payment approval was rejected. Please try again if you'd like to proceed." },
 
-  // ===== 超时（exit 2）=====
+  // ===== Timeout (exit 2) =====
   PAYMENT_TIMEOUT:        { exit: 2, message: "Payment approval timed out. Please try again." },
   WC_SESSION_EXPIRED:     { exit: 2, message: "WalletConnect session expired." },
   POLL_TIMEOUT:           { exit: 2, message: "Polling timed out. Card may still be provisioning." },
   TX_TIMEOUT:             { exit: 2, message: "On-chain transaction timed out." },
 
-  // ===== 服务/网络（exit 3）=====
+  // ===== Service / network (exit 3) =====
   SERVICE_UNAVAILABLE:    { exit: 3, message: "Service unavailable or network error." },
   PAYMENT_FETCH_FAILED:   { exit: 3, message: "Failed to fetch payment requirements." },
   BALANCE_CHECK_FAILED:   { exit: 3, message: "Failed to check balance." },
@@ -44,7 +44,7 @@ export const ERROR_CODES = {
   IMAGE_DOWNLOAD_FAILED:  { exit: 3, message: "Image download failed." },
   FUNDING_FAILED:         { exit: 3, message: "Funding flow failed." },
 
-  // ===== 内部（exit 4）=====
+  // ===== Internal (exit 4) =====
   INTERNAL_ERROR:         { exit: 4, message: "Internal error." },
   WALLET_ERROR:           { exit: 1, message: "Wallet operation failed." },
 };

package/src/output.mjs

@@ -1,12 +1,13 @@
 /**
- * 统一输出封装：envelope JSON + 分级日志
+ * Unified output envelope: JSON on stdout + tiered stderr logs.
  *
- * stdout: 一行最终 JSON（machine-readable）
- *   - 成功：{ ok: true, command, version, data }
- *   - 失败：{ ok: false, command, version, error: { code, message, ...context } }
- * stderr: 进度日志（human-readable，agent 可忽略）
+ * stdout: a single line of final JSON (machine-readable)
+ *   - success: { ok: true, command, version, data }
+ *   - failure: { ok: false, command, version, error: { code, message, ...context } }
+ * stderr: progress logs (human-readable; agents can ignore them)
  *
- * --legacy-output 模式：保留旧裸字段格式，便于已按旧 JSON 解析的脚本/agent 平滑过渡。
+ * --legacy-output mode: emit the pre-envelope shape so scripts / agents that
+ * already parse the old JSON can migrate gradually.
  */
 
 import { readFileSync } from "fs";
@@ -30,10 +31,11 @@ export function isLegacyMode() { return LEGACY_MODE; }
 export function isVerboseMode() { return VERBOSE_MODE; }
 
 /**
- * 输出成功结果。调用方应在调用后让函数自然返回（不要再 process.exit）。
- * @param {string} command - 命令名，如 "create-card" / "wallet-init"
- * @param {object} data - envelope 模式下放在 data 字段
- * @param {object} [legacyShape] - legacy 模式下直接输出的旧格式对象；省略则使用 data 本身
+ * Emit a success result. Callers should let the function return naturally
+ * (do not call process.exit afterwards).
+ * @param {string} command - command name, e.g. "create-card" / "wallet-init"
+ * @param {object} data - placed under envelope.data
+ * @param {object} [legacyShape] - the legacy-mode payload; if omitted, `data` is used
  */
 export function emitOk(command, data, legacyShape) {
   if (LEGACY_MODE) {
@@ -44,10 +46,11 @@ export function emitOk(command, data, legacyShape) {
 }
 
 /**
- * 输出错误并退出（按错误码对应的 exit 码）。
+ * Emit an error and exit with the corresponding exit code.
  * @param {string} command
- * @param {string} code - ERROR_CODES 键名
- * @param {object} [details] - 额外字段。message 字段会覆盖默认 message；legacy 字段在 legacy 模式下完全替代输出
+ * @param {string} code - key of ERROR_CODES
+ * @param {object} [details] - extra fields. `message` overrides the default message;
+ *   `legacy` fully replaces the output in legacy mode.
  */
 export function emitErr(command, code, details = {}) {
   const info = ERROR_CODES[code] || ERROR_CODES.INTERNAL_ERROR;
@@ -69,17 +72,17 @@ export function emitErr(command, code, details = {}) {
   process.exit(exit);
 }
 
-/** 进度日志（quiet 模式压制） */
+/** Progress log (suppressed in quiet mode) */
 export function logInfo(msg) {
   if (!QUIET_MODE) console.error(msg);
 }
 
-/** 详细日志（仅 verbose 模式下输出） */
+/** Verbose log (only emitted in verbose mode) */
 export function logVerbose(msg) {
   if (VERBOSE_MODE && !QUIET_MODE) console.error(msg);
 }
 
-/** 错误日志（quiet 模式下也会输出） */
+/** Error log (still emitted in quiet mode) */
 export function logError(msg) {
   console.error(msg);
 }

package/src/sanitize.mjs

@@ -1,14 +1,14 @@
 /**
- * 卡片输出脱敏：隐藏敏感卡片信息（完整卡号→末4位、移除CVV、移除有效期）
- * CLI 输出 JSON 供 Agent 解析，Agent 按产品模板展示给用户
+ * Card output sanitisation: redact sensitive card data (truncate the full PAN to its last 4 digits, drop CVV, drop expiry).
+ * The CLI emits JSON for an agent to parse; the agent then renders the product-specific template to the user.
  */
 
-// 需要替换为末4位的字段
+// Fields whose value should be replaced with the last-4 representation
 const CARD_NUMBER_KEYS = new Set([
   "cardnumber", "cardno",
 ]);
 
-// 需要完全移除的字段
+// Fields that must be removed entirely
 const REMOVE_KEYS = new Set([
   "cvv", "cvv2", "cvc", "cvc2", "securitycode",
   "expiry", "expirydate", "expiredate", "cardexpiry",
@@ -16,10 +16,10 @@ const REMOVE_KEYS = new Set([
 ]);
 
 /**
- * 递归脱敏对象：
- * - cardNumber/cardNo → 只保留末4位（"•••• 3398"）
- * - cvv/securityCode → 移除
- * - expiry/expireDate → 移除
+ * Recursively sanitise an object:
+ *   - cardNumber / cardNo → keep only the last four digits ("•••• 3398")
+ *   - cvv / securityCode → drop
+ *   - expiry / expireDate → drop
  */
 export function sanitizeOutput(obj) {
   if (obj === null || obj === undefined) return obj;
@@ -30,15 +30,15 @@ export function sanitizeOutput(obj) {
   for (const [key, value] of Object.entries(obj)) {
     const normalized = key.toLowerCase().replace(/[-_]/g, "");
 
-    // 移除 CVV、有效期等敏感字段
+    // Drop sensitive fields (CVV, expiry, etc.)
     if (REMOVE_KEYS.has(normalized)) continue;
 
-    // 卡号只保留末4位
+    // Card number: only keep the last 4 digits
     if (CARD_NUMBER_KEYS.has(normalized)) {
       if (typeof value === "string" && value.length >= 4) {
         result[key] = "•••• " + value.slice(-4);
       }
-      // value 为 null 时不输出此字段
+      // when value is null, do not emit this field
       continue;
     }
 

package/src/update-check.mjs

@@ -1,11 +1,11 @@
 /**
- * 自动版本检查 + 静默后台升级
+ * Auto version check + silent background upgrade.
  *
- * 策略：
- * 1. 同步快速检查（npm view）— 发现新版本时输出提示
- * 2. spawn 后台子进程执行 npm install -g 升级
- * 3. 升级后执行 postinstall.mjs（skills CLI 安装到所有工具）
- * 不阻塞主进程
+ * Strategy:
+ * 1. Synchronously poll the npm registry (`npm view`) — print a notice when a newer version is found.
+ * 2. Spawn a detached background process to run `npm install -g`.
+ * 3. After install, run postinstall.mjs (which re-installs the skill into every detected tool via the skills CLI).
+ * Does not block the main process.
  */
 
 import { execFileSync, spawn } from "node:child_process";
@@ -13,11 +13,11 @@ import { execFileSync, spawn } from "node:child_process";
 const PKG_NAME = "@aeon-ai-pay/aigateway";
 
 /**
- * 启动时调用：同步检查版本 + 后台升级
+ * Called at CLI startup: synchronous version probe + detached upgrade.
  * @param {string} currentVersion
  */
 export function checkForUpdates(currentVersion) {
-  // 同步快速检查最新版本（超时短，不阻塞太久）
+  // Synchronous fast probe (short timeout so it does not block too long)
   let latest;
   try {
     latest = execFileSync("npm", ["view", PKG_NAME, "version"], {
@@ -25,15 +25,15 @@ export function checkForUpdates(currentVersion) {
       stdio: ["ignore", "pipe", "ignore"],
     }).toString().trim();
   } catch {
-    return; // 网络不可用，静默跳过
+    return; // network unavailable — silently skip
   }
 
   if (!latest || latest === currentVersion) return;
 
-  // 有新版本：输出提示
+  // A newer version exists — print a notice
   console.error(`[update] ${PKG_NAME} ${currentVersion} → ${latest}, upgrading in background...`);
 
-  // 后台执行升级（结果写入日志文件）
+  // Run the upgrade in a detached child, writing the result to a log file
   const script = `
     const { execFileSync } = require("child_process");
     const { join } = require("path");

package/src/walletconnect.mjs

@@ -1,6 +1,6 @@
 /**
- * WalletConnect v2 封装模块
- * 用于通过 WalletConnect 协议连接用户钱包并发起交易
+ * WalletConnect v2 wrapper.
+ * Connects to the user's wallet over WalletConnect and submits transactions.
  */
 import { SignClient } from "@walletconnect/sign-client";
 import { encodeFunctionData, parseUnits } from "viem";
@@ -13,8 +13,9 @@ import { WC_CONNECT_TIMEOUT_MS, ERC20_TRANSFER_ABI, DEFAULT_WC_PROJECT_ID } from
 import { loadConfig, saveConfig } from "./config.mjs";
 
 /**
- * WalletConnect 流程抛出的错误，携带稳定 error code（PAYMENT_TIMEOUT / PAYMENT_REJECTED / WALLET_ERROR）。
- * Commands 层捕获后通过 emitErr 输出，无需关心底层细节。
+ * Error type thrown by the WalletConnect flow, carrying a stable error code
+ * (PAYMENT_TIMEOUT / PAYMENT_REJECTED / WALLET_ERROR). The Commands layer
+ * catches it and forwards it via emitErr; no caller needs to look at the underlying details.
  */
 export class WalletConnectError extends Error {
   constructor(code, message) {
@@ -24,7 +25,7 @@ export class WalletConnectError extends Error {
   }
 }
 
-// ============== 状态同步服务器（供浏览器页面轮询） ==============
+// ============== Status server (polled by the browser-side QR page) ==============
 
 let _status = { state: "waiting_scan" };
 let _server = null;
@@ -65,14 +66,14 @@ export function stopStatusServer() {
 
 const BSC_CHAIN_ID = "eip155:56";
 
-// QR 页面倒计时（与 WalletConnect 连接超时一致）
+// QR-page countdown (matches the WalletConnect connection timeout)
 const QR_EXPIRE_MS = 5 * 60 * 1000;
 
 /**
- * 生成 QR 码 HTML 页面并在浏览器中打开（按 Figma Ai card v1.2 设计稿）
+ * Generate the QR-code HTML page and open it in a browser (follows the Figma "AI card v1.2" design).
  * @param {string} uri - WalletConnect URI
- * @param {number} statusPort - 状态服务端口
- * @param {string|null} amount - 用户需要支付的 USDT 数量（如 "0.66"）
+ * @param {number} statusPort - port of the local status server
+ * @param {string|null} amount - USDT amount the user has to pay (e.g. "0.66")
  */
 function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB Chain(BEP20) only", gasAmount = null) {
   const html = `<!DOCTYPE html>
@@ -165,16 +166,16 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
   const EXPIRE_MS = ${QR_EXPIRE_MS};
   const startTime = Date.now();
 
-  // 倒计时 SVG 图标（Figma 导出 1:63 clock 16x16）- 使用 currentColor 跟随 .timer 颜色
+  // Clock countdown icon (exported from Figma 1:63, 16x16) — uses currentColor to track `.timer` color
   const CLOCK_SVG = '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M14.667 8C14.667 11.68 11.68 14.667 8 14.667C4.32 14.667 1.334 11.68 1.334 8C1.334 4.32 4.32 1.333 8 1.333C11.68 1.333 14.667 4.32 14.667 8Z" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/><path d="M10.476 10.12L8.409 8.887C8.049 8.674 7.756 8.16 7.756 7.74V5.007" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>';
-  // 提示 info 图标（Figma 导出 1:43 Icon 20x20）
+  // Info / hint icon (exported from Figma 1:43, 20x20)
   const INFO_SVG = '<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path opacity="0.2" d="M10 18.333C14.6 18.333 18.331 14.602 18.331 10C18.331 5.397 14.6 1.666 10 1.666C5.395 1.666 1.664 5.397 1.664 10C1.664 14.602 5.395 18.333 10 18.333Z" fill="#737A86"/><path d="M10 13.333V10" stroke="#737A86" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/><path d="M10 6.666H10.008" stroke="#737A86" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>';
-  // Loading 旋转图标（Figma 导出 1:50 loading-02 24x24）
+  // Loading spinner icon (exported from Figma 1:50 loading-02, 24x24)
   const LOADING_SVG = '<svg class="loading-icon" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path opacity=".7" d="M4.922 5l2.828 2.828" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/><path opacity=".6" d="M6 12H2" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/><path opacity=".5" d="M4.922 19.078l2.828-2.828" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/><path opacity=".4" d="M12 18v4" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/><path opacity=".3" d="M19.078 19.078L16.25 16.25" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/><path opacity=".2" d="M22 12h-4" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/><path opacity=".1" d="M19.078 5L16.25 7.828" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/><path opacity=".8" d="M12 2v4" stroke="#191B1F" stroke-width="2.5" stroke-linecap="round"/></svg>';
-  // 成功勾选
+  // Success checkmark
   const CHECK_SVG = '<div class="check-icon"><svg viewBox="0 0 14 14" fill="none"><path d="M3 7l3 3 5-5" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg></div>';
 
-  // 超时插图 SVG（从 Figma 导出）
+  // "Expired" illustration SVG (exported from Figma)
   const EXPIRED_SVG = \`<svg width="144" height="129" viewBox="0 0 144 129" fill="none" xmlns="http://www.w3.org/2000/svg">
 <path opacity="0.1" d="M140.369 64.988C140.369 82.769 133.106 98.797 121.461 110.317C110.066 121.711 94.289 128.598 76.884 128.598C59.604 128.598 43.826 121.586 32.306 110.317C20.661 98.797 13.398 82.769 13.398 64.988C13.398 29.802 41.823 1.377 76.884 1.377C111.944 1.377 140.369 29.927 140.369 64.988Z" fill="#1A72F7"/>
 <path d="M134.859 23.291C137.695 23.291 139.993 20.992 139.993 18.157C139.993 15.321 137.695 13.023 134.859 13.023C132.024 13.023 129.725 15.321 129.725 18.157C129.725 20.992 132.024 23.291 134.859 23.291Z" fill="#E8F1FE"/>
@@ -194,7 +195,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
 <linearGradient id="pb2" x1="53.891" y1="104.557" x2="103.297" y2="105.207" gradientUnits="userSpaceOnUse"><stop stop-color="#DBDEE3" stop-opacity=".7"/><stop offset="1" stop-color="#DBDEE3"/></linearGradient>
 </defs></svg>\`;
 
-  // 拒绝插图 SVG（基于超时插图，替换时钟为 X 标记，橙色改红色）
+  // "Rejected" illustration SVG (variant of the expired illustration: clock swapped for an X, orange swapped for red)
   const REJECTED_SVG = \`<svg width="144" height="129" viewBox="0 0 144 129" fill="none" xmlns="http://www.w3.org/2000/svg">
 <path opacity="0.1" d="M140.369 64.988C140.369 82.769 133.106 98.797 121.461 110.317C110.066 121.711 94.289 128.598 76.884 128.598C59.604 128.598 43.826 121.586 32.306 110.317C20.661 98.797 13.398 82.769 13.398 64.988C13.398 29.802 41.823 1.377 76.884 1.377C111.944 1.377 140.369 29.927 140.369 64.988Z" fill="#1A72F7"/>
 <path d="M134.859 23.291C137.695 23.291 139.993 20.992 139.993 18.157C139.993 15.321 137.695 13.023 134.859 13.023C132.024 13.023 129.725 15.321 129.725 18.157C129.725 20.992 132.024 23.291 134.859 23.291Z" fill="#E8F1FE"/>
@@ -223,7 +224,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
 
   function fmtAmount(v) {
     if (v == null || v === '') return '';
-    // 完整显示原始金额（不做取整），去除末尾多余的 0，整数部分加千分位
+    // Render the full original amount (no rounding); trim trailing zeros and add thousands separators to the integer part
     const s = String(v);
     const neg = s.startsWith('-') ? '-' : '';
     const body = neg ? s.slice(1) : s;
@@ -233,7 +234,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
     return neg + intWithComma + (decPart ? '.' + decPart : '') + ' ' + TOKEN;
   }
 
-  // ====== 页面渲染函数 ======
+  // ====== Page rendering helpers ======
 
   function renderQR(data) {
     const remaining = Math.max(0, EXPIRE_MS - (Date.now() - startTime));
@@ -250,22 +251,22 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
 
     const expireMin = Math.ceil(remaining / 60000);
 
-    // QR wrap: 圆角矩形路径从12点（顶部中心）出发，顺时针绘制
-    // canvas 200 + padding 12*2 = 224, 圆角 r=16, 描边偏移1px
+    // QR wrap: rounded-rectangle path starts at 12 o'clock (top center) and goes clockwise.
+    // canvas 200 + padding 12*2 = 224, corner radius r=16, stroke offset 1px
     const S = 224, R = 16, cx = S/2;
-    // 从顶部中心开始，顺时针绘制一圈回到起点（开放路径，不用 Z 闭合，避免 dash 环绕）
+    // Start at top center, draw clockwise back to the start (open path, no Z — avoids the dash wrapping around)
     const qrPath = 'M' + cx + ',1 H' + (S-1-R) + ' A' + R + ',' + R + ' 0 0 1 ' + (S-1) + ',' + (1+R) +
       ' V' + (S-1-R) + ' A' + R + ',' + R + ' 0 0 1 ' + (S-1-R) + ',' + (S-1) +
       ' H' + (1+R) + ' A' + R + ',' + R + ' 0 0 1 1,' + (S-1-R) +
       ' V' + (1+R) + ' A' + R + ',' + R + ' 0 0 1 ' + (1+R) + ',1 H' + cx;
-    // 用 pathLength=1000 统一长度，避免手算偏差
+    // Use pathLength=1000 so the dash math is exact (no hand-calculated drift)
     const PL = 1000;
     const progress = remaining / EXPIRE_MS;
     const dashOffset = -PL * (1 - progress);
 
-    // USDT 图标 SVG（绿色圆形 Tether 标志）
+    // USDT icon SVG (green circle Tether glyph)
     const USDT_ICON = '<svg class="usdt-icon" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="9" cy="9" r="9" fill="#26A17B"/><path d="M10.1 9.6c-.06 0-.33.02-.73.02-.32 0-.58-.01-.67-.02-1.32-.06-2.3-.3-2.3-.58 0-.29.98-.52 2.3-.58v.93c.09.01.36.02.68.02.38 0 .66-.01.72-.02v-.93c1.31.06 2.29.3 2.29.58 0 .28-.98.52-2.29.58zm0-.87v-.83h2.05V6.5H5.88v1.4h2.05v.83c-1.48.07-2.6.38-2.6.75 0 .37 1.12.68 2.6.75v2.69h1.07v-2.69c1.48-.07 2.59-.38 2.59-.75 0-.37-1.11-.68-2.59-.75z" fill="#fff"/></svg>';
-    // BNB 图标 SVG（黄色圆形 BNB 标志）
+    // BNB icon SVG (yellow circle BNB glyph)
     const BNB_ICON = '<svg class="usdt-icon" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="9" cy="9" r="9" fill="#F3BA2F"/><path d="M9 4.5L7.2 6.3l-1.8-1.8L9 1.2l3.6 3.3-1.8 1.8L9 4.5zm-4.5 4.5L2.7 7.2 4.5 5.4l1.8 1.8L4.5 9zm4.5 4.5l-1.8-1.8-1.8 1.8L9 16.8l3.6-3.3-1.8-1.8L9 13.5zm4.5-4.5l1.8 1.8-1.8 1.8-1.8-1.8 1.8-1.8zM10.8 9L9 7.2 7.2 9 9 10.8 10.8 9z" fill="#fff"/></svg>';
     const TOKEN_ICON = TOKEN === 'BNB' ? BNB_ICON : USDT_ICON;
 
@@ -307,7 +308,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
       '<div class="result-sub">' + (error || 'Something went wrong.') + '<br>Please try again.</div></div>';
   }
 
-  // ====== 状态机 ======
+  // ====== State machine ======
 
   const FINAL = ['confirmed', 'rejected', 'failed', 'expired'];
   let lastState = null;
@@ -339,7 +340,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
       stopTimer();
     } else {
       body.innerHTML = renderQR(data);
-      // 渲染 QR 码
+      // Render the QR code
       const qrEl = document.getElementById('qr');
       if (qrEl) {
         new QRious({ element: qrEl, value: URI, size: 200, backgroundAlpha: 1, background: '#ffffff', foreground: '#000000', level: 'M' });
@@ -361,13 +362,13 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
     closeTimer = setTimeout(tick, 1000);
   }
 
-  // 初始渲染
+  // Initial render
   render(null);
 
-  // 倒计时刷新（每秒更新 timer）
+  // Countdown refresh (update timer every second)
   timerInterval = setInterval(() => {
     const remaining = EXPIRE_MS - (Date.now() - startTime);
-    // 后端已进入活跃状态（已连接/签名中/交易已提交），不触发页面过期
+    // Backend has entered an active state (connected / signing / tx-submitted); do not expire the page
     const ACTIVE = ['connected', 'signing', 'tx_submitted'];
     if (remaining <= 0 && !FINAL.includes(lastState) && !ACTIVE.includes(lastState)) {
       lastState = 'expired';
@@ -375,7 +376,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
       maybeAutoClose('expired');
       return;
     }
-    // 更新倒计时文字
+    // Update the countdown label
     const timerEl = document.querySelector('.timer');
     if (timerEl) {
       const expireMin = Math.ceil(Math.max(0, remaining) / 60000);
@@ -383,7 +384,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
       const hintSpan = document.querySelector('.hint-bar span');
       if (hintSpan) hintSpan.textContent = 'Expire in ' + expireMin + ' mins. This page will close automatically once the transfer is completed';
     }
-    // 更新 QR 边框倒计时进度（负值 → 从12点顺时针消失）
+    // Update the QR-border progress (negative offset → the dash recedes clockwise from 12 o'clock)
     const progressEl = document.getElementById('qr-progress');
     if (progressEl) {
       const PL = 1000;
@@ -392,7 +393,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
     }
   }, 1000);
 
-  // 轮询后端状态
+  // Poll backend status
   async function poll() {
     if (stopped) return;
     try {
@@ -426,7 +427,7 @@ function openQRInBrowser(uri, statusPort, amount, token = "USDT", network = "BNB
 }
 
 /**
- * 初始化 WalletConnect SignClient
+ * Initialise the WalletConnect SignClient
  * @param {string} projectId - WalletConnect Cloud project ID
  */
 export async function initSignClient(projectId) {
@@ -446,8 +447,9 @@ export async function initSignClient(projectId) {
     ),
   ]);
 
-  // WalletConnect relay 偶发 null WebSocket 帧，导致 isJsonRpcPayload('id' in null) 崩溃
-  // 在 connection 层过滤掉 null payload，避免错误传播到 provider / request 链路
+  // WalletConnect relay occasionally emits null WebSocket frames, which crashes
+  // isJsonRpcPayload('id' in null). Filter null payloads at the connection layer so
+  // the error never reaches the provider / request chain.
   try {
     const conn = client.core.relayer.provider.connection;
     const _origEmit = conn.emit.bind(conn);
@@ -460,7 +462,7 @@ export async function initSignClient(projectId) {
     };
   } catch {}
 
-  // 清理残留 session + pairing（并行等待完成，确保 relay 状态干净后再建新连接）
+  // Tear down stale sessions + pairings (await in parallel to ensure the relay is clean before reconnecting)
   try {
     const sessions = client.session.getAll();
     if (sessions.length > 0) {
@@ -486,10 +488,10 @@ export async function initSignClient(projectId) {
 }
 
 /**
- * 连接钱包：展示 QR 码，等待用户扫码授权
+ * Connect to a wallet: render the QR code and wait for the user to approve via scan.
  * @param {SignClient} signClient
  * @param {number} statusPort
- * @param {string|null} amount - 需要展示的 USDT 金额（如 "0.66"）
+ * @param {string|null} amount - USDT amount to display (e.g. "0.66")
  * @returns {{ session: object, peerAddress: string }}
  */
 export async function connectWallet(signClient, statusPort, amount = null, token = "USDT", gasAmount = null) {
@@ -503,7 +505,7 @@ export async function connectWallet(signClient, statusPort, amount = null, token
     },
   });
 
-  // 生成 QR 码页面（含状态轮询）并在浏览器中打开
+  // Generate the QR-code page (with status polling) and open it in the browser
   openQRInBrowser(uri, statusPort, amount, token, "BNB Chain(BEP20) only", gasAmount);
   console.error("QR code opened in browser. Scan it with your wallet app.");
   console.error("Waiting for wallet approval...");
@@ -528,11 +530,11 @@ export async function connectWallet(signClient, statusPort, amount = null, token
 }
 
 /**
- * 请求 ERC-20 代币转账
+ * Request an ERC-20 token transfer
  * @param {SignClient} signClient
  * @param {object} session - WalletConnect session
  * @param {{ from: string, to: string, token: string, amount: string, decimals?: number }} params
- * @returns {string} 交易 hash
+ * @returns {string} transaction hash
  */
 export async function requestERC20Transfer(signClient, session, { from, to, token, amount, decimals = 18 }) {
   const value = parseUnits(amount, decimals);
@@ -554,7 +556,7 @@ export async function requestERC20Transfer(signClient, session, { from, to, toke
             from,
             to: token,
             data,
-            gas: "0xFDE8", // 65000 — ERC20 transfer 合约调用
+            gas: "0xFDE8", // 65000 — ERC20.transfer contract call
           },
         ],
       },
@@ -568,11 +570,11 @@ export async function requestERC20Transfer(signClient, session, { from, to, toke
 }
 
 /**
- * 请求原生 BNB 转账
+ * Request a native BNB transfer
  * @param {SignClient} signClient
  * @param {object} session
- * @param {{ from: string, to: string, value: string }} params - value 为 BNB 数量（如 "0.001"）
- * @returns {string} 交易 hash
+ * @param {{ from: string, to: string, value: string }} params - `value` is the BNB amount (e.g. "0.001")
+ * @returns {string} transaction hash
  */
 export async function requestNativeTransfer(signClient, session, { from, to, value }) {
   const weiValue = "0x" + parseUnits(value, 18).toString(16);
@@ -589,7 +591,7 @@ export async function requestNativeTransfer(signClient, session, { from, to, val
             from,
             to,
             value: weiValue,
-            gas: "0x5208", // 21000 — BNB 原生转账固定 gas
+            gas: "0x5208", // 21000 — fixed gas for a native BNB transfer
           },
         ],
       },
@@ -605,11 +607,11 @@ export async function requestNativeTransfer(signClient, session, { from, to, val
 const FINAL_LINGER_MS = 2000;
 
 /**
- * 通用钱包连接高阶函数：自动管理连接生命周期
- * - 启动状态服务器
- * - 扫码连接钱包
- * - 执行调用方的事务逻辑
- * - 无论成功失败，始终断开连接并清理
+ * Higher-order wallet-connect helper: manages the full connection lifecycle.
+ * - Starts the status server
+ * - Waits for the user to scan and connect their wallet
+ * - Runs the caller's transaction logic
+ * - Always disconnects and cleans up, whether the body succeeded or failed
  *
  * @param {{ amount?: string, projectId?: string }} opts
  * @param {(ctx: { signClient, session, peerAddress }) => Promise<void>} fn
@@ -629,7 +631,7 @@ export async function withWallet(opts, fn) {
 
     await fn({ signClient, session, peerAddress });
 
-    // 成功：写回 mainWallet
+    // Success: persist mainWallet so subsequent withdraws can default to it
     const config = loadConfig();
     config.mainWallet = peerAddress;
     saveConfig(config);
@@ -652,11 +654,11 @@ export async function withWallet(opts, fn) {
     await new Promise((r) => setTimeout(r, FINAL_LINGER_MS));
     stopStatusServer();
     if (signClient) {
-      // 断开当前 session
+      // Disconnect the current session
       if (session) {
         await disconnectSession(signClient, session);
       }
-      // 断开所有 pairing，确保钱包端不残留连接
+      // Disconnect every pairing so the wallet side has no lingering connection
       try {
         const pairings = signClient.core.pairing.pairings.getAll({ active: true });
         await Promise.allSettled(
@@ -672,19 +674,19 @@ export async function withWallet(opts, fn) {
 }
 
 /**
- * 标准化钱包错误消息：将已知的中文/多语言错误映射为统一英文
+ * Normalise wallet error messages: map known Chinese / multilingual error strings to a unified English form.
  * @param {Error} error
- * @returns {Error} 同一个 error 对象，message 已替换
+ * @returns {Error} the same error object with its `message` rewritten
  */
 export function normalizeWalletError(error) {
   const msg = error?.message || "";
   const patterns = [
-    // 拒绝类
-    { test: /拒绝|用户取消|User rejected|User denied|declined/i, replacement: "rejected" },
-    // 断开连接类
-    { test: /断开.*连接|断开.*DApp|disconnect.*DApp|session.*expired|session.*disconnected/i, replacement: "rejected" },
-    // 超时类
-    { test: /超时|timed?\s*out|timeout/i, replacement: "timed out" },
+    // Rejection patterns (English error strings only — localised wallets fall through to WALLET_ERROR)
+    { test: /User rejected|User denied|declined/i, replacement: "rejected" },
+    // Disconnect patterns
+    { test: /disconnect.*DApp|session.*expired|session.*disconnected/i, replacement: "rejected" },
+    // Timeout patterns
+    { test: /timed?\s*out|timeout/i, replacement: "timed out" },
   ];
   for (const { test, replacement } of patterns) {
     if (test.test(msg)) {
@@ -696,7 +698,7 @@ export function normalizeWalletError(error) {
 }
 
 /**
- * 断开 WalletConnect 会话
+ * Disconnect a WalletConnect session.
  * @param {SignClient} signClient
  * @param {object} session
  */
@@ -707,6 +709,6 @@ export async function disconnectSession(signClient, session) {
       reason: { code: 6000, message: "Session complete" },
     });
   } catch {
-    // 静默处理断开错误
+    // Silently ignore disconnect errors
   }
 }

package/src/x402.mjs

@@ -1,5 +1,5 @@
 /**
- * x402 协议客户端：初始化 EVM signer + x402Client
+ * x402 protocol client: initialise an EVM signer and an x402Client.
  */
 import { x402Client, wrapAxiosWithPayment, x402HTTPClient } from "@aeon-ai-pay/axios";
 import { registerExactEvmScheme } from "@aeon-ai-pay/evm/exact/client";
@@ -11,8 +11,8 @@ import { BSC_RPC_URL } from "./constants.mjs";
 import axios from "axios";
 
 /**
- * 创建已注册 EVM 签名的 x402 axios 客户端
- * @param {`0x${string}`} privateKey - EVM 私钥
+ * Build an x402 axios client with the EVM signer pre-registered.
+ * @param {`0x${string}`} privateKey - EVM private key
  * @returns {{ api: AxiosInstance, client: x402Client, address: string, getOrderNo: () => string|null }}
  */
 export function createX402Api(privateKey) {
@@ -39,8 +39,9 @@ export function createX402Api(privateKey) {
 
   const axiosInstance = axios.create();
 
-  // 在 wrapAxiosWithPayment 之前注册拦截器，
-  // 从 402 响应体中捕获 orderNo（服务端在 firstRequest 返回）
+  // Register the interceptor *before* wrapAxiosWithPayment so it can
+  // capture orderNo from the 402 response body (the server returns it
+  // on the first request).
   let capturedOrderNo = null;
   axiosInstance.interceptors.response.use(
     (response) => response,
@@ -63,11 +64,13 @@ export function createX402Api(privateKey) {
 }
 
 /**
- * 第一次发起 x402 请求（不带签名），从 402 响应中提取实际付款要求。
- * 同时保留完整的 402 响应数据和原始请求配置，供后续手动签名使用。
- * 字段名与 x402 v2 PaymentRequirements 标准对齐：asset、payTo、amount。
+ * Send the first x402 request (unsigned) and extract the real payment requirements
+ * from the 402 response.
+ * Also keeps the raw 402 response and the original request config so the caller can
+ * sign manually later.
+ * Field names follow the x402 v2 PaymentRequirements standard: asset, payTo, amount.
  *
- * 兼容 GET（card 路径）和 POST（image / Skill Boss 路径）。
+ * Supports both GET (card path) and POST (image / Skill Boss path).
  *
  * @param {string} url
  * @param {{ method?: "GET"|"POST", data?: any, headers?: object }} [options]
@@ -105,7 +108,7 @@ export async function fetchPaymentRequirements(url, options = {}) {
 }
 
 /**
- * 从响应头中解码 PAYMENT-RESPONSE（x402 v2）
+ * Decode the PAYMENT-RESPONSE response header (x402 v2).
  * @param {object} headers - axios response headers
  * @returns {object|null}
  */