@aeon-ai-pay/aigateway 0.1.4 → 0.1.6

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/catalog.mjs

@@ -0,0 +1,38 @@
+/**
+ * tools-catalog client. **No caching** — every call hits the server.
+ *
+ * The server-side catalog (resources/skillboss/tools-catalog.json) is the
+ * single source of truth. Each invocation reads the current state, so model
+ * additions / schema changes take effect immediately with no stale-cache risk.
+ */
+import axios from "axios";
+
+/** Fetch catalog from server. Throws on network / HTTP failure. */
+export async function fetchCatalog(serviceUrl) {
+  if (!serviceUrl) throw new Error("serviceUrl is required");
+  const url = `${serviceUrl}/open/api/skillBoss/tools-catalog`;
+  const resp = await axios.get(url, { timeout: 15_000 });
+  return resp.data;
+}
+
+/**
+ * Find a model entry in the catalog by id.
+ * Returns { category, model, effectiveSchema } or null.
+ * effectiveSchema = model.inputsOverride ?? category.defaultInputsSchema ?? null
+ */
+export function findModel(catalog, modelId) {
+  if (!catalog || !Array.isArray(catalog.categories)) return null;
+  for (const cat of catalog.categories) {
+    if (!Array.isArray(cat.models)) continue;
+    for (const m of cat.models) {
+      if (m.id === modelId) {
+        return {
+          category: cat,
+          model: m,
+          effectiveSchema: m.inputsOverride || cat.defaultInputsSchema || null,
+        };
+      }
+    }
+  }
+  return null;
+}

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/sb-invoke.mjs

