@aeon-ai-pay/aigateway 0.2.3 → 0.2.4

package/README.md

@@ -4,6 +4,26 @@
 >
 > **Zero API keys · Zero prepay · x402 protocol pay-per-call · Natural-language driven**
 
+---
+
+## 🚀 AEON x BNB Chain: AI Agent Campaign
+
+> **Your AI agent is ready to work — now let it pay.**
+
+AEON and **BNB Chain** are launching the **AI Agent Campaign**, opening up a native payment rail for autonomous AI agents on BNB Chain. With BNB assets, your agent can now call LLMs, APIs, skills, and compute resources — and settle instantly on-chain.
+
+**How it works**
+
+Agents pay with BNB-native assets through AEON's infrastructure. Every API call, every model inference, every skill invocation — settled seamlessly, no human in the loop.
+
+**🎁 First 1,000 users get $5 USDT in free credits** to start using AEON Skills and experience what agentic commerce actually feels like.
+
+Build agents that don't just think — but **transact**.
+
+→ **[Claim your $5 free credits (Google Form)](https://docs.google.com/forms/d/e/1FAIpQLSe8WF6-Y8Sh2AEC_hEGScyl_gQRahPYWPMDewdXJlfeVENENg/viewform?usp=publish-editor)** · Deploy your agent. Let it run.
+
+---
+
 `@aeon-ai-pay/aigateway` is a unified CLI + Agent Skill. Through a single session-key wallet and the [x402 protocol](https://www.x402.org/), it opens up SkillBoss's 200+ tool capabilities (image / video / audio / search / scraping / email / document / social data / UI generation, etc.) to AI Agents for pay-per-call invocation.
 
 ---

package/docs/env-vars.md

@@ -4,9 +4,8 @@ All environment variables that affect the `aigateway` CLI. Resolution priority f
 
 | Variable | Used by | Default | Purpose |
 | --- | --- | --- | --- |
-| `AIGATEWAY_SERVICE_URL` | All paid commands (`create-card`, `create-image`, `create-card-status`) | `https://ai-api.aeon.xyz` | Override the x402 service base URL. Useful for staging / local backends. |
+| `AIGATEWAY_SERVICE_URL` | All commands that talk to the gateway (`sb invoke`, `sb tools`, `wallet-init`, `wallet-topup`, `wallet-balance`) | `https://ai-api.aeon.xyz` | Override the x402 service base URL. Useful for staging / local backends. |
 | `EVM_PRIVATE_KEY` | All commands needing a session key | (read from config file) | Override the saved session key. Required when running in custodial / containerised mode where you don't want a config file on disk. **Treat as a secret.** |
-| `AICARD_LEGACY_NOOP` | — | — | Reserved. Not currently used. |
 
 ## Config file
 
@@ -26,22 +25,18 @@ All environment variables that affect the `aigateway` CLI. Resolution priority f
 - `privateKey` / `address` / `mode` — written by `wallet-init` when auto-generating a session key.
 - `mainWallet` — auto-recorded after a successful `wallet-topup` so `wallet-withdraw` can default to that address.
 
-## CLI flag priority example
+## Priority example
 
 ```bash
-# All four set, --service-url wins
-AIGATEWAY_SERVICE_URL=https://env.example.com \
-  aigateway create-card --amount 5 --service-url=...   # (no such flag now — env wins)
-
-# Only env set
-AIGATEWAY_SERVICE_URL=https://staging.example.com \
-  aigateway create-card --amount 5
+# Env var wins over config file
+AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \
+  aigateway sb invoke --model <id> --inputs '<json>'
 
 # Nothing set → built-in default https://ai-api.aeon.xyz
-aigateway create-card --amount 5
+aigateway sb invoke --model <id> --inputs '<json>'
 ```
 
-The `--service-url` CLI flag has been removed in 0.1.0+ — use the env var or edit the config file directly.
+There is no `--service-url` CLI flag — use the env var or edit the config file directly.
 
 ## Production hardening
 
@@ -60,11 +55,14 @@ aigateway wallet-init
 
 # Custodial server (key from Vault, no config file)
 EVM_PRIVATE_KEY=$(vault kv get -field=key merchants/acme-prod) \
-  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
 
 # Staging
 AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \
-  aigateway create-card --amount 5 --app-id YOUR_TEST_APPID --poll
+  aigateway sb tools --category image --app-id YOUR_TEST_APPID
 
 # Both
 AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \

package/docs/exit-codes.md

@@ -6,13 +6,13 @@ The `aigateway` CLI returns a stable exit code that maps to the category of outc
 | ---: | -------- | ------- |
 | `0` | Success | Command completed and produced an `ok: true` envelope. |
 | `1` | User error | Validation, configuration, balance, or user-side rejection. Caller should fix input and retry. |
-| `2` | Timeout | Polling, WalletConnect, signature, or on-chain wait exceeded its limit. The underlying operation may still complete asynchronously (e.g. card may still be provisioning). |
+| `2` | Timeout | Polling, WalletConnect, signature, or on-chain wait exceeded its limit. The underlying operation may still complete asynchronously. |
 | `3` | Service / network | Upstream service unavailable, network error, on-chain revert. Generally retryable after backoff. |
 | `4` | Internal | Unexpected internal error in the CLI. Please file an issue if reproducible. |
 
 ## Error Code Reference
 
-The full set of `error.code` values, grouped by exit code, is defined in [`src/error-codes.mjs`](../src/error-codes.mjs).
+The full set of `error.code` values is defined in [`src/error-codes.mjs`](../src/error-codes.mjs); the table below mirrors that file.
 
 ### Exit 1 — User Error
 
@@ -20,17 +20,25 @@ The full set of `error.code` values, grouped by exit code, is defined in [`src/e
 | ---- | ---- |
 | `WALLET_NOT_CONFIGURED` | No local wallet. Run `aigateway wallet-init`. |
 | `SERVICE_URL_MISSING` | Service URL not configured. |
-| `AMOUNT_INVALID` | Amount could not be parsed. |
-| `AMOUNT_OUT_OF_RANGE` | Amount outside `amountLimits.min` ~ `amountLimits.max`. |
-| `AMOUNT_EXCEEDS_BALANCE` | `withdraw --amount` exceeds available USDT. |
+| `AMOUNT_INVALID` | Amount could not be parsed (e.g. `wallet-topup --amount`, `--topup-amount`). |
+| `AMOUNT_EXCEEDS_BALANCE` | `wallet-withdraw --amount` exceeds available USDT. |
 | `INSUFFICIENT_USDT` | USDT balance still insufficient after funding. |
 | `INSUFFICIENT_BNB` | No BNB for approve / withdraw gas. |
-| `NO_FUNDS` | Session wallet has zero USDT and zero BNB. |
+| `NO_FUNDS` | Session wallet has zero USDT and zero BNB (withdraw context). |
 | `NO_MAIN_WALLET` | `wallet-withdraw` invoked without `--to` and no `mainWallet` in config. |
-| `MISSING_PROMPT` | `create-image` invoked without `--prompt`. |
-| `TOPUP_REQUIRED` | `wallet-topup` / `create-card` / `create-image` running non-TTY with `usdt < 1` and no amount argument. Choose from `error.presets` (5/10/20/50) and rerun (`topup --amount <n>` or pass `--topup-amount <n>` to `create-*`). |
-| `TOPUP_AMOUNT_TOO_SMALL` | `topup --amount` (or `create-* --topup-amount`) below `MIN_TOPUP_USDT` (5 USDT) or the per-call minimum (`error.minTopup`). |
+| `MISSING_MODEL` | `sb invoke` invoked without `--model`. |
+| `MISSING_INPUTS` | `sb invoke --inputs` is missing, or required fields are absent. `error.errors[]` lists which. |
+| `INVALID_INPUTS` | Inputs failed schema validation. `error.errors[].kind ∈ {enum, type, range}`. |
+| `INVALID_INPUTS_JSON` | `--inputs` could not be parsed as JSON. |
+| `INPUTS_FILE_NOT_FOUND` | `--inputs @path` file does not exist. |
+| `INVALID_MODEL_ID` | Catalog or server rejected the model id. |
+| `CATEGORY_NOT_FOUND` | `sb tools --category` argument not in the live catalog. |
+| `MODEL_PRICING_NOT_CONFIGURED` | Catalog lists the model but the gateway has no price entry yet. |
+| `INVALID_BODY` | Server rejected the request body shape. |
+| `TOPUP_REQUIRED` | Non-TTY context, USDT below the per-call minimum. Choose from `error.presets` (filtered to ≥ `error.minTopup`) and rerun the failing command with `--topup-amount <n>` (or `wallet-topup --amount <n>`). |
+| `TOPUP_AMOUNT_TOO_SMALL` | `--topup-amount` (or `topup --amount`) below `error.minTopup`. |
 | `PAYMENT_REJECTED` | User rejected the transaction in their wallet. |
+| `WALLET_ERROR` | Generic wallet operation failure (treated as user-resolvable). |
 
 ### Exit 2 — Timeout
 
@@ -38,9 +46,8 @@ The full set of `error.code` values, grouped by exit code, is defined in [`src/e
 | ---- | ---- |
 | `PAYMENT_TIMEOUT` | WalletConnect / signature request timed out (5 minutes). |
 | `WC_SESSION_EXPIRED` | WalletConnect session dropped mid-flow. |
-| `POLL_TIMEOUT` | `create-card-status --poll` exhausted attempts. Card may still be provisioning. |
-| `TX_TIMEOUT` | On-chain receipt wait exceeded 60 s. |
-| `UPDATE_APPLIED` | The CLI just upgraded itself synchronously to a newer version. The previous command was not executed — the caller (or the agent) must rerun it on the new version. Envelope carries `error.from` / `error.to` showing the version transition. |
+| `TX_TIMEOUT` | On-chain receipt wait exceeded its limit. |
+| `UPDATE_APPLIED` | The CLI just upgraded itself synchronously to a newer version. The previous command was **not executed** — the caller (or the agent) must rerun it on the new version. Envelope carries `error.from` / `error.to` showing the version transition. |
 
 ### Exit 3 — Service / Network
 
@@ -48,13 +55,15 @@ The full set of `error.code` values, grouped by exit code, is defined in [`src/e
 | ---- | ---- |
 | `SERVICE_UNAVAILABLE` | Generic upstream / network failure. |
 | `PAYMENT_FETCH_FAILED` | First 402 request to the service failed. |
+| `CATALOG_FETCH_FAILED` | `sb tools` could not fetch the catalog from the server. |
 | `BALANCE_CHECK_FAILED` | RPC query to BSC failed. |
 | `ALLOWANCE_CHECK_FAILED` | RPC `allowance()` query failed. |
 | `TX_REVERTED` | On-chain transaction reverted. |
 | `WITHDRAW_FAILED` | Withdraw transaction failed (revert / RPC). |
-| `APPROVE_FAILED` | `wallet-init` could not broadcast or confirm the facilitator `approve()` tx. |
+| `APPROVE_FAILED` | `wallet-topup` could not broadcast or confirm the facilitator `approve()` tx. |
 | `FUNDING_FAILED` | WalletConnect funding flow failed (non-timeout / non-reject path). |
-| `IMAGE_DOWNLOAD_FAILED` | Generated image URL returned a non-200 / timed out. |
+| `IMAGE_DOWNLOAD_FAILED` | Generated image URL returned a non-200 / timed out. (Legacy alias; `sb invoke` now also emits `DOWNLOAD_FAILED` for non-image artifacts.) |
+| `DOWNLOAD_FAILED` | `sb invoke` could not save a binary artifact (image / video / audio) to disk. The upstream URL is still available in `data.downloaded[].url`. |
 | `INVALID_PAYMENT_AMOUNT` | Service returned a 402 with `amount === 0`. |
 | `PAYMENT_FAILED` | Service rejected the signed payment request. |
 
@@ -63,4 +72,5 @@ The full set of `error.code` values, grouped by exit code, is defined in [`src/e
 | Code | When |
 | ---- | ---- |
 | `INTERNAL_ERROR` | Unexpected error inside the CLI. |
-| `WALLET_ERROR` | Generic non-classified WalletConnect failure. (Exit 1 — treated as user-resolvable.) |
+
+> Note: `WALLET_ERROR` is defined alongside the timeout block in `error-codes.mjs` but its exit code is `1` (user-resolvable), so it appears under Exit 1 above.

package/docs/ide-setup.md

@@ -55,6 +55,6 @@ For Claude Code, OpenClaw, Gemini CLI, GitHub Copilot, and 30+ others, the [skil
 
 After installation, in your IDE chat say:
 
-> Create me a $5 virtual card.
+> Generate me an image of a cyberpunk fox.
 
-The agent should propose running `aigateway wallet-init` (one-time, auto-creates a wallet) followed by `aigateway create-card --amount 5 --poll`. If it doesn't, the rule file isn't being picked up — check that the file path matches what your IDE expects and that the IDE has been restarted.
+The agent should propose running `aigateway wallet-init` (one-time, auto-creates a wallet), then `aigateway sb tools --category image` to pick a model, then `aigateway sb invoke --model <id> --inputs '{"prompt":"cyberpunk fox"}'`. If it doesn't, the rule file isn't being picked up — check that the file path matches what your IDE expects and that the IDE has been restarted.

package/docs/output-schema.md

@@ -1,6 +1,6 @@
 # Output Schema
 
-Every `aigateway` command emits **exactly one line of JSON** to **stdout** —— the *envelope*. Human-readable progress logs go to **stderr** and can be safely ignored by programmatic consumers.
+Every `aigateway` command emits **exactly one line of JSON** to **stdout** — the *envelope*. Human-readable progress logs go to **stderr** and can be safely ignored by programmatic consumers.
 
 > Pass `--quiet` to suppress non-error stderr. Pass `--legacy-output` to fall back to the pre-envelope shape (see [Legacy mode](#legacy-mode)).
 
@@ -11,8 +11,8 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 ```json
 {
   "ok": true,
-  "command": "create",
-  "version": "0.9.0",
+  "command": "sb-invoke",
+  "version": "x.y.z",
   "data": { /* command-specific payload */ }
 }
 ```
@@ -22,20 +22,21 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 ```json
 {
   "ok": false,
-  "command": "create",
-  "version": "0.9.0",
+  "command": "sb-invoke",
+  "version": "x.y.z",
   "error": {
-    "code": "AMOUNT_OUT_OF_RANGE",
-    "message": "Amount must be at least $0.6. Allowed range: $0.6 ~ $800 USD.",
-    "min": 0.6,
-    "max": 800
+    "code": "MISSING_INPUTS",
+    "message": "Inputs validation failed for ...",
+    "errors": [{ "field": "prompt", "kind": "missing", "message": "..." }],
+    "required": ["prompt"],
+    "properties": ["prompt", "aspect_ratio", "num_outputs"]
   }
 }
 ```
 
 - `error.code` is a stable identifier from [`src/error-codes.mjs`](../src/error-codes.mjs) — see [exit-codes.md](./exit-codes.md) for the full list.
 - `error.message` is human-readable and may change between versions; **do not** match on it for control flow.
-- Additional fields under `error` are command-specific context (e.g. `min` / `max` / `address` / `required` / `available`).
+- Additional fields under `error` are command-specific context (e.g. `min` / `max` / `address` / `required` / `available` / `errors[]` / `presets`).
 
 ## Per-Command `data` Payloads
 
@@ -49,8 +50,14 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
   "mode": "private-key",
   "address": "0x...",
   "mainWallet": "0x..." | null,
-  "serviceUrl": "https://...",
-  "amountLimits": { "min": 0.6, "max": 800 }
+  "usdt": "5.0",
+  "bnb": "0.0003",
+  "allowance": "115792...max" | "0",
+  "needsTopup": false,
+  "topupReason": null | "first_time" | "low_balance" | "no_approve" | "chain_check_failed",
+  "minTopup": 5,
+  "presets": [5, 10, 20, 50],
+  "serviceUrl": "https://..."
 }
 ```
 
@@ -70,72 +77,80 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 }
 ```
 
-### `create-card`
+### `sb invoke`
 
 ```json
 {
-  "appId": "TEST000001",
-  "orderNo": "...",
-  "data": { /* sanitized server response */ },
-  "paymentResponse": { /* decoded PAYMENT-RESPONSE header */ },
-  "pollResult": { /* present when --poll succeeds */ }
+  "model": "replicate/black-forest-labs/flux-schnell",
+  "inputs": { "prompt": "...", "aspect_ratio": "1:1" },
+  "transaction": "0x..." | null,
+  "downloaded": [
+    {
+      "url": "https://...",
+      "localPath": "/home/.../aigateway-images/...png",
+      "format": "png",
+      "width": 1024,
+      "height": 1024,
+      "sizeBytes": 412345,
+      "sizeHuman": "402.7 KB"
+    }
+  ],
+  "raw": { /* upstream vendor response, unwrapped from { payer, transaction, data } */ },
+  "paymentResponse": { "txHash": "0x...", "payer": "0x...", "...": "..." },
+  "balance": {
+    "initial": "5.0",
+    "before": "5.0",
+    "after": "4.99",
+    "charged": 0.01,
+    "topup": null | "5"
+  }
 }
 ```
 
-### `create-image`
+- **Binary outputs** (image / video / audio) populate `downloaded[]`. With `--raw` the auto-download is skipped and `downloaded[]` stays empty; the URLs live in `raw`.
+- **JSON-only outputs** (search, scraper, social_data, email, etc.) leave `downloaded` empty; consumers read `raw`.
+- `balance.charged` is the live USDT amount taken for this call (computed server-side as `priceUnit × inputs usage`).
+
+Failure shapes carry extra fields per code, e.g.:
 
 ```json
 {
-  "appId": "TEST000001",
-  "prompt": "...",
-  "aspectRatio": "16:9",
-  "outputFormat": "png",
-  "model": "...",
-  "transaction": "0x...",
-  "images": [
-    { "url": "https://...", "localPath": "/.../...png", "format": "png", "width": 1024, "height": 576, "sizeBytes": 123456, "sizeHuman": "120.6 KB" }
-  ],
-  "balance": { "initial": "5", "before": "5", "after": "4.99", "charged": 0.01, "topup": null }
+  "ok": false,
+  "command": "sb-invoke",
+  "error": {
+    "code": "TOPUP_REQUIRED",
+    "message": "USDT balance is below the 5 USDT minimum...",
+    "minTopup": 5,
+    "required": 0.01,
+    "currentBalance": "0",
+    "address": "0x...",
+    "presets": [5, 10, 20, 50],
+    "hint": "Rerun: aigateway wallet-topup --amount <usdt> --app-id ..."
+  }
 }
 ```
 
-**Dry-run (`--dry-run`)** — preflight checks complete but no signing/transaction occurs:
+### `sb tools`
 
-```json
-{
-  "dryRun": true,
-  "url": "...",
-  "paymentRequirements": { "amountUsdt": 0.66, "amountWei": "660000000000000000", "asset": "0x...", "payTo": "0x...", "orderNo": "..." },
-  "wallet": { "address": "0x..." },
-  "decision": { "needTopup": true, "needGas": false, "topupAmount": "0.660000" },
-  "will": ["fund_usdt_via_walletconnect", "approve_or_skip", "sign_payment_eip712", "submit_to_facilitator", "poll_status"]
-}
-```
+`data` shape depends on the filters supplied:
 
-### `create-card-status`
+| Invocation | `data.mode` | Shape |
+| --- | --- | --- |
+| `sb tools` | (absent) | Full catalog: `{ categories: [{ key, agentTrigger, defaultInputsSchema, models: [...] }], version, ... }` |
+| `sb tools --model <id>` | `"single-model"` | `{ category: "<key>", model: { id, vendor, useCase, price, priceUnit, tier, inputsOverride? }, effectiveSchema: { ... } }` |
+| `sb tools --category <key>` | `"single-category"` | `{ category: { key, agentTrigger, defaultInputsSchema, models: [...] } }` |
+| `sb tools --tier <t>` (alone) | `"tier-filtered"` | Full catalog with each category's `models[]` filtered to `tier === t`, plus `tier: "<t>"` |
 
-```json
-{
-  "success": true,
-  "model": {
-    "orderNo": "...",
-    "orderStatus": "SUCCESS" | "FAIL" | "PROCESSING" | "...",
-    "channelStatus": "...",
-    "cardStatus": "ACTIVE" | "PENDING" | "...",
-    "cardScheme": "VISA" | "MASTERCARD",
-    "cardNumber": "•••• 1234",
-    "...": "(sensitive fields like CVV / expiry are stripped)"
-  }
-}
-```
+`effectiveSchema` = `model.inputsOverride ?? category.defaultInputsSchema` — the JSON-schema-shaped object that `sb invoke` validates against client-side.
 
-### `wallet`
+### `wallet-balance`
 
 ```json
 {
   "mode": "private-key",
   "address": "0x...",
   "usdt": "12.34",
+  "bnb": "0.0003",
   "network": "BSC Mainnet (Chain ID: 56)",
   "mainWallet": { "address": "0x...", "usdt": "..." }
 }
@@ -182,7 +197,7 @@ Every `aigateway` command emits **exactly one line of JSON** to **stdout** —
 For consumers still parsing the pre-envelope JSON shape, pass `--legacy-output` to get the old format on stdout (and errors on **stderr** as before):
 
 ```bash
-aigateway --legacy-output create-card --amount 5
+aigateway --legacy-output wallet-balance
 ```
 
-Legacy mode is kept for one or two minor releases as a migration aid. New integrations should use the envelope.
+Legacy mode is kept as a migration aid. New integrations should use the envelope.

package/docs/recipes/cron-issue-cards.md

@@ -1,31 +1,38 @@
-# Recipe — Schedule Recurring Card Issuance
+# Recipe — Schedule Recurring Paid Invocations
 
-Use this when an agent needs to issue cards on a schedule — for example, "create a $5 card every Monday at 09:00 to seed an autonomous shopping flow."
+> Filename kept for backwards compatibility. The earlier "issue card" workflow has been folded into the unified `aigateway sb invoke` entry point; this recipe now covers any scheduled paid call.
+
+Use this when an agent or automation needs to invoke a paid AI tool on a schedule — for example, "generate a marketing image every Monday at 09:00", "transcribe yesterday's recordings nightly", "run a search summarisation every hour".
 
 ## Prerequisites
 
 1. **Pre-funded session wallet.** WalletConnect requires a browser; cron jobs run headless. Top up the local wallet manually first:
    ```bash
-   aigateway wallet-topup --amount 50    # adds USDT + a tiny amount of BNB for approve gas
+   aigateway wallet-topup --amount 50    # adds USDT + a tiny amount of BNB for the one-time approve
    ```
-2. **One-time `approve`.** Run `aigateway create-card --amount 0.6 --poll` once interactively so the approve transaction is on-chain. Subsequent creates won't need WalletConnect again until USDT is depleted.
+2. **Approve already broadcast.** `wallet-topup` performs the one-time `ERC20.approve(facilitator, MaxUint256)`. After it succeeds, all subsequent `sb invoke` calls are gasless EIP-712 signing — no WalletConnect needed until USDT is depleted.
+3. **Catalog sanity-check.** Before scheduling, run `aigateway sb tools --model <id>` once to confirm the model id is valid and to learn its `effectiveSchema` (so your wrapper builds the correct `--inputs`).
 
 ## A Minimal Wrapper Script
 
-`~/bin/issue-card.sh`:
+`~/bin/invoke-tool.sh`:
 
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
 
-AMOUNT="${1:-5}"
+MODEL="${1:?model id required}"
+INPUTS_FILE="${2:?path to inputs JSON required}"     # e.g. ~/aigateway/jobs/daily-image.json
 LOG_DIR="${HOME}/.aigateway/logs"
 mkdir -p "$LOG_DIR"
 TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
-LOG="$LOG_DIR/issue-${TS}.log"
+LOG="$LOG_DIR/invoke-${TS}.log"
 
 # Capture envelope on stdout; quiet stderr noise
-ENVELOPE=$(aigateway --quiet create-card --amount "$AMOUNT" --poll 2>"$LOG")
+ENVELOPE=$(aigateway --quiet sb invoke \
+  --model "$MODEL" \
+  --inputs "@${INPUTS_FILE}" \
+  2>"$LOG")
 EXIT=$?
 
 echo "$ENVELOPE" > "${LOG%.log}.json"
@@ -37,19 +44,26 @@ if [ "$EXIT" -ne 0 ]; then
   exit "$EXIT"
 fi
 
-ORDER=$(echo "$ENVELOPE" | jq -r '.data.orderNo')
-echo "[$(date -u)] OK orderNo=$ORDER amount=$AMOUNT"
+TX=$(echo "$ENVELOPE" | jq -r '.data.transaction // "—"')
+FIRST=$(echo "$ENVELOPE" | jq -r '.data.downloaded[0].localPath // empty')
+echo "[$(date -u)] OK tx=$TX file=${FIRST:-n/a} model=$MODEL"
 ```
 
 ```bash
-chmod +x ~/bin/issue-card.sh
+chmod +x ~/bin/invoke-tool.sh
 ```
 
 ## Cron Entry
 
 ```cron
 # minute hour dom mon dow  command
-  0      9    *   *   1   /Users/me/bin/issue-card.sh 5 >> /Users/me/.aigateway/logs/cron.log 2>&1
+  0      9    *   *   1   /Users/me/bin/invoke-tool.sh replicate/black-forest-labs/flux-schnell /Users/me/aigateway/jobs/weekly-image.json >> /Users/me/.aigateway/logs/cron.log 2>&1
+```
+
+Example `weekly-image.json`:
+
+```json
+{ "prompt": "neon city skyline at dusk, hyper-detailed", "aspect_ratio": "16:9" }
 ```
 
 > ⚠️ On macOS, `cron` may lack PATH access to `aigateway`. Use an absolute path (`/Users/me/.nvm/versions/node/v25/bin/aigateway`) or source your shell rc inside the wrapper.
@@ -58,12 +72,16 @@ chmod +x ~/bin/issue-card.sh
 
 | Code | Likely cause in cron context | Fix |
 | ---- | ---------------------------- | --- |
-| `INSUFFICIENT_USDT` | Wallet ran dry. | Top up via `aigateway wallet-init` on a workstation. |
-| `INSUFFICIENT_BNB` | Approve allowance expired or BNB depleted by retries. | Run `aigateway wallet-gas` to add a small amount. |
-| `PAYMENT_TIMEOUT` | WalletConnect was triggered (unexpected — should be fully approved). | Run an interactive `aigateway wallet-init` once to refresh allowance. |
-| `SERVICE_UNAVAILABLE` | Upstream outage. | Cron will retry next tick. Alert if 3+ consecutive failures. |
+| `INSUFFICIENT_USDT` / `TOPUP_REQUIRED` | Wallet ran dry. Headless cron cannot scan a QR. | Top up via `aigateway wallet-topup --amount <n>` on a workstation. |
+| `INSUFFICIENT_BNB` | BNB depleted (only matters for `wallet-withdraw` / re-approve). | Run `aigateway wallet-gas` interactively on a workstation. |
+| `INVALID_MODEL_ID` | The model id was renamed or removed upstream. | Run `aigateway sb tools` and update the wrapper's `--model`. |
+| `MISSING_INPUTS` / `INVALID_INPUTS` | Inputs file drifted from the schema (e.g. missing `duration_seconds` for video / `duration_minutes` for STT). | Re-pull `sb tools --model <id>` and fix the JSON. |
+| `MODEL_PRICING_NOT_CONFIGURED` | Upstream removed the model from the pricing config. | Pick another model. |
+| `SERVICE_UNAVAILABLE` / `PAYMENT_FETCH_FAILED` | Upstream outage. | Cron will retry next tick. Alert if 3+ consecutive failures. |
+| `PAYMENT_TIMEOUT` | WalletConnect was unexpectedly triggered (should not happen once approve is on-chain). | Run an interactive `aigateway wallet-topup` once to re-fund / re-approve. |
 
 ## See Also
 
 - [integrate-in-agent.md](./integrate-in-agent.md) — Node.js / Python subprocess wrapper.
 - [error-recovery.md](./error-recovery.md) — Full code-by-code recovery table.
+- [../output-schema.md](../output-schema.md) — `sb invoke` envelope fields used above (`transaction`, `downloaded[]`, `balance`).

package/docs/recipes/error-recovery.md

@@ -6,25 +6,40 @@ Map each `error.code` returned by the envelope to a concrete recovery action. Us
 | ------------ | :--: | -------------------- |
 | `WALLET_NOT_CONFIGURED` | 1 | Run `aigateway wallet-init` once (auto-creates a local session wallet). |
 | `SERVICE_URL_MISSING` | 1 | Override via env `AIGATEWAY_SERVICE_URL`. The default service URL is wired into the CLI for production; this should never trigger in normal use. |
-| `AMOUNT_INVALID` | 1 | Caller bug — input must be a numeric string. |
-| `AMOUNT_OUT_OF_RANGE` | 1 | Re-prompt user with `error.min` ~ `error.max`. Do **not** silently clamp. |
-| `AMOUNT_EXCEEDS_BALANCE` | 1 | Use the smaller of requested vs. `error.available`. |
-| `INSUFFICIENT_USDT` | 1 | Top-up failed or partial. Surface `error.required` / `error.available` to user, ask whether to retry with a new amount. |
-| `INSUFFICIENT_BNB` | 1 | Run `aigateway wallet-gas` to top up a small amount of BNB via WalletConnect, then retry. |
-| `NO_FUNDS` | 1 | Nothing to withdraw. Inform the user, possibly suggest `wallet-topup`. |
-| `NO_MAIN_WALLET` | 1 | Caller must pass `--to <address>`. |
+| `AMOUNT_INVALID` | 1 | Caller bug — input must be a positive numeric string (used by `wallet-topup`, `wallet-gas`, `wallet-withdraw`, `--topup-amount`). |
+| `AMOUNT_EXCEEDS_BALANCE` | 1 | `wallet-withdraw --amount` exceeded available USDT. Use the smaller of requested vs. `error.available`. |
+| `INSUFFICIENT_USDT` | 1 | Top-up failed or the chosen `--topup-amount` was still below the call's required USDT. Surface `error.required` / `error.available`; ask the user to retry with a larger top-up. |
+| `INSUFFICIENT_BNB` | 1 | Approve / withdraw needs BNB for gas. Run `aigateway wallet-gas` (WalletConnect, must be interactive), then retry. |
+| `NO_FUNDS` | 1 | Nothing to withdraw. Inform the user; suggest `wallet-topup` if relevant. |
+| `NO_MAIN_WALLET` | 1 | `wallet-withdraw` invoked with no `mainWallet` saved. Re-run with `--to <address>`. |
+| `MISSING_MODEL` | 1 | `sb invoke --model` is required. Run `aigateway sb tools` to pick one. |
+| `MISSING_INPUTS` | 1 | `sb invoke --inputs` is required, or the JSON is missing required fields. `error.errors[]` lists which fields are missing; `error.required[]` lists all required keys for the model. |
+| `INVALID_INPUTS` | 1 | Inputs failed schema validation. `error.errors[]` items carry `{ field, kind, message }` where `kind ∈ {enum, type, range}`. Fix and retry. |
+| `INVALID_INPUTS_JSON` | 1 | `--inputs` could not be parsed as JSON. Check quoting / escaping; on shells use `JSON.stringify(...)` from your wrapper. |
+| `INPUTS_FILE_NOT_FOUND` | 1 | `--inputs @path` file does not exist. Resolve to an absolute path or correct the caller. |
+| `INVALID_MODEL_ID` | 1 | Server / catalog rejected the model id. Run `aigateway sb tools --category <key>` to find a valid one. |
+| `CATEGORY_NOT_FOUND` | 1 | `sb tools --category` argument is not in the live catalog. Run `aigateway sb tools` (no filter) to list categories. |
+| `MODEL_PRICING_NOT_CONFIGURED` | 1 | The catalog lists the model but the gateway has no price entry yet. Pick another model or ask the operator to add it. |
+| `INVALID_BODY` | 1 | Server rejected the request body shape. Usually a CLI / catalog drift; file a bug. |
+| `TOPUP_REQUIRED` | 1 | Non-TTY context, USDT below the per-call minimum. Choose from `error.presets` (filtered to ≥ `error.minTopup`) and rerun the failing command with `--topup-amount <n>`. |
+| `TOPUP_AMOUNT_TOO_SMALL` | 1 | `--topup-amount` (or `topup --amount`) below `error.minTopup`. Rerun with a larger value. |
 | `PAYMENT_REJECTED` | 1 | User cancelled in their wallet. **Do not auto-retry** — ask user first. |
-| `PAYMENT_TIMEOUT` | 2 | WalletConnect approval expired (5 min). Ask user whether to retry. **Do not auto-retry.** |
-| `WC_SESSION_EXPIRED` | 2 | Reconnect required. Re-run the original command. |
-| `POLL_TIMEOUT` | 2 | Card may still provision. Surface `error.orderNo` and query later with `aigateway create-card-status --order-no <n>`. |
-| `TX_TIMEOUT` | 2 | The on-chain transfer is likely still pending — query the chain or retry the status command. |
+| `PAYMENT_TIMEOUT` | 2 | WalletConnect approval window expired (5 min). Ask user whether to retry. **Do not auto-retry.** |
+| `WC_SESSION_EXPIRED` | 2 | WalletConnect relay dropped the session. Re-run the original command. |
+| `TX_TIMEOUT` | 2 | The on-chain transfer is likely still pending. Wait, then re-check with `wallet-balance`. |
+| `UPDATE_APPLIED` | 2 | CLI just upgraded itself synchronously. The previous command was **not executed**. Surface `error.from` → `error.to` and **rerun the same command verbatim** on the new version. |
 | `SERVICE_UNAVAILABLE` | 3 | Exponential backoff: 1 s → 4 s → 16 s, max 3 attempts. |
-| `PAYMENT_FETCH_FAILED` | 3 | Same as above. Check network connectivity. |
+| `PAYMENT_FETCH_FAILED` | 3 | First 402 probe failed. Backoff + retry; check network connectivity. |
+| `CATALOG_FETCH_FAILED` | 3 | `sb tools` could not reach the server. Retry once; if it persists, `sb invoke` still runs (server-side validation is the safety net). |
 | `BALANCE_CHECK_FAILED` | 3 | BSC RPC hiccup. Retry once after 2 s. |
+| `ALLOWANCE_CHECK_FAILED` | 3 | BSC RPC hiccup. Retry once after 2 s. |
 | `TX_REVERTED` | 3 | On-chain failure. Capture `error.message` for diagnosis; do not retry blindly. |
 | `WITHDRAW_FAILED` | 3 | Withdraw transaction failed. Check `aigateway wallet-balance` and retry. |
+| `APPROVE_FAILED` | 3 | One-time facilitator approve failed during `wallet-topup`. Inspect the tx; retry the top-up. |
 | `INVALID_PAYMENT_AMOUNT` | 3 | Server-side issue (returned amount = 0). Retry after a short delay. |
-| `PAYMENT_FAILED` | 3 | Service rejected the signed request. Surface `error.data` to the user / log. |
+| `PAYMENT_FAILED` | 3 | Service rejected the signed payment request. Surface `error.data` / `error.status` to the user / log. On 5xx, retry once. |
+| `IMAGE_DOWNLOAD_FAILED` / `DOWNLOAD_FAILED` | 3 | The paid call succeeded but the local download failed. The original URL is still in the upstream response — surface it from `data.downloaded[].url` (when available) or re-fetch via `--raw`. **Do not re-invoke the model** (you'd pay again). |
+| `FUNDING_FAILED` | 3 | Non-timeout / non-reject failure in the WalletConnect funding flow. Re-run `wallet-topup`. |
 | `INTERNAL_ERROR` | 4 | File a bug. Don't retry. |
 | `WALLET_ERROR` | 1 | Generic wallet failure. Surface to user, ask whether to retry. |
 
@@ -41,13 +56,29 @@ async function withRetry(fn, { codes, attempts = 3, baseDelayMs = 1000 } = {}) {
 }
 
 // Only retry transient service/network errors
-await withRetry(() => runAEON AI Gateway(["create", "--amount", "5", "--poll"]), {
-  codes: ["SERVICE_UNAVAILABLE", "PAYMENT_FETCH_FAILED", "BALANCE_CHECK_FAILED", "INVALID_PAYMENT_AMOUNT"],
-});
+await withRetry(
+  () => runAigateway([
+    "sb", "invoke",
+    "--model", "replicate/black-forest-labs/flux-schnell",
+    "--inputs", JSON.stringify({ prompt: "a cyberpunk fox" }),
+  ]),
+  {
+    codes: [
+      "SERVICE_UNAVAILABLE",
+      "PAYMENT_FETCH_FAILED",
+      "CATALOG_FETCH_FAILED",
+      "BALANCE_CHECK_FAILED",
+      "ALLOWANCE_CHECK_FAILED",
+      "INVALID_PAYMENT_AMOUNT",
+    ],
+  },
+);
 ```
 
 ## Anti-patterns
 
 - ❌ Don't retry `PAYMENT_REJECTED` or `PAYMENT_TIMEOUT` automatically — the user actively cancelled or walked away.
+- ❌ Don't retry `IMAGE_DOWNLOAD_FAILED` / `DOWNLOAD_FAILED` by re-invoking the model — the paid call already settled, you'd be charged again. Re-fetch the URL or re-run with `--raw`.
 - ❌ Don't match on `error.message` text — messages may change between versions. Match on `error.code`.
 - ❌ Don't ignore exit code in favour of envelope. Stack-level proxies sometimes mangle stdout; the exit code is a redundant safety net.
+- ❌ Don't paper over `UPDATE_APPLIED` by treating it as a generic timeout — it's a "new binary; rerun me" signal, not a failure.