@aeon-ai-pay/aigateway 0.2.3 → 0.2.5

package/docs/recipes/integrate-in-agent.md

@@ -6,15 +6,16 @@ This recipe shows how to invoke `aigateway` from inside an agent product (Node.j
 
 - `@aeon-ai-pay/aigateway` installed (globally for system-wide use, or as a dependency in your project).
 - A working session wallet — run `aigateway wallet-init` once on the host.
+- First-time funding done with `aigateway wallet-topup --amount 5` (one-time WalletConnect flow + facilitator `approve`). After this, all `sb invoke` calls are gasless and headless-friendly.
 
-> ⚠️ The CLI uses **WalletConnect for funding**, which opens a browser window with a QR code. If your agent runs headless or in containers without a display, fund the session wallet ahead of time (`aigateway wallet-init`) on a workstation, then ship the `~/.aigateway/config.json` to the runtime host. Agents should never embed user main-wallet private keys.
+> ⚠️ `wallet-topup` opens a browser window with a WalletConnect QR code. If your agent runs headless or in containers without a display, fund the session wallet ahead of time on a workstation, then ship the `~/.aigateway/config.json` (or its `privateKey`) to the runtime host. Agents should never embed user main-wallet private keys.
 
 ## Node.js — Spawn & Parse Envelope
 
 ```js
 import { spawn } from "node:child_process";
 
-function runAEON AI Gateway(args) {
+function runAigateway(args) {
   return new Promise((resolve, reject) => {
     const child = spawn("aigateway", args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
@@ -33,18 +34,20 @@ function runAEON AI Gateway(args) {
   });
 }
 
-// Example: create a $5 card and poll until terminal
-const { envelope, exitCode } = await runAEON AI Gateway([
+// Example: invoke an AI tool (image generation) via the x402 paid entry point
+const { envelope, exitCode } = await runAigateway([
   "--quiet",
-  "create",
-  "--amount", "5",
+  "sb", "invoke",
+  "--model", "replicate/black-forest-labs/flux-schnell",
+  "--inputs", JSON.stringify({ prompt: "a cyberpunk fox", aspect_ratio: "1:1" }),
   "--app-id", "MY_AGENT_001",
-  "--poll",
 ]);
 
 if (envelope.ok) {
-  const { orderNo, data } = envelope.data;
-  console.log("Card ready:", data.model?.cardNumber, "order:", orderNo);
+  const { model, transaction, downloaded, balance } = envelope.data;
+  console.log(`Done (${model}) tx=${transaction}`);
+  for (const d of downloaded) console.log(`Saved: ${d.localPath} (${d.sizeHuman})`);
+  console.log(`Charged ${balance.charged} USDT, remaining ${balance.after}`);
 } else {
   // See docs/recipes/error-recovery.md for code-by-code guidance
   console.error(`Failed [${envelope.error.code}] (exit ${exitCode}):`, envelope.error.message);
@@ -74,22 +77,40 @@ def run_aigateway(args):
     envelope = json.loads(result.stdout.strip().splitlines()[-1])
     return result.returncode, envelope
 
-exit_code, env = run_aigateway(["create", "--amount", "5", "--poll"])
+exit_code, env = run_aigateway([
+    "sb", "invoke",
+    "--model", "replicate/black-forest-labs/flux-schnell",
+    "--inputs", json.dumps({"prompt": "a cyberpunk fox"}),
+])
 if env["ok"]:
-    print("Card ready:", env["data"]["data"]["model"]["cardNumber"])
+    for d in env["data"]["downloaded"]:
+        print("Saved:", d["localPath"])
 else:
     print(f"Failed [{env['error']['code']}] exit={exit_code}: {env['error']['message']}")
 ```
 
-## Probing Without Cost — `--dry-run`
+## Discovering Models — `sb tools`
 
-To validate inputs, balances, and allowance **without** signing or transacting, use `--dry-run` on `create-card`:
+Before calling `sb invoke`, fetch the live catalog with `sb tools` to pick a valid `model` and learn the expected `inputs` schema:
 
 ```bash
-aigateway --quiet create-card --amount 5 --dry-run | jq '.data.will, .data.decision'
+# Single model + effectiveSchema (most useful for agents)
+aigateway --quiet sb tools --model replicate/black-forest-labs/flux-schnell | jq '.data'
+
+# All models in a category
+aigateway --quiet sb tools --category image | jq '.data.categories[0].models[].id'
+
+# Cheapest tier across all categories
+aigateway --quiet sb tools --tier price
 ```
 
-This is ideal for integration tests, configuration smoke checks, and "is everything ready?" probes.
+The catalog is fetched live from the server each call (no local cache). Each model carries `price`, `priceUnit`, `tier`, and an optional `inputsOverride`; each category carries `defaultInputsSchema`.
+
+## Probing Without Cost
+
+`sb invoke` performs client-side validation of `--model` and `--inputs` against the live catalog **before** any x402 round-trip. Invalid model ids and missing/invalid fields return `INVALID_MODEL_ID` / `MISSING_INPUTS` / `INVALID_INPUTS` locally, with zero USDT spent.
+
+For wallet-only smoke tests, `aigateway wallet-balance` is read-only and never signs anything.
 
 ## Exit Code Strategy
 
@@ -99,7 +120,7 @@ Treat exit codes as a fast filter, then branch on `error.code` for nuance:
 switch (exitCode) {
   case 0: /* success */ break;
   case 1: /* user / config — surface to caller for correction */ break;
-  case 2: /* timeout — safe to retry; card may still be provisioning */ break;
+  case 2: /* timeout — safe to retry the same command */ break;
   case 3: /* network / service — exponential backoff retry */ break;
   case 4: /* internal — log + fail loud */ break;
 }

package/docs/recipes/merchant-integration.md

@@ -33,8 +33,8 @@ Both modes use the same CLI; only the source of the session key (`EVM_PRIVATE_KE
 Your product walks the user through:
 
 ```bash
-aigateway wallet-init                    # one-time, auto-creates local key
-aigateway wallet-topup --amount 5         # user scans QR to load 5 USDT
+aigateway wallet-init                     # one-time, auto-creates local session key
+aigateway wallet-topup --amount 5         # user scans QR to load 5 USDT + tiny BNB for first-time approve
 ```
 
 Subsequent paid calls are spawned by your product (agent / IDE plugin / app):
@@ -59,11 +59,18 @@ function runAigateway(args) {
   });
 }
 
-const { envelope } = await runAigateway(["create-card", "--amount", "5", "--poll"]);
+const inputs = { prompt: "a cyberpunk fox", aspect_ratio: "1:1" };
+const { envelope } = await runAigateway([
+  "sb", "invoke",
+  "--model", "replicate/black-forest-labs/flux-schnell",
+  "--inputs", JSON.stringify(inputs),
+]);
+
 if (envelope.ok) {
-  showCard(envelope.data);  // card number already redacted to "•••• 4242"
+  showImages(envelope.data.downloaded);                   // [{ localPath, format, width, height, sizeHuman, ... }]
 } else if (envelope.error.code === "TOPUP_REQUIRED") {
-  promptUserToTopup(envelope.error.presets);  // [5, 10, 20, 50]
+  // Headless / non-TTY ran out of USDT. Use envelope.error.presets and rerun.
+  promptUserToTopup(envelope.error.presets);              // [5, 10, 20, 50]
 }
 ```
 
@@ -77,7 +84,10 @@ aigateway already supports `EVM_PRIVATE_KEY` — no config file needed:
 
 ```bash
 EVM_PRIVATE_KEY=0xYourMerchantSessionKey \
-  aigateway create-card --amount 5 --app-id MERCHANT_ACME_001 --poll
+  aigateway sb invoke \
+    --model replicate/black-forest-labs/flux-schnell \
+    --inputs '{"prompt":"a cyberpunk fox"}' \
+    --app-id MERCHANT_ACME_001
 ```
 
 ### 3.2 Express backend example
@@ -107,23 +117,30 @@ function runCmd(args) {
 }
 
 // User paid you in fiat upstream, now you fulfil via aigateway
-app.post("/api/issue-card", async (req, res) => {
-  const { userId, amount } = req.body;
+app.post("/api/generate-image", async (req, res) => {
+  const { userId, prompt } = req.body;
 
   // Your KYC / fraud / balance checks
-  if (!await canIssueCard(userId, amount)) return res.status(403).end();
+  if (!await canSpend(userId)) return res.status(403).end();
 
-  const { code, envelope } = await runCmd(["create-card", "--amount", String(amount), "--poll"]);
+  const { code, envelope } = await runCmd([
+    "sb", "invoke",
+    "--model", "replicate/black-forest-labs/flux-schnell",
+    "--inputs", JSON.stringify({ prompt }),
+  ]);
 
   if (envelope.ok) {
-    await db.cards.insert({
+    const [first] = envelope.data.downloaded;
+    await db.generations.insert({
       userId,
-      orderNo: envelope.data.orderNo,
-      cardNumber: envelope.data.data.model.cardNumber,
-      amount,
-      issuedAt: new Date(),
+      model: envelope.data.model,
+      transaction: envelope.data.transaction,
+      localPath: first?.localPath,
+      url: first?.url,
+      charged: envelope.data.balance.charged,
+      createdAt: new Date(),
     });
-    res.json({ ok: true, orderNo: envelope.data.orderNo });
+    res.json({ ok: true, transaction: envelope.data.transaction, file: first?.localPath });
   } else {
     await logErr(userId, envelope.error);
     res.status(500).json({ error: envelope.error.code, message: envelope.error.message });
@@ -142,7 +159,7 @@ EVM_PRIVATE_KEY=<your-merchant-session-key> \
   aigateway wallet-topup --amount 50 --app-id MERCHANT_ACME_001
 ```
 
-Scan QR with your treasury wallet, confirm two transactions (USDT + 0.0003 BNB for one-time approve). After this, the production server can issue cards / images **without ever opening WalletConnect**.
+Scan QR with your treasury wallet, confirm two transactions (USDT + a small amount of BNB for the one-time `approve`). After this, the production server can issue `sb invoke` calls **without ever opening WalletConnect** until USDT is depleted.
 
 ### 3.4 Low-balance alerting
 
@@ -168,18 +185,29 @@ function handleEnvelope(envelope, exitCode) {
 
     case "INSUFFICIENT_USDT":
     case "TOPUP_REQUIRED":
-      await yourTopupFlow();
+      await yourTopupFlow(envelope.error.presets);       // [5, 10, 20, 50]
+      return { ok: false, retry: true };
+
+    case "INSUFFICIENT_BNB":
+      await yourGasTopupFlow();                          // aigateway wallet-gas
       return { ok: false, retry: true };
 
-    case "AMOUNT_OUT_OF_RANGE":
-      return { ok: false, userMessage: `Amount must be $${envelope.error.min}~${envelope.error.max}` };
+    case "MISSING_MODEL":
+    case "INVALID_MODEL_ID":
+      return { ok: false, userMessage: "Pick a model first (run `aigateway sb tools`)" };
+
+    case "MISSING_INPUTS":
+    case "INVALID_INPUTS":
+    case "INVALID_INPUTS_JSON":
+      // envelope.error.errors[] = [{ field, kind, message }], plus required[] / properties[]
+      return { ok: false, validation: envelope.error };
 
-    case "POLL_TIMEOUT":
-      await scheduleStatusCheck(envelope.error.orderNo);
-      return { ok: false, asyncPending: true };
+    case "MODEL_PRICING_NOT_CONFIGURED":
+      return { ok: false, userMessage: "This model is not yet priced; pick another" };
 
     case "SERVICE_UNAVAILABLE":
     case "PAYMENT_FETCH_FAILED":
+    case "CATALOG_FETCH_FAILED":
     case "BALANCE_CHECK_FAILED":
       return { ok: false, retryWithBackoff: true };
 
@@ -187,6 +215,10 @@ function handleEnvelope(envelope, exitCode) {
     case "PAYMENT_TIMEOUT":
       return { ok: false, userMessage: "Payment not confirmed" };
 
+    case "DOWNLOAD_FAILED":
+      // Generation succeeded; original URL still in envelope.error.url (if surfaced) or downloaded[].url
+      return { ok: false, partial: true };
+
     default:
       throw new UnexpectedError(envelope.error);
   }
@@ -197,23 +229,20 @@ Full code table: [exit-codes.md](../exit-codes.md). Concrete recovery actions pe
 
 ## 5. Sandbox / test environments
 
-### Dry-run (no real USDT)
+### Validation-only probes
 
-```bash
-aigateway create-card --amount 5 --dry-run --app-id TEST000001
-# envelope.data.dryRun = true; preflight passes, nothing signed
-```
+`sb invoke` performs client-side schema validation against the live catalog **before** any payment round-trip — so an invalid `--model` or malformed `--inputs` fails locally with zero USDT spent. Use this to validate your subprocess wrapper + envelope parser in CI without burning real budget.
 
 ### Staging service URL
 
 ```bash
 AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \
-  aigateway create-card --amount 5 --app-id YOUR_TEST_APPID --poll
+  aigateway sb invoke --model <id> --inputs '<json>' --app-id YOUR_TEST_APPID
 ```
 
 ### CI
 
-Never invoke real paid commands in CI. Use `--dry-run` to validate your subprocess wrapper + envelope parser only.
+Never invoke real paid commands in CI. Wrap your test fixtures around invalid-input probes (so the call short-circuits with `MISSING_INPUTS` / `INVALID_MODEL_ID`) or use `wallet-balance` (read-only).
 
 ## 6. Operational checklist for merchants
 
@@ -224,15 +253,15 @@ Never invoke real paid commands in CI. Use `--dry-run` to validate your subproce
 | Top-up (manual, workstation) | When USDT is low | `wallet-topup --amount <n>` |
 | Withdraw to merchant treasury | Monthly / quarterly | `wallet-withdraw --to <treasury>` |
 | Auto version upgrade | Automatic | (handled by `src/update-check.mjs`) |
-| Reconciliation | Per settlement | Use `envelope.data.orderNo` / `transaction` to match on-chain + backend records |
+| Reconciliation | Per settlement | Use `envelope.data.transaction` / `paymentResponse.txHash` to match on-chain + backend records |
 
 ## 7. Security checklist
 
 - **Session key (custodial mode)** = funds. **Store in Vault / KMS / encrypted env var only**. Never commit to git or write to plaintext `.env` files in production.
 - **`appId` is not a secret.** Leaking it doesn't lose money, but could let someone burn API quota under your identity. If the backend requires authenticated calls, the AEON team will issue a separate API key — confirm with them.
-- **Card PII**: `envelope.data.data.model.cardNumber` is already redacted to `"•••• 4242"`. The full PAN / CVV / expiry is retrievable only via the merchant-side API with strong auth (not exposed in this CLI). Don't try to capture full card data from the CLI.
 - **WalletConnect**: only run `wallet-topup` / `wallet-gas` / `wallet-init` on a workstation with a wallet app. Don't let your production server auto-spawn QR windows.
 - **`EVM_PRIVATE_KEY` env var**: scope it to the process that needs it (e.g. systemd unit, k8s secret-mounted file). Don't echo it to logs.
+- **Generated artifacts**: `sb invoke` saves binary outputs (images / videos / audio) under `~/aigateway-{images,videos,audio}/` by default. In custodial deployments, override with `--output <dir>` and treat the contents as user data (retention, access control).
 
 ## 8. See also
 

package/docs/troubleshooting.md

@@ -58,11 +58,11 @@ If you're in a custodial / server context, inject the key via env var instead:
 EVM_PRIVATE_KEY=0x...  aigateway wallet-balance
 ```
 
-### QR window doesn't open during `wallet-topup`
+### QR window doesn't open during `wallet-topup` / `wallet-gas`
 
 The CLI tries `open` (macOS) / `start` (Windows) / `xdg-open` (Linux). In headless environments, it prints the file path. Open `file:///tmp/aigateway-qr.html` manually in any browser. If you're on a remote VM, port-forward `127.0.0.1:<status-port>` (printed in stderr) and open the file locally instead.
 
-**Headless servers should never run `wallet-topup` interactively** — see [merchant-integration.md § 3.3](./recipes/merchant-integration.md) for the workstation pre-funding pattern.
+**Headless servers should never run `wallet-topup` / `wallet-gas` interactively** — see [merchant-integration.md § 3.3](./recipes/merchant-integration.md) for the workstation pre-funding pattern.
 
 ### `error.code: PAYMENT_TIMEOUT`
 
@@ -76,12 +76,13 @@ You (or the user) tapped "Reject" in the wallet app. Same as above — re-run on
 
 Likely causes:
 1. The `wallet-topup` you ran was on a **different** session key. Verify `aigateway wallet-balance` shows the same address you funded.
-2. The on-chain tx hasn't confirmed yet. BSC normally confirms within 3 seconds; if longer, check `~/.aigateway/update.log` and the explorer.
-3. You funded in the wrong network (BSC vs. ETH). aigateway only reads USDT on **BSC** (chain id 56, contract `0x55d3...955`).
+2. The on-chain tx hasn't confirmed yet. BSC normally confirms within 3 seconds; if longer, check the explorer.
+3. You funded in the wrong network (BSC vs. ETH). aigateway only reads USDT on **BSC** (chain id 56).
+4. The call's required USDT exceeded your topped-up amount. `error.required` shows what the model needed; rerun `sb invoke` with a larger `--topup-amount`, or run `wallet-topup --amount <n>` separately.
 
 ### `error.code: INSUFFICIENT_BNB`
 
-`wallet-withdraw` and the one-time approve in `wallet-topup` are direct on-chain transactions and need BNB for gas. Run:
+`wallet-withdraw` and the one-time approve inside `wallet-topup` are direct on-chain transactions and need BNB for gas. Run:
 
 ```bash
 aigateway wallet-gas --amount 0.001
@@ -104,6 +105,48 @@ sleep 3 && aigateway wallet-balance
 
 If reproducible, file an issue.
 
+## `sb invoke` / `sb tools`
+
+### `error.code: MISSING_MODEL` / `INVALID_MODEL_ID`
+
+You didn't pass `--model`, or the id you passed isn't in the live catalog. Run:
+
+```bash
+aigateway sb tools                       # list everything
+aigateway sb tools --category image      # narrow to a category
+aigateway sb tools --model <id>          # confirm a specific id + see its effectiveSchema
+```
+
+Never hard-code model ids in long-lived prompts — vendors rename, the gateway catalog is the source of truth.
+
+### `error.code: MISSING_INPUTS` / `INVALID_INPUTS`
+
+`sb invoke` validates `--inputs` against the live catalog **before** any payment round-trip. Inspect `error.errors[]` — each item carries `{ field, kind, message }`, with `kind ∈ {missing, enum, type, range}`. `error.required[]` lists every required field for the chosen model.
+
+Common cases:
+- `video` model without `inputs.duration_seconds` (1–300).
+- `stt` model without `inputs.duration_minutes` (1–360).
+- `tts` model without `inputs.text`.
+- Image `aspect_ratio` not in the enum (e.g. `"square"` instead of `"1:1"`).
+
+Re-pull the schema with `aigateway sb tools --model <id>` and fix the JSON.
+
+### `error.code: INVALID_INPUTS_JSON`
+
+Your `--inputs` string couldn't be parsed. From a shell, use `JSON.stringify(...)` in your wrapper (Node.js / Python) and pass the result with single quotes around the whole argument. Alternatively pass `--inputs @path/to/inputs.json` to read from a file.
+
+### `error.code: MODEL_PRICING_NOT_CONFIGURED`
+
+The catalog lists the model but the gateway has no price entry for it yet (operator-side gap). Pick another model from the same category; mention it to the AEON team if you specifically need that one.
+
+### `error.code: DOWNLOAD_FAILED` / `IMAGE_DOWNLOAD_FAILED`
+
+The paid call succeeded — money was charged — but the local file save failed (URL 404, timeout, disk full). The URL is still available in `data.downloaded[].url`. Re-fetch the URL directly, or rerun the same command with `--raw` to skip auto-download and inspect `raw`. **Do not re-invoke the model** unless you're prepared to pay again.
+
+### `error.code: CATALOG_FETCH_FAILED`
+
+`sb tools` couldn't reach the server. `sb invoke` will still run (server-side validation is the safety net), it'll just skip the local pre-validation step. Retry once; if it persists, check network connectivity to the configured `AIGATEWAY_SERVICE_URL`.
+
 ## Skill / Agent integration
 
 ### Skill not picked up by Cursor / Windsurf / Cline / Codex
@@ -122,18 +165,22 @@ The skill version is locked to `metadata.version` in the frontmatter. If you edi
 
 ```yaml
 metadata:
-  version: "0.1.1"   # was 0.1.0
+  version: "0.2.5"   # was 0.2.5
 ```
 
 Then `npx skills add AEON-Project/aigateway -g -y -f` (force) or re-run postinstall.
 
 ## Auto-upgrade (`update-check.mjs`)
 
+### `error.code: UPDATE_APPLIED`
+
+The CLI detected a newer published version, upgraded itself in-place, and **did not execute your command**. The envelope carries `error.from` / `error.to`. Rerun the same command verbatim on the new version. Do not treat this as a generic timeout.
+
 ### Auto-upgrade doesn't seem to run
 
-Check `~/.aigateway/update.log`. The upgrade is a detached background process and may take 1–2 minutes after the CLI is invoked. If the log shows a failure, the most common reasons are:
+Check `~/.aigateway/update.log`. The upgrade runs synchronously at startup; if the log shows a failure, the most common reasons are:
 
-- Your global npm registry needs auth and the background process can't prompt.
+- Your global npm registry needs auth and the foreground process can't prompt.
 - The user lacks permission to write to the global node_modules (run with sudo, or use nvm).
 
 You can force-upgrade manually:
@@ -144,10 +191,10 @@ npm install -g @aeon-ai-pay/aigateway@latest
 
 ### Block the auto-upgrade
 
-Currently no flag for this — but the upgrade is **non-blocking** and won't affect the current command. If you need a deterministic version (e.g. in CI), pin the install:
+Currently no flag for this. If you need a deterministic version (e.g. in CI), pin the install:
 
 ```bash
-npm install -g @aeon-ai-pay/aigateway@0.1.0
+npm install -g @aeon-ai-pay/aigateway@<version>
 ```
 
 The check still runs but the install is idempotent at the same version.
@@ -167,20 +214,21 @@ Causes:
 
 ### Spawning hangs forever
 
-If you spawn `wallet-topup` / `create-card` / `create-image` in a context where the QR window can't be shown (CI, server, headless), the CLI waits 5 minutes for the WalletConnect signature, then exits with `PAYMENT_TIMEOUT`. **Never spawn these without pre-funded session keys** — see [merchant-integration.md § 3](./recipes/merchant-integration.md).
+If you spawn `wallet-topup` / `wallet-gas` (or `sb invoke` against an empty wallet) in a context where the QR window can't be shown (CI, server, headless), the CLI waits 5 minutes for the WalletConnect signature, then exits with `PAYMENT_TIMEOUT`. **Never spawn these without a pre-funded session key** — see [merchant-integration.md § 3](./recipes/merchant-integration.md).
 
 ## Service / network
 
 ### `error.code: SERVICE_UNAVAILABLE`
 
-Upstream is degraded. Retry with exponential backoff (1s → 4s → 16s, max 3 attempts). If it persists for more than 5 minutes, contact AEON support with the `appId` and an example `orderNo`.
+Upstream is degraded. Retry with exponential backoff (1s → 4s → 16s, max 3 attempts). If it persists for more than 5 minutes, contact AEON support with the `appId` and an example `transaction` hash.
 
 ### Staging vs. production
 
 The default service URL is `https://ai-api.aeon.xyz` (production). To use a staging endpoint:
 
 ```bash
-AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz  aigateway create-card --amount 5
+AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \
+  aigateway sb tools --category image
 ```
 
 ## Getting more diagnostics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeon-ai-pay/aigateway",
-  "version": "0.2.3",
+  "version": "0.2.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": {
@@ -19,11 +19,11 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "create-card": "node bin/cli.mjs create-card",
-    "create-image": "node bin/cli.mjs create-image",
     "wallet-init": "node bin/cli.mjs wallet-init",
     "wallet-topup": "node bin/cli.mjs wallet-topup",
     "wallet-balance": "node bin/cli.mjs wallet-balance",
+    "sb-tools": "node bin/cli.mjs sb tools",
+    "sb-invoke": "node bin/cli.mjs sb invoke",
     "release": "node scripts/release.mjs"
   },
   "dependencies": {
@@ -43,8 +43,14 @@
     "aigateway",
     "agent-skills",
     "x402",
-    "virtual-card",
-    "ai-image",
+    "ai-tools",
+    "image-generation",
+    "video-generation",
+    "text-to-speech",
+    "speech-to-text",
+    "web-search",
+    "web-scraping",
+    "embeddings",
     "skill-boss",
     "crypto-payment",
     "evm",

package/skills/aigateway/SKILL.md

@@ -26,7 +26,7 @@ description: >
 emoji: "🛰️"
 homepage: https://github.com/AEON-Project/aigateway
 metadata:
-  version: "0.2.3"
+  version: "0.2.5"
   author: AEON-Project
   openclaw:
     requires:
@@ -256,7 +256,10 @@ Approve:   {approveTx truncated or "already approved"}
 
 ⭐ **默认模式**：**AI 不擅自选 model**，而是把候选 + 预估总价列给用户，让用户拍板。**推荐默认选最便宜的**（按 `tier: "price"` 优先排序）。
 
-**例外**：用户原话已经指定了 model（`"用 flux-2-max 画"`） → 直接用，跳过列表。
+**跳过候选展示的场景**（任一命中即跳过）：
+
+1. 用户原话已经指定了 model（`"用 flux-2-max 画"`） → 直接用
+2. **任务匹配后候选只剩 1 个 model** → 直接用该 model，不要再渲染单行"列表"和"输入序号"引导。若 `priceUnit` 需要用量字段（`per_second` / `per_minute`），只问用量；其它直接调用。用一行 `✨ 选用 {model_id}（${unitPrice}{unit-cn} × {quantity} = ${total} USDT），开始生成…` 替代候选表格。
 
 #### Step A: 看 `priceUnit` 决定是否前置询问用量
 

package/src/commands/sb-invoke.mjs

@@ -27,6 +27,7 @@ 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";
+import { CAMPAIGN_TOKEN_ADDRESS } from "../constants.mjs";
 
 /**
  * Parse `--inputs` value: either a JSON literal or `@path/to/file.json`.
@@ -151,10 +152,19 @@ export async function invoke(opts) {
   logInfo("Fetching payment requirements...");
   let paymentReq;
   let requiredUsdt;
+  let paymentMethod = "USDT"; // "USDT" | "COUPON"
   try {
     paymentReq = await fetchPaymentRequirements(url);
     requiredUsdt = paymentReq.amountUsdt;
-    logInfo(`Required: ${requiredUsdt} USDT (pay to ${paymentReq.payTo})`);
+    // 服务端在 402 响应里的 asset 字段如果等于活动 token 合约 → 本次走优惠券支付
+    if (paymentReq.asset && paymentReq.asset.toLowerCase() === CAMPAIGN_TOKEN_ADDRESS.toLowerCase()) {
+      paymentMethod = "COUPON";
+    }
+    if (paymentMethod === "COUPON") {
+      logInfo(`💳 Paid with coupon: ${requiredUsdt} (token ${paymentReq.asset})`);
+    } else {
+      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).
@@ -382,6 +392,8 @@ export async function invoke(opts) {
       // unwrap server envelope: { payer, transaction, data: <upstream-response> } → <upstream-response>
       raw: response.data?.data ?? response.data,
       paymentResponse,
+      paymentMethod,           // "USDT" | "COUPON" — agent / CLI 可据此显示扣款方式
+      paymentToken: paymentReq.asset,
       balance: {
         initial: balanceInitialUsdt,
         before: balanceBeforeChargeUsdt,

package/src/commands/wallet-init.mjs

@@ -12,7 +12,7 @@
  *   - 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 { loadConfig, saveConfig, getOrCreateDeviceId, resolve } from "../config.mjs";
 import { getWalletBalance, getAllowance } from "../balance.mjs";
 import {
   LOW_BALANCE_THRESHOLD,
@@ -20,6 +20,7 @@ import {
   TOPUP_PRESETS,
 } from "../funding.mjs";
 import { emitOk, logInfo } from "../output.mjs";
+import { checkCouponStatus, claimCoupon } from "../coupon.mjs";
 
 export async function initWallet(opts) {
   const config = loadConfig();
@@ -90,12 +91,65 @@ export async function initWallet(opts) {
     topupReason = "no_approve";
   }
 
+  // device id 在首次 init 时生成,后续 claim / 审计复用
+  const deviceId = getOrCreateDeviceId();
+
+  // AEON x BNB Chain AI Agent Campaign — 两步同步流程:
+  //   1) status check:已领 → 跳过,直接走后续流程
+  //   2) 未领 → 输出"申请中..." → claim 同步阻塞 → 输出 mint 结果
+  // 任何网络异常都安静 log,不阻塞 wallet-init 主流程。
+  let coupon = null;
+  const serviceUrl = resolve(opts.serviceUrl, "AIGATEWAY_SERVICE_URL", "serviceUrl");
+  if (serviceUrl && config.address) {
+    const status = await checkCouponStatus({ serviceUrl, userAddress: config.address });
+    if (status.ok && status.claimed) {
+      // 已领过 → 直接走后续流程
+      logInfo(`Coupon already claimed (status=${status.mintStatus}${status.mintTxHash ? ", tx=" + status.mintTxHash : ""}).`);
+      coupon = {
+        ok: status.mintStatus === "SUCCESS",
+        code: status.mintStatus === "SUCCESS" ? "ALREADY_CLAIMED_SUCCESS" : "ALREADY_CLAIMED_" + status.mintStatus,
+        tokenAddress: status.tokenAddress,
+        tokenAmount: status.tokenAmount,
+        txHash: status.mintTxHash,
+        campaignId: status.campaignId,
+      };
+    } else if (status.ok && !status.claimed) {
+      // 未领 → 申请,同步阻塞
+      logInfo("🎁 Claiming AEON x BNB campaign coupon, please wait...");
+      coupon = await claimCoupon({
+        serviceUrl,
+        userAddress: config.address,
+        deviceId,
+        appId,
+      });
+      if (coupon?.ok) {
+        logInfo(`✅ Coupon claimed: ${coupon.tokenAmount} credits (tx: ${coupon.txHash})`);
+      } else if (coupon?.code === "ALREADY_CLAIMED") {
+        // status 和 claim 之间有人抢着领过(罕见 race),按已领处理
+        logInfo("Coupon already claimed (race with status check).");
+      } else if (coupon?.code === "CAMPAIGN_QUOTA_EXHAUSTED") {
+        logInfo("⚠️ Coupon campaign quota exhausted.");
+      } else if (coupon?.code === "MINT_FAILED") {
+        logInfo(`❌ Coupon mint failed: ${coupon.errorMsg}`);
+      } else if (coupon?.code === "CLAIM_NETWORK_ERROR") {
+        logInfo(`Coupon claim network error: ${coupon.errorMsg}`);
+      } else if (coupon?.code) {
+        logInfo(`Coupon claim skipped: ${coupon.code} — ${coupon.errorMsg || ""}`);
+      }
+    } else {
+      // status check 自己网络失败 — 静默,不阻塞 wallet-init
+      logInfo(`Coupon status check unreachable: ${status.errorMsg}`);
+      coupon = { ok: false, code: status.code, errorMsg: status.errorMsg };
+    }
+  }
+
   const data = {
     ready: true,
     created,
     appId,
     mode: config.mode || null,
     address: config.address || null,
+    deviceId,
     mainWallet: config.mainWallet || null,
     serviceUrl: config.serviceUrl || null,
     usdt,
@@ -106,6 +160,7 @@ export async function initWallet(opts) {
     minTopup: MIN_TOPUP_USDT,
     presets: TOPUP_PRESETS,
     chainCheck: chainCheckOk ? "ok" : { error: chainCheckError },
+    coupon,                 // null(未尝试) | { ok, code, tokenAmount?, txHash?, errorMsg? }
   };
   emitOk("wallet-init", data, data);
 }

package/src/config.mjs

@@ -5,6 +5,7 @@
  * AEON AI Gateway uses a single x402 service (ai-api.aeon.xyz).
  */
 import {readFileSync, writeFileSync, mkdirSync, chmodSync} from "fs";
+import {randomUUID} from "crypto";
 import {join} from "path";
 import {homedir} from "os";
 
@@ -24,6 +25,18 @@ export function loadConfig() {
     }
 }
 
+/**
+ * 读取或生成 deviceId(持久化到 config.json 复用)。
+ * 用于活动优惠券防刷审计 + 后端识别同设备多钱包。
+ */
+export function getOrCreateDeviceId() {
+    const cfg = loadConfig();
+    if (cfg.deviceId) return cfg.deviceId;
+    const deviceId = randomUUID();
+    saveConfig({...cfg, deviceId});
+    return deviceId;
+}
+
 export function saveConfig(config) {
     mkdirSync(CONFIG_DIR, {recursive: true});
     writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {mode: 0o600});