@aeon-ai-pay/aigateway 0.2.2 → 0.2.4

package/README.md

@@ -1,115 +1,285 @@
 # AEON AI Gateway
 
-> AI Agents discover, invoke, and settle paid LLMs, APIs, and Skills — starting with **Skill Boss**.
+> **Co-presented by AEON & SkillBoss** — AI Agents pay per-call in USDT on BSC to invoke 200+ AI tool capabilities.
 >
-> **No manual key setup. No prepayment. Pay-per-call via x402 or Agent Card.**
+> **Zero API keys · Zero prepay · x402 protocol pay-per-call · Natural-language driven**
 
-A unified CLI + agent skill that lets an AI agent **purchase virtual debit cards** *and* **invoke AI services (image generation via Skill Boss)** in the same wallet, paid per-call with USDT on BSC via the [x402 protocol](https://www.x402.org/).
+---
 
-Published as `@aeon-ai-pay/aigateway` (CLI: `aigateway`).
+## 🚀 AEON x BNB Chain: AI Agent Campaign
 
-## Install Skill
+> **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.
+
+---
+
+## About SkillBoss
+
+**SkillBoss** is a unified AI API + Agent Skills platform — a single API Key gives you access to models and tool capabilities from multiple providers, covering chat & reasoning, search, web scraping, image generation, video generation, audio, document processing, email, data services, and website / full-stack app deployment. Native support for Claude Code, Codex, Cursor, Windsurf, and other AI Agent tools.
+
+| Dimension | Data |
+| --- | --- |
+| **Public API endpoints** | 359 |
+| **Service providers** | 50 |
+| **Official Skill packages** | 1 main + 4 sub: `skillboss` / `skillboss-image` / `skillboss-video` / `skillboss-marketing` / `skillboss-cold-email` |
+| **Skills Marketplace** | 500+ ready-to-use skills |
+
+**Full capability surface**: LLM / Chat · Embedding · Search · Scraping · Image · Video · Audio (TTS / STT) · Document · Social / Business Data · Email · Finance / Utility · Platform / Storage · Marketing / Cold Email · Full-stack App / Website Build & Deploy
+
+### SkillBoss Resources
+
+| Entry | URL |
+| --- | --- |
+| API web catalog | https://www.skillboss.co/docs/api-catalog |
+| API JSON catalog | https://www.skillboss.co/api-catalog.json |
+| Skills marketplace | https://www.skillboss.co/skills |
+| Skills index API | https://www.skillboss.co/api/skills/index |
+| Skills search API | https://www.skillboss.co/api/skills/search |
+| Agent install entry | https://www.skillboss.co/skill.md |
+
+---
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  AI Agent (Claude Code / Cursor / Codex / Windsurf / ...) │
+└────────────────────┬───────────────────────────────────────┘
+                     │ natural-language instructions
+                     ▼
+┌────────────────────────────────────────────────────────────┐
+│  aigateway CLI (@aeon-ai-pay/aigateway)                    │
+│   sb tools  ──→ server catalog (model + tier + schema)     │
+│   sb invoke ──→ client-side inputs validation              │
+│              ──→ x402 phase 1 (402 response: live price)   │
+│              ──→ EIP-712 signing (session key, gasless)    │
+│              ──→ auto-download image / video / audio       │
+└────────────────────┬───────────────────────────────────────┘
+                     │ HTTP + x402
+                     ▼
+┌────────────────────────────────────────────────────────────┐
+│  AEON x402 Gateway (ai-api.aeon.xyz)                       │
+│   dynamic pricing by model.priceUnit × usage               │
+│   proxies calls to SkillBoss upstream                      │
+└────────────────────┬───────────────────────────────────────┘
+                     │
+                     ▼
+┌────────────────────────────────────────────────────────────┐
+│  SkillBoss (api.skillboss.co)                              │
+│   50 vendors · 359 endpoints                               │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Capability Categories
+
+| Category | Pricing Unit | Description |
+| --- | --- | --- |
+| `image` | `per_image` | Image generation / editing / upscaling / background removal |
+| `video` | `per_second` | Video generation (requires `duration_seconds`) |
+| `tts` | `per_1k_chars` | Text-to-speech / sound effect generation |
+| `stt` | `per_minute` | Speech-to-text (requires `duration_minutes`) |
+| `search` | `per_request` | Web search / map search |
+| `scraper` | `per_request` | Web scraping / structured extraction |
+| `social_data` | `per_request` | Social / business data |
+| `sms` | `per_request` | SMS / OTP / email verification |
+| `document` | `per_request` | Document parsing (PDF / DOCX → Markdown) |
+| `ui_generation` | `per_request` | UI / prototype / slide deck generation |
+| `embeddings` | `per_million_tokens` | Text embedding vectors |
+| `financial` | `per_request` | Stock / forex / crypto / financial news |
+| `news` | `per_request` | News APIs |
+| `utility` | `per_request` | Domain / QR code / geo / dictionary and other utility APIs |
+
+### Querying models at runtime
+
+```bash
+# Fetch the full catalog
+aigateway sb tools
+
+# Filter by category
+aigateway sb tools --category image
+aigateway sb tools --category video
+
+# Filter by tier (price percentile within a category: price / balanced / quality)
+aigateway sb tools --tier price
+aigateway sb tools --category image --tier quality
+
+# Look up a single model (with effectiveSchema)
+aigateway sb tools --model <model_id>
+```
+
+Response shape: `categories[].models[]`. Each model carries `id` / `vendor` / `useCase` / `price` / `priceUnit` / `tier` / optional `inputsOverride`. Each category carries `agentTrigger` / `defaultInputsSchema`.
+
+---
+
+## Prerequisites
+
+- Node.js ≥ 25
+- A WalletConnect-compatible mobile wallet (MetaMask / OKX Wallet / Trust Wallet, etc.)
+- Your main wallet holds USDT (BEP-20) plus a small amount of BNB (for the first-time approve gas, ~$0.002)
+
+---
+
+## Installation
+
+### Step 1: Install the CLI (npm)
 
 ```bash
-# Install to all detected agents (Claude Code, Cursor, Codex, OpenClaw, Gemini CLI, etc.)
-npx skills add AEON-Project/aigateway -g -y
+npm install -g @aeon-ai-pay/aigateway
 
-# Install to specific agents
-npx skills add AEON-Project/aigateway -a claude-code -a cursor -a codex -g -y
+# Verify
+aigateway --version
 ```
 
-Supported agents: Claude Code, Cursor, Codex, OpenClaw, Gemini CLI, GitHub Copilot, Windsurf, Roo Code, and [39+ more](https://agentskills.io).
+### Step 2: Install the Agent Skill (optional, for repair)
 
-## One-Glance Flow
+When you run `npm install -g`, the `postinstall` script already installs the skill into all detected agents. If something was missed, install it manually:
 
+```bash
+npx skills add AEON-Project/aigateway -g -y                                # install into all detected agents
+npx skills add AEON-Project/aigateway -a claude-code -a cursor -a codex -g -y   # install into specific agents
 ```
-aigateway wallet-init            # 1. auto-create local session wallet (pure local, no QR)
-aigateway wallet-topup --amount 5       # 2. WalletConnect: USDT top-up + one-time facilitator approve
-aigateway create-card --amount 5 # 3a. paid call: $5 virtual card via x402
-aigateway create-image --prompt "cyberpunk fox"  # 3b. paid call: AI image via x402
+
+Supported: Claude Code, Cursor, Codex, OpenClaw, Gemini CLI, GitHub Copilot, Windsurf, Roo Code, [39+ more](https://agentskills.io).
+
+### Step 3: Initialize the wallet
+
+```bash
+aigateway wallet-init   # generates the session key at ~/.aigateway/config.json and prints address + balance
 ```
 
-Step 2 covers the **only** manual moment — scanning a WalletConnect QR with your phone wallet to load ≥5 USDT once. Every subsequent paid call is a gasless EIP-712 signature against the local session key.
+### Step 4: First-time top-up (one-time)
+
+```bash
+aigateway wallet-topup --amount 5
+```
 
-## CLI Commands
+After scanning the WalletConnect QR code, the main wallet signs 2 transactions: transfer USDT + a small amount of BNB to the session key; the session key then broadcasts a one-time `ERC20.approve(facilitator, MaxUint256)`. After that, `sb invoke` is fully gasless EIP-712 signing end-to-end.
 
-Every command accepts `--app-id <id>` (merchant identifier, default `TEST000001`). Every command emits a JSON *envelope* on stdout (`{ ok, command, version, data | error }`).
+### Step 5: Invoke SkillBoss tools
 
-| Command | Description | Key Options |
+```bash
+aigateway sb tools --category image                                # browse available models
+aigateway sb invoke --model <model_id> --inputs '{"prompt":"..."}' # invoke
+```
+
+Images / videos / audio are auto-downloaded into `~/aigateway-{images,videos,audio}/`.
+
+---
+
+## CLI Command Reference
+
+Every command accepts `--app-id <id>` (merchant ID, defaults to `TEST000001`) and emits a single JSON envelope line to stdout: `{ ok, command, version, data | error }`.
+
+| Command | Description | Key flags |
 | --- | --- | --- |
-| `wallet-init` | Check / create the local session wallet (pure local — no QR, no on-chain) | `--app-id <id>` |
-| `wallet-topup` | WalletConnect USDT top-up (≥5 USDT, presets 5/10/20/50) + one-time facilitator approve | `--amount <usdt>`, `--app-id <id>`, `--private-key <key>` |
-| `create-card` | Issue a one-time virtual Visa/Mastercard ($0.6 ~ $800) | `--amount <usd>` (required), `--app-id <id>`, `--poll`, `--dry-run`, `--topup-amount <usdt>` |
-| `create-image` | Generate an AI image via Skill Boss | `--prompt <text>` (required), `--app-id <id>`, `--aspect-ratio`, `--output-format`, `--model`, `--output <dir>`, `--topup-amount <usdt>` |
-| `create-card-status` | Query the status of a card issued via `create-card` | `--order-no <orderNo>` (required), `--app-id <id>`, `--poll` |
-| `wallet` | Show local wallet USDT + BNB balance | `--app-id <id>`, `--private-key` |
-| `wallet-gas` | Send BNB from main wallet to session key via WalletConnect | `--amount <bnb>` (default `0.001`), `--app-id <id>` |
-| `wallet-withdraw` | Reclaim USDT + BNB from session key back to main wallet | `--amount <usdt>` (default: all), `--to <address>`, `--app-id <id>` |
-| `clean` | Remove skill + uninstall global package | — |
-
-Global flags: `--legacy-output` (old JSON shape), `--verbose`, `--quiet`.
-
-## Wallet & Funding Model
-
-- **Session key**: A locally-generated private key stored at `~/.aigateway/config.json` (mode 0o600). It signs all paid calls and never leaves your machine.
-- **Main wallet**: Your existing MetaMask / OKX / Trust wallet. Connects only via WalletConnect QR — its key never touches the CLI.
-- **First-funding floor**: ≥ **1 USDT** (`LOW_BALANCE_THRESHOLD`) is enforced before any paid call.
-- **Per-top-up minimum**: ≥ **5 USDT** (`MIN_TOPUP_USDT`). Presets: 5 / 10 / 20 / 50, or custom ≥ 5.
-- **Approve once**: `wallet-topup` broadcasts a one-time `ERC20.approve(facilitator, MaxUint256)` (consumes ~0.0003 BNB). Subsequent paid calls reuse this allowance — no more on-chain transactions for the user.
-- **Gasless paid calls**: Both `create-card` and `create-image` are pure EIP-712 signatures; the facilitator pays gas for the actual USDT transfer.
+| `wallet-init` | Check / create the local session wallet (purely local — no QR, no on-chain action) | `--app-id <id>` |
+| `wallet-topup` | WalletConnect USDT top-up (≥5 USDT, presets 5/10/20/50) + first-time approve | `--amount <usdt>`, `--private-key <key>` |
+| **`sb invoke`** | **The only x402 paid invocation entry point** — invoke any SkillBoss model | `--model <id>` (required), `--inputs <json>` (required), `--output <dir>`, `--raw`, `--topup-amount <usdt>` |
+| **`sb tools`** | Fetch the model catalog from the server in real time (no cache) | `--model <id>` / `--category <key>` / `--tier <price\|quality\|balanced>` |
+| `wallet-balance` | Show the session wallet's USDT + BNB balance | `--private-key <key>` |
+| `wallet-gas` | Transfer BNB from the main wallet to the session key via WalletConnect | `--amount <bnb>` (default `0.001`) |
+| `wallet-withdraw` | Withdraw USDT + BNB from the session key back to the main wallet | `--amount <usdt>` (default all), `--to <address>` |
+| `clean` | Uninstall the skill + global package and clear caches | — |
 
-## Prerequisites
+Global flags: `--legacy-output` (legacy JSON shape), `--verbose`, `--quiet`.
 
-- Node.js ≥ 25
-- A mobile wallet app with WalletConnect support (MetaMask, OKX Wallet, Trust Wallet, etc.)
-- USDT (BEP-20) and a small BNB balance in your main wallet for the one-time approve gas (~$0.002)
+**Usage-based pricing constraints** (enforced by `sb invoke` client-side preflight):
+
+- `video`: must include `duration_seconds` (billed per second)
+- `stt`: must include `duration_minutes` (billed per minute)
+
+---
+
+## Wallet & Pricing Model
 
-## Quickstart for Developers
+- **Session key**: a locally generated private key (`~/.aigateway/config.json`, mode 0o600). All paid calls are signed by this key, and the private key never leaves your machine.
+- **Main wallet**: your existing MetaMask / OKX / Trust wallet — only connected via the WalletConnect QR code, the main wallet's private key never touches the CLI.
+- **First-call balance threshold**: wallet balance must be ≥ **1 USDT** before invocation (`LOW_BALANCE_THRESHOLD`).
+- **Minimum top-up per session**: ≥ **5 USDT** (`MIN_TOPUP_USDT`), presets 5 / 10 / 20 / 50.
+- **One-time approve**: `wallet-topup` broadcasts a single `ERC20.approve(facilitator, MaxUint256)` (consumes ~0.0003 BNB); all subsequent paid calls reuse the allowance — no further on-chain tx needed.
+- **Gasless payments**: `sb invoke` is purely EIP-712 signing end-to-end; the server pays the gas for the on-chain USDT transfer.
+- **Dynamic pricing**: the server computes `priceUnit × inputs usage` in real time:
+  - Image: `per_image × num_outputs`
+  - Video: `per_second × duration_seconds`
+  - TTS: `per_1k_chars × len(text)/1000`
+  - Transcription: `per_minute × duration_minutes`
+  - Embedding: `per_million_tokens × len(input)/4/1M`
+  - Others: `per_request × 1`
 
-Bundling `aigateway` inside your own agent product or merchant service? See:
+---
+
+## Developer Integration
 
 **Reference**
-- [docs/output-schema.md](docs/output-schema.md) — full envelope schema per command
-- [docs/exit-codes.md](docs/exit-codes.md) — exit code categories + `error.code` reference
-- [docs/env-vars.md](docs/env-vars.md) — `AIGATEWAY_SERVICE_URL`, `EVM_PRIVATE_KEY`, and the config-file fallback
-- [docs/troubleshooting.md](docs/troubleshooting.md) — common issues + remedies
+- [docs/output-schema.md](docs/output-schema.md) — Full envelope schema for every command
+- [docs/exit-codes.md](docs/exit-codes.md) — Exit code categories + `error.code` index
+- [docs/env-vars.md](docs/env-vars.md) — `AIGATEWAY_SERVICE_URL` / `EVM_PRIVATE_KEY` / config fallback rules
+- [docs/troubleshooting.md](docs/troubleshooting.md) — Common issues
 
 **Recipes**
-- [docs/recipes/integrate-in-agent.md](docs/recipes/integrate-in-agent.md) — generic Node.js / Python subprocess wrappers
-- [docs/recipes/merchant-integration.md](docs/recipes/merchant-integration.md) — merchant patterns (user-managed vs. custodial wallet, Express backend example)
-- [docs/recipes/error-recovery.md](docs/recipes/error-recovery.md) — code-by-code recovery strategy
-- [docs/recipes/cron-issue-cards.md](docs/recipes/cron-issue-cards.md) — scheduled paid calls
+- [docs/recipes/integrate-in-agent.md](docs/recipes/integrate-in-agent.md) — Node.js / Python subprocess wrapping
+- [docs/recipes/merchant-integration.md](docs/recipes/merchant-integration.md) — Merchant onboarding (self-custody vs. managed wallet)
+- [docs/recipes/error-recovery.md](docs/recipes/error-recovery.md) — Recovery strategies by error code
 
-**Agent / IDE adoption**
-- [docs/ide-setup.md](docs/ide-setup.md) — manual install templates for Cursor / Windsurf / Cline / Codex
+**Agent / IDE integration**
+- [docs/ide-setup.md](docs/ide-setup.md) — Manual install templates for various IDEs
 
-**Releasing**
-- [docs/release-process.md](docs/release-process.md) — version lock-step, publish, auto-upgrade flow
-- [CHANGELOG.md](CHANGELOG.md) — release history
+**Release**
+- [docs/release-process.md](docs/release-process.md) — Version sync, release, auto-upgrade
+- [CHANGELOG.md](CHANGELOG.md) — Release history
 
-Minimal Node.js example:
+### Minimal Node.js example
 
 ```js
 import { spawn } from "node:child_process";
 
 const child = spawn("aigateway", [
-  "--quiet", "create-card", "--amount", "5", "--app-id", "MY_AGENT_001", "--poll",
+  "--quiet",
+  "sb", "invoke",
+  "--model", "<model_id>",
+  "--inputs", JSON.stringify({ prompt: "a cyberpunk fox" }),
+  "--app-id", "MY_AGENT_001",
 ]);
 let stdout = "";
 child.stdout.on("data", (b) => { stdout += b; });
-child.on("close", (code) => {
+child.on("close", () => {
   const env = JSON.parse(stdout.trim().split("\n").pop());
-  if (env.ok) console.log("Card ready:", env.data.orderNo);
-  else console.error(`[${env.error.code}] ${env.error.message}`);
+  if (env.ok) {
+    console.log("Image saved:", env.data.downloaded[0].localPath);
+    console.log("Tx:", env.data.transaction);
+  } else {
+    console.error(`[${env.error.code}] ${env.error.message}`);
+  }
 });
 ```
 
+---
+
 ## Configuration
 
-Config lives at `~/.aigateway/config.json` (file mode 600). The default service URL (`https://ai-api.aeon.xyz`) is wired into the CLI; staging / custom backends can be overridden through environment variables only:
+Config lives at `~/.aigateway/config.json` (file mode 600). The CLI ships with a default service URL (`https://ai-api.aeon.xyz`); for testing or a custom backend, override via environment variables:
+
+- `AIGATEWAY_SERVICE_URL` — base URL of the x402 service
+- `EVM_PRIVATE_KEY` — override the saved session key (development use)
 
-- `AIGATEWAY_SERVICE_URL` — x402 service base URL
-- `EVM_PRIVATE_KEY` — override the saved session key (developer use)
+---
 
 ## License
 

package/bin/cli.mjs

@@ -128,6 +128,7 @@ sb
 sb
   .command("tools")
   .description("Fetch and display the AI tool catalog (with optional filters)")
+  .option("--app-id <id>", "Merchant app ID", DEFAULT_APP_ID)
   .option("--model <id>", "Return only this model (+effectiveSchema)")
   .option("--category <key>", "Return only this category (image / video / tts / etc.)")
   .option("--tier <tier>", "Filter models by tier (price | quality | balanced)")

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.