@aeon-ai-pay/aigateway 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -7,6 +7,44 @@ 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
+- **`create-card` envelope now carries a `balance` block** (`initial`, `before`,
+  `after`, `charged`, `topup`) parallel to `create-image`, so the agent can
+  render the same money-flow narrative for card issuance.
+
+### Changed
+- **Both paid commands adopt an emoji-aligned card-style success template**
+  with explicit balance transitions (`{initial} → {before}` for top-up;
+  `{before} → {after}` for charge) on dedicated rows. The `💸 Top-up` row is
+  conditional — only rendered when `balance.topup` is non-null.
+  - `create-card`: header `✅ Card Issued`, rows for Order / Card / State /
+    Face value / Usage / Tx / (optional) Top-up / Charged.
+  - `create-image`: header `✅ Generated`, second row `🧩 Powered by Skillboss`,
+    rows for Path / Format / Dimensions / Size / Tx / (optional) Top-up /
+    Charged.
+- SKILL.md Copy Constraints table extended with all new template rows so
+  agents must reproduce the glyphs (`→`, `−`, `+`) exactly.
+
 ## [0.1.3] — 2026-05-19
 
 ### Fixed
@@ -24,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.3",
+  "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.3"
+  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
@@ -238,16 +233,30 @@ Output template first line:
 
 ### Success
 
-`envelope.data`: `{ orderNo, data, paymentResponse, pollResult? }`. After fetching details (may take ~30 s), display **verbatim**:
+`envelope.data`: `{ orderNo, amount, data, paymentResponse, balance: { initial, before, after, charged, topup }, pollResult? }`.
+
+After fetching details (may take ~30 s), display **verbatim** (emoji, spacing, glyphs `→` / `−` / `+` must match exactly):
 
 ```
-Order No: {orderNo}
-Card: {cardScheme} •••• {last4}
-State: Active
-Remaining balance: ${amount} USD
-Usage: 0 / 1 (single-use)
+✅ Card Issued
+🆔 Order        {orderNo}
+💳 Card         {cardScheme} •••• {last4}
+🎯 State        Active
+💵 Face value   ${amount} USD
+🔢 Usage        0 / 1 (single-use)
+🔗 Tx           {transaction}
+💸 Top-up       {initial} → {before} USDT (+{topup})
+💰 Charged      {before} → {after} USDT (−{charged})
 ```
 
+**Field rules:**
+
+- `{cardScheme}` and `••••{last4}` come from `data.data.model` (already sanitized — never show full card number).
+- `{transaction}` is `data.paymentResponse.txHash` or `data.data.transaction`. If absent, render the line as `🔗 Tx           —`.
+- The **`💸 Top-up`** row is **conditional**: render only when `data.balance.topup` is non-null and non-zero (i.e. a lazy top-up actually happened during this call). Otherwise **omit the entire `💸 Top-up` line**.
+- The **`💰 Charged`** row is always rendered.
+- Use the minus sign character `−` (U+2212) before `{charged}`, not the hyphen `-`. Use `→` (U+2192) for the balance transition arrow.
+
 Always record `orderNo` — only identifier for status queries.
 
 ### Errors
@@ -284,19 +293,31 @@ Output template first line:
 
 ### Success
 
-`envelope.data`: `{ prompt, transaction, images: [{ url, localPath, format, width, height, sizeHuman }], balance: { initial, before, after, charged } }`.
+`envelope.data`: `{ prompt, transaction, images: [{ url, localPath, format, width, height, sizeHuman }], balance: { initial, before, after, charged, topup } }`.
 
-Display **verbatim**:
+Display **verbatim** (emoji, spacing, dash glyphs `→` / `−` / `+` must match exactly):
 
 ```
 ✅ Generated
-Prompt:       {prompt}
-Image:        {localPath} ({width}×{height}, {sizeHuman})
-Transaction:  {transaction}
-Charged:      {balance.charged} USDT
-Balance:      {balance.after} USDT remaining
+🧩 Powered by Skillboss
+📁 Path        {localPath}
+🎨 Format      {FORMAT}
+📐 Dimensions  {width} × {height}
+💾 Size        {sizeHuman}
+🔗 Tx          {transaction}
+💸 Top-up      {initial} → {before} USDT (+{topup})
+💰 Charged     {before} → {after} USDT (−{charged})
 ```
 