@@ -0,0 +1,407 @@
+/**
+ * sb-invoke: invoke any AI tool through the x402 protocol.
+ *
+ * Server endpoint: GET {serviceUrl}/open/ai/x402/skillBoss/create?body=<urlencoded-json>&appId=<merchant>
+ *   (legacy server path name; client-side abstraction is vendor-agnostic.)
+ * Body shape: { "model": "<model_id>", "inputs": { /* tool-specific *​/ } }
+ *
+ * This module exposes two surfaces:
+ *   - invoke(opts)         → core logic, returns a result object. No emit.
+ *                            Reusable from any future thin wrapper.
+ *   - sbInvokeCommand(opts) → commander action handler; runs invoke() and
+ *                            emits the universal envelope.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import axios from "axios";
+import { createX402Api, decodePaymentResponse, fetchPaymentRequirements } from "../x402.mjs";
+import { resolve } from "../config.mjs";
+import { getWalletBalance, getAllowance } from "../balance.mjs";
+import {
+  fundSessionKey,
+  promptTopupAmount,
+  MIN_TOPUP_USDT,
+  TOPUP_PRESETS,
+} from "../funding.mjs";
+import { WalletConnectError } from "../walletconnect.mjs";
+import { emitOk, emitErr, logInfo } from "../output.mjs";
+import { extractOutputs, resolveOutputDir, downloadOutputs } from "../tools-download.mjs";
+import { fetchCatalog, findModel } from "../catalog.mjs";
+import { validateInputs } from "../inputs-validator.mjs";
+
+/**
+ * Parse `--inputs` value: either a JSON literal or `@path/to/file.json`.
+ * Returns the parsed object on success.
+ * Throws { code: 'INPUTS_FILE_NOT_FOUND' | 'INVALID_INPUTS_JSON', message } on failure.
+ */
+function parseInputs(raw) {
+  if (raw == null || raw === "") {
+    const err = new Error("Missing --inputs.");
+    err.code = "MISSING_INPUTS";
+    throw err;
+  }
+  if (typeof raw === "object") return raw;
+
+  let text = String(raw);
+  if (text.startsWith("@")) {
+    const path = text.slice(1);
+    if (!existsSync(path)) {
+      const err = new Error(`Inputs file not found: ${path}`);
+      err.code = "INPUTS_FILE_NOT_FOUND";
+      err.path = path;
+      throw err;
+    }
+    text = readFileSync(path, "utf-8");
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    const err = new Error(`Failed to parse --inputs as JSON: ${e.message}`);
+    err.code = "INVALID_INPUTS_JSON";
+    throw err;
+  }
+}
+
+/**
+ * Core invocation. Returns:
+ *   { ok: true, data: { model, inputs, transaction, downloaded, raw, balance, paymentResponse } }
+ *   { ok: false, code, details }   — caller decides whether to emit
+ *
+ * Never calls emitOk / emitErr / process.exit directly. Suitable for reuse from
+ * any thin wrapper that needs to remap the envelope shape.
+ */
+export async function invoke(opts) {
+  const serviceUrl = resolve(opts.serviceUrl, "AIGATEWAY_SERVICE_URL", "serviceUrl");
+  const privateKey = resolve(opts.privateKey, "EVM_PRIVATE_KEY", "privateKey");
+  const { appId, model } = opts;
+
+  if (!serviceUrl) {
+    return { ok: false, code: "SERVICE_URL_MISSING", details: { appId } };
+  }
+  if (!privateKey) {
+    return { ok: false, code: "WALLET_NOT_CONFIGURED", details: { appId } };
+  }
+  if (!model || !String(model).trim()) {
+    return { ok: false, code: "MISSING_MODEL", details: { appId } };
+  }
+
+  let inputs;
+  try {
+    inputs = parseInputs(opts.inputs);
+  } catch (e) {
+    return {
+      ok: false,
+      code: e.code || "INVALID_INPUTS_JSON",
+      details: { message: e.message, path: e.path, appId },
+    };
+  }
+
+  // ─── Phase 3.2 + 3.3 client-side validation (live catalog from server) ─────
+  //   Catches model typos & missing/invalid inputs *before* any x402 round-trip.
+  //   No cache — always fetches fresh catalog. Falls back gracefully on network
+  //   failure (warn + skip; server still validates).
+  let catalog = null;
+  try {
+    catalog = await fetchCatalog(serviceUrl);
+  } catch (e) {
+    logInfo(`Warn: catalog fetch failed (${e.message}); skipping client-side validation — server will still check.`);
+  }
+
+  if (catalog) {
+    const found = findModel(catalog, model);
+    if (!found) {
+      return {
+        ok: false,
+        code: "INVALID_MODEL_ID",
+        details: {
+          message: `Model "${model}" not found in catalog. Run \`aigateway sb tools\` to see the current list.`,
+          model,
+          appId,
+        },
+      };
+    }
+
+    if (found.effectiveSchema) {
+      const { ok: validOk, errors } = validateInputs(inputs, found.effectiveSchema);
+      if (!validOk) {
+        const missingFields = errors.filter((e) => e.kind === "missing").map((e) => e.field);
+        const code = missingFields.length > 0 ? "MISSING_INPUTS" : "INVALID_INPUTS";
+        return {
+          ok: false,
+          code,
+          details: {
+            message: `Inputs validation failed for ${model}: ${errors.map((e) => `[${e.field}] ${e.message}`).join("; ")}`,
+            errors,
+            required: found.effectiveSchema.required || [],
+            properties: Object.keys(found.effectiveSchema.properties || {}),
+            category: found.category.key,
+            model,
+            appId,
+          },
+        };
+      }
+    }
+  }
+  // ─── End client-side validation ────────────────────────────────────────────
+
+  const bodyPayload = { model, inputs };
+  const bodyParam = encodeURIComponent(JSON.stringify(bodyPayload));
+  const url = `${serviceUrl}/open/ai/x402/skillBoss/create?body=${bodyParam}&appId=${encodeURIComponent(appId)}`;
+
+  logInfo(`Invoking ${model}...`);
+  logInfo("Fetching payment requirements...");
+  let paymentReq;
+  let requiredUsdt;
+  try {
+    paymentReq = await fetchPaymentRequirements(url);
+    requiredUsdt = paymentReq.amountUsdt;
+    logInfo(`Required: ${requiredUsdt} USDT (pay to ${paymentReq.payTo})`);
+  } catch (e) {
+    // Server may return HTTP 400 with structured { code, msg } for pricing / body errors.
+    // Surface that code as-is so the agent can react (e.g. MODEL_PRICING_NOT_CONFIGURED).
+    const serverData = e.response?.data;
+    const serverCode = serverData?.code || serverData?.error;
+    const serverMsg = serverData?.msg || serverData?.message;
+    if (e.response?.status === 400 && serverCode && /^[A-Z_]+$/.test(serverCode)) {
+      return {
+        ok: false,
+        code: serverCode,
+        details: { message: serverMsg || e.message, model, appId, serverStatus: 400 },
+      };
+    }
+    return {
+      ok: false,
+      code: "PAYMENT_FETCH_FAILED",
+      details: { message: `Failed to fetch payment requirements: ${e.message}`, model, appId },
+    };
+  }
+
+  // Balance / allowance / funding decision
+  logInfo("Checking wallet...");
+  let needTopup = false;
+  let needGas = false;
+  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`);
+
+    const allowance = await getAllowance(address);
+    const requiredWei = BigInt(paymentReq.amountWei);
+    if (requiredWei === 0n) {
+      return {
+        ok: false,
+        code: "INVALID_PAYMENT_AMOUNT",
+        details: { message: "Server returned invalid payment amount (0). Please retry later.", appId },
+      };
+    }
+    if (allowance >= requiredWei) {
+      logInfo("Allowance sufficient, no approve needed.");
+    } else {
+      logInfo(`Allowance ${allowance} < required ${requiredWei}; approve needed.`);
+      if (bnbRaw === 0n) {
+        needGas = true;
+        logInfo("No BNB for approve gas, will request BNB transfer.");
+      }
+    }
+
+    if (usdtNum < requiredUsdt) {
+      needTopup = true;
+      const shortfall = requiredUsdt - usdtNum;
+      const minTopup = Math.max(MIN_TOPUP_USDT, Math.ceil(shortfall));
+      logInfo(`USDT insufficient: have ${usdtNum}, need ${requiredUsdt}, shortfall ${shortfall.toFixed(6)} (top-up minimum: ${minTopup} USDT)`);
+
+      if (opts.topupAmount != null && String(opts.topupAmount).trim() !== "") {
+        const amt = Number(opts.topupAmount);
+        if (!Number.isFinite(amt) || amt <= 0) {
+          return {
+            ok: false,
+            code: "AMOUNT_INVALID",
+            details: { message: `Invalid --topup-amount: ${opts.topupAmount}`, appId },
+          };
+        }
+        if (amt < minTopup) {
+          return {
+            ok: false,
+            code: "TOPUP_AMOUNT_TOO_SMALL",
+            details: { message: `--topup-amount ${amt} USDT is below the ${minTopup} USDT minimum for this call.`, minTopup, appId },
+          };
+        }
+        topupAmount = String(opts.topupAmount);
+        logInfo(`Using --topup-amount: ${topupAmount} USDT`);
+      } else if (process.stdin.isTTY) {
+        topupAmount = await promptTopupAmount(minTopup);
+        logInfo(`Selected top-up amount: ${topupAmount} USDT`);
+      } else {
+        const presets = TOPUP_PRESETS.filter((v) => v >= minTopup);
+        return {
+          ok: false,
+          code: "TOPUP_REQUIRED",
+          details: {
+            message: `USDT balance is below the ${minTopup} USDT minimum for this call. Choose a top-up amount and rerun with --topup-amount <usdt>.`,
+            minTopup,
+            required: requiredUsdt,
+            currentBalance: balanceInitialUsdt,
+            address: sessionAddress,
+            appId,
+            presets,
+            hint: `Rerun: aigateway wallet-topup --amount <usdt> --app-id ${appId}`,
+          },
+        };
+      }
+    }
+  } catch (e) {
+    return {
+      ok: false,
+      code: "BALANCE_CHECK_FAILED",
+      details: { message: `Balance check failed: ${e.message}`, appId },
+    };
+  }
+
+  if (needTopup || needGas) {
+    logInfo("Funding flow triggered...");
+    try {
+      await fundSessionKey({
+        sessionAddress,
+        usdtAmount: needTopup ? topupAmount : null,
+        needGas,
+      });
+    } catch (e) {
+      if (e instanceof WalletConnectError) {
+        return { ok: false, code: e.code, details: { message: e.message, address: sessionAddress, appId } };
+      }
+      return { ok: false, code: "FUNDING_FAILED", details: { message: e.message, address: sessionAddress, appId } };
+    }
+
+    logInfo("Re-checking wallet balance...");
+    try {
+      const { usdt, bnbRaw } = await getWalletBalance(privateKey);
+      balanceBeforeChargeUsdt = usdt;
+      const usdtNum = parseFloat(usdt);
+      if (needGas && bnbRaw === 0n) {
+        return {
+          ok: false,
+          code: "INSUFFICIENT_BNB",
+          details: { message: "No BNB for approve transaction after funding. Run 'aigateway wallet-gas' to add BNB manually.", address: sessionAddress, appId },
+        };
+      }
+      if (usdtNum < requiredUsdt) {
+        return {
+          ok: false,
+          code: "INSUFFICIENT_USDT",
+          details: { message: "Still insufficient USDT after funding.", required: `${requiredUsdt} USDT`, available: `${usdt} USDT`, address: sessionAddress, appId },
+        };
+      }
+    } catch (e) {
+      return { ok: false, code: "BALANCE_CHECK_FAILED", details: { message: `Balance re-check failed: ${e.message}`, appId } };
+    }
+  }
+
+  // Sign x402 payment & retry the request.
+  const { client } = createX402Api(privateKey);
+  logInfo(`Submitting payment & request: ${url}`);
+
+  let response;
+  let paymentResponse;
+  try {
+    const { x402HTTPClient } = await import("@aeon-ai-pay/core/client");
+    const httpClient = new x402HTTPClient(client);
+
+    const raw402 = paymentReq.raw402Response;
+    const getHeader = (name) => {
+      const value = raw402.headers[name] ?? raw402.headers[name.toLowerCase()];
+      return typeof value === "string" ? value : undefined;
+    };
+    const paymentRequired = httpClient.getPaymentRequiredResponse(getHeader, raw402.data);
+    const paymentPayload = await client.createPaymentPayload(paymentRequired);
+    const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+
+    response = await axios.get(url, {
+      headers: {
+        ...paymentHeaders,
+        "Access-Control-Expose-Headers": "PAYMENT-RESPONSE",
+      },
+    });
+    paymentResponse = decodePaymentResponse(response.headers);
+  } catch (error) {
+    return {
+      ok: false,
+      code: "PAYMENT_FAILED",
+      details: {
+        message: error.message,
+        status: error.response?.status,
+        data: error.response?.data,
+        appId,
+      },
+    };
+  }
+
+  const transaction = response.data?.transaction || paymentResponse?.txHash || null;
+
+  // Detect downloadable outputs and fetch them locally (unless --raw).
+  let downloaded = [];
+  if (!opts.raw) {
+    const { kind, items } = extractOutputs(response.data);
+    if (items.length) {
+      const outputDir = resolveOutputDir(opts.output, kind);
+      downloaded = await downloadOutputs(items, outputDir);
+      for (const d of downloaded) {
+        if (d.error) {
+          logInfo(`Failed to download ${d.url}: ${d.error}`);
+        } else {
+          logInfo(`Saved: ${d.localPath} (${d.format || "?"}, ${d.width || "?"}×${d.height || "?"}, ${d.sizeHuman})`);
+        }
+      }
+    }
+  }
+
+  // Post-payment balance probe (best effort).
+  let balanceAfterUsdt = null;
+  try {
+    const after = await getWalletBalance(privateKey);
+    balanceAfterUsdt = after.usdt;
+  } catch (e) {
+    logInfo(`Post-payment balance check failed: ${e.message}`);
+  }
+
+  return {
+    ok: true,
+    data: {
+      model,
+      inputs,
+      transaction,
+      downloaded,
+      // unwrap server envelope: { payer, transaction, data: <upstream-response> } → <upstream-response>
+      raw: response.data?.data ?? response.data,
+      paymentResponse,
+      balance: {
+        initial: balanceInitialUsdt,
+        before: balanceBeforeChargeUsdt,
+        after: balanceAfterUsdt,
+        charged: requiredUsdt,
+        topup: topupAmount,
+      },
+    },
+  };
+}
+
+/**
+ * Commander action handler for `aigateway sb invoke`.
+ * Emits the universal envelope; errors are emitted via emitErr (which exits).
+ */
+export async function sbInvokeCommand(opts) {
+  const result = await invoke(opts);
+  if (result.ok) {
+    emitOk("sb-invoke", result.data, { success: true, ...result.data });
+    return;
+  }
+  emitErr("sb-invoke", result.code, result.details);
+}

package/src/commands/sb-tools.mjs

@@ -0,0 +1,37 @@
+/**
+ * sb-tools: fetch and display the AI tool catalog from the server.
+ *
+ *   aigateway sb tools
+ *
+ * No caching — always hits the server. Server-side `tools-catalog.json` is the
+ * single source of truth. Stdout is the full envelope with `data` = catalog.
+ *
+ * Endpoint: GET {serviceUrl}/open/api/skillBoss/tools-catalog
+ *   (free, no x402; price fields are stripped server-side)
+ */
+import { resolve } from "../config.mjs";
+import { emitOk, emitErr, logInfo } from "../output.mjs";
+import { fetchCatalog } from "../catalog.mjs";
+
+export async function sbTools(opts) {
+  const serviceUrl = resolve(opts.serviceUrl, "AIGATEWAY_SERVICE_URL", "serviceUrl");
+  if (!serviceUrl) {
+    emitErr("sb-tools", "SERVICE_URL_MISSING", {});
+    return;
+  }
+
+  logInfo("Fetching tools catalog from server...");
+  let data;
+  try {
+    data = await fetchCatalog(serviceUrl);
+  } catch (e) {
+    emitErr("sb-tools", "CATALOG_FETCH_FAILED", {
+      message: `Failed to fetch tools catalog: ${e.message}`,
+      url: `${serviceUrl}/open/api/skillBoss/tools-catalog`,
+      status: e.response?.status,
+    });
+    return;
+  }
+
+  emitOk("sb-tools", data, { success: true, ...data });
+}

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,19 +1,18 @@
 /**
- * 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 sb invoke
  */
 import { loadConfig, saveConfig } from "../config.mjs";
-import { MIN_AMOUNT, MAX_AMOUNT } from "../constants.mjs";
 import { getWalletBalance, getAllowance } from "../balance.mjs";
 import {
   LOW_BALANCE_THRESHOLD,
@@ -41,7 +40,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 +49,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 +67,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,10 +102,9 @@ 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 },
     chainCheck: chainCheckOk ? "ok" : { error: chainCheckError },
   };
   emitOk("wallet-init", data, data);