+**Field rules:**
+
+- `{FORMAT}` is `data.outputFormat` uppercased (e.g. `PNG`, `JPEG`, `WEBP`).
+- `{width}` / `{height}` / `{sizeHuman}` come from `data.images[0]` (first image only — agent does not list extras unless asked).
+- `{transaction}` is `data.transaction` (may be `null` if the server didn't return one; in that case render the line as `🔗 Tx          —`).
+- The **`💸 Top-up`** line is **conditional**: only render it if `data.balance.topup` is not null and not "0" (i.e. a lazy top-up actually happened during this call). Otherwise **omit the entire `💸 Top-up` line**.
+- The **`💰 Charged`** line is always rendered.
+- Use the minus sign character `−` (U+2212) before `{charged}`, not the hyphen `-`. Use `→` (U+2192) for the balance transition arrow.
+
 ### Errors
 
 | `error.code` | Action |
@@ -404,6 +425,15 @@ The following first-line / key-phrase strings must be **exactly reproduced** —
 | Pre-check | `> Pre-check in progress...` |
 | Top up | `> Topping up wallet...` |
 | Create card | `> Creating Agent Card...` |
+| Card success header | `✅ Card Issued` |
+| Card Order row | `🆔 Order        {orderNo}` |
+| Card scheme row | `💳 Card         {cardScheme} •••• {last4}` |
+| Card State row | `🎯 State        Active` |
+| Card Face value row | `💵 Face value   ${amount} USD` |
+| Card Usage row | `🔢 Usage        0 / 1 (single-use)` |
+| Card Tx row | `🔗 Tx           {transaction}` |
+| Card Top-up row (conditional) | `💸 Top-up       {initial} → {before} USDT (+{topup})` |
+| Card Charged row | `💰 Charged      {before} → {after} USDT (−{charged})` |
 | Create image | `> Generating image...` |
 | Fetch details | `> Fetching card details, please wait...` |
 | Query status | `> Fetching card status...` |
@@ -411,17 +441,25 @@ The following first-line / key-phrase strings must be **exactly reproduced** —
 | Withdraw target line | `To: main wallet (0x0...{last4})` |
 | Withdraw status line | `Status: completed` |
 | Image success header | `✅ Generated` |
+| Image success row 2 | `🧩 Powered by Skillboss` |
+| Image Path row | `📁 Path        {localPath}` |
+| Image Format row | `🎨 Format      {FORMAT}` |
+| Image Dimensions row | `📐 Dimensions  {width} × {height}` |
+| Image Size row | `💾 Size        {sizeHuman}` |
+| Image Tx row | `🔗 Tx          {transaction}` |
+| Image Top-up row (conditional) | `💸 Top-up      {initial} → {before} USDT (+{topup})` |
+| Image Charged row | `💰 Charged     {before} → {after} USDT (−{charged})` |
 | Wallet prepared header | `✅ Wallet prepared` |
 
 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";
@@ -82,11 +82,13 @@ export async function createCard(opts) {
   let sessionAddress;
   let topupAmount = null;
   let balanceInitialUsdt = null;
+  let balanceBeforeChargeUsdt = null;
 
   try {
     const { address, usdt, bnb, bnbRaw } = await getWalletBalance(privateKey);
     sessionAddress = address;
     balanceInitialUsdt = usdt;
+    balanceBeforeChargeUsdt = usdt;
     const usdtNum = parseFloat(usdt);
     logInfo(`Wallet: ${address}`);
     logInfo(`Balance: ${usdt} USDT, ${bnb} BNB`);
@@ -161,7 +163,7 @@ export async function createCard(opts) {
     return;
   }
 
-  // Dry-run：跑完前置检查就退出
+  // Dry-run: exit after preflight checks complete
   if (dryRun) {
     const preview = {
       dryRun: true,
@@ -189,7 +191,7 @@ export async function createCard(opts) {
     return;
   }
 
-  // WalletConnect 充值
+  // WalletConnect top-up
   if (needTopup || needGas) {
     logInfo("Funding flow triggered...");
     try {
@@ -210,6 +212,7 @@ export async function createCard(opts) {
     logInfo("Re-checking wallet balance...");
     try {
       const { usdt, bnbRaw } = await getWalletBalance(privateKey);
+      balanceBeforeChargeUsdt = usdt;
       const usdtNum = parseFloat(usdt);
       if (needGas && bnbRaw === 0n) {
         emitErr("create-card", "INSUFFICIENT_BNB", {
@@ -260,12 +263,28 @@ export async function createCard(opts) {
     const paymentResponse = decodePaymentResponse(response.headers);
     const orderNo = paymentReq.orderNo || response.data?.model?.orderNo || response.data?.orderNo;
 
+    let balanceAfterUsdt = null;
+    try {
+      const after = await getWalletBalance(privateKey);
+      balanceAfterUsdt = after.usdt;
+    } catch (e) {
+      logInfo(`Post-payment balance check failed: ${e.message}`);
+    }
+
     const sanitizedData = sanitizeOutput(response.data);
     const successData = {
       appId,
       orderNo,
+      amount,
       data: sanitizedData,
       paymentResponse,
+      balance: {
+        initial: balanceInitialUsdt,
+        before: balanceBeforeChargeUsdt,
+        after: balanceAfterUsdt,
+        charged: requiredUsdt,
+        topup: topupAmount,
+      },
     };
 
     function findCardStatus(obj) {

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;