@aeon-ai-pay/aigateway 0.1.0

package/docs/output-schema.md

@@ -0,0 +1,188 @@
+# 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.
+
+> Pass `--quiet` to suppress non-error stderr. Pass `--legacy-output` to fall back to the pre-envelope shape (see [Legacy mode](#legacy-mode)).
+
+## Envelope
+
+### Success
+
+```json
+{
+  "ok": true,
+  "command": "create",
+  "version": "0.9.0",
+  "data": { /* command-specific payload */ }
+}
+```
+
+### Failure
+
+```json
+{
+  "ok": false,
+  "command": "create",
+  "version": "0.9.0",
+  "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
+  }
+}
+```
+
+- `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`).
+
+## Per-Command `data` Payloads
+
+### `wallet-init`
+
+```json
+{
+  "ready": true,
+  "created": false,
+  "appId": "TEST000001",
+  "mode": "private-key",
+  "address": "0x...",
+  "mainWallet": "0x..." | null,
+  "serviceUrl": "https://...",
+  "amountLimits": { "min": 0.6, "max": 800 }
+}
+```
+
+### `wallet-topup`
+
+```json
+{
+  "ready": true,
+  "appId": "TEST000001",
+  "address": "0x...",
+  "initialUsdt": "0",
+  "usdt": "5",
+  "bnb": "0.0003",
+  "allowance": "115792...max",
+  "topup": "5" | null,
+  "approveTx": "0x..." | null
+}
+```
+
+### `create-card`
+
+```json
+{
+  "appId": "TEST000001",
+  "orderNo": "...",
+  "data": { /* sanitized server response */ },
+  "paymentResponse": { /* decoded PAYMENT-RESPONSE header */ },
+  "pollResult": { /* present when --poll succeeds */ }
+}
+```
+
+### `create-image`
+
+```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 }
+}
+```
+
+**Dry-run (`--dry-run`)** — preflight checks complete but no signing/transaction occurs:
+
+```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"]
+}
+```
+
+### `create-card-status`
+
+```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)"
+  }
+}
+```
+
+### `wallet`
+
+```json
+{
+  "mode": "private-key",
+  "address": "0x...",
+  "usdt": "12.34",
+  "network": "BSC Mainnet (Chain ID: 56)",
+  "mainWallet": { "address": "0x...", "usdt": "..." }
+}
+```
+
+### `wallet-gas`
+
+```json
+{
+  "appId": "TEST000001",
+  "localWallet": { "address": "0x...", "bnb": "..." },
+  "transaction": "0x..."
+}
+```
+
+### `wallet-withdraw`
+
+```json
+{
+  "to": "0x...",
+  "transactions": { "usdt": "0x..." | null, "bnb": "0x..." | null },
+  "remaining": { "usdt": "0.0", "bnb": "0.0" }
+}
+```
+
+### `clean`
+
+```json
+{
+  "removed": ["skills", "npm-global", "npm-cache", "npx-cache"]
+}
+```
+
+## Logging Flags
+
+| Flag | Effect |
+| ---- | ------ |
+| `--verbose` | Enable verbose stderr logs. |
+| `--quiet` | Suppress non-error stderr logs. The stdout envelope is unaffected. |
+| `--legacy-output` | See below. |
+
+## Legacy Mode
+
+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
+```
+
+Legacy mode is kept for one or two minor releases as a migration aid. New integrations should use the envelope.

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

@@ -0,0 +1,69 @@
+# Recipe — Schedule Recurring Card Issuance
+
+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."
+
+## 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
+   ```
+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.
+
+## A Minimal Wrapper Script
+
+`~/bin/issue-card.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+AMOUNT="${1:-5}"
+LOG_DIR="${HOME}/.aigateway/logs"
+mkdir -p "$LOG_DIR"
+TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
+LOG="$LOG_DIR/issue-${TS}.log"
+
+# Capture envelope on stdout; quiet stderr noise
+ENVELOPE=$(aigateway --quiet create-card --amount "$AMOUNT" --poll 2>"$LOG")
+EXIT=$?
+
+echo "$ENVELOPE" > "${LOG%.log}.json"
+
+if [ "$EXIT" -ne 0 ]; then
+  CODE=$(echo "$ENVELOPE" | jq -r '.error.code // "UNKNOWN"')
+  echo "[$(date -u)] FAILED code=$CODE exit=$EXIT — see $LOG" >&2
+  # Surface failure via your alerting channel (Slack, email, etc.) here
+  exit "$EXIT"
+fi
+
+ORDER=$(echo "$ENVELOPE" | jq -r '.data.orderNo')
+echo "[$(date -u)] OK orderNo=$ORDER amount=$AMOUNT"
+```
+
+```bash
+chmod +x ~/bin/issue-card.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
+```
+
+> ⚠️ 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.
+
+## Failure Modes to Watch
+
+| 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. |
+
+## 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.

package/docs/recipes/error-recovery.md

@@ -0,0 +1,53 @@
+# Recipe — Error Recovery Strategy
+
+Map each `error.code` returned by the envelope to a concrete recovery action. Use this table when wiring `aigateway` into an agent prompt or a control-flow layer.
+
+| `error.code` | Exit | Recommended Recovery |
+| ------------ | :--: | -------------------- |
+| `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>`. |
+| `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. |
+| `SERVICE_UNAVAILABLE` | 3 | Exponential backoff: 1 s → 4 s → 16 s, max 3 attempts. |
+| `PAYMENT_FETCH_FAILED` | 3 | Same as above. Check network connectivity. |
+| `BALANCE_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. |
+| `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. |
+| `INTERNAL_ERROR` | 4 | File a bug. Don't retry. |
+| `WALLET_ERROR` | 1 | Generic wallet failure. Surface to user, ask whether to retry. |
+
+## Generic Retry Helper (Node.js)
+
+```js
+async function withRetry(fn, { codes, attempts = 3, baseDelayMs = 1000 } = {}) {
+  for (let i = 0; i < attempts; i++) {
+    const { exitCode, envelope } = await fn();
+    if (envelope.ok) return envelope;
+    if (!codes.includes(envelope.error.code)) return envelope; // non-retryable
+    if (i < attempts - 1) await new Promise(r => setTimeout(r, baseDelayMs * 4 ** i));
+  }
+}
+
+// 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"],
+});
+```
+
+## Anti-patterns
+
+- ❌ Don't retry `PAYMENT_REJECTED` or `PAYMENT_TIMEOUT` automatically — the user actively cancelled or walked away.
+- ❌ 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.

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

@@ -0,0 +1,108 @@
+# Recipe — Integrate `aigateway` Inside Your Agent
+
+This recipe shows how to invoke `aigateway` from inside an agent product (Node.js, Python, or anything that can spawn a subprocess) and parse the JSON envelope reliably.
+
+## Prerequisites
+
+- `@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.
+
+> ⚠️ 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.
+
+## Node.js — Spawn & Parse Envelope
+
+```js
+import { spawn } from "node:child_process";
+
+function runAEON AI Gateway(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("aigateway", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => { stdout += b; });
+    child.stderr.on("data", (b) => { stderr += b; });
+    child.on("close", (code) => {
+      let envelope;
+      try {
+        envelope = JSON.parse(stdout.trim().split("\n").pop());
+      } catch {
+        return reject(new Error(`Could not parse envelope. stderr: ${stderr}`));
+      }
+      resolve({ exitCode: code, envelope, stderr });
+    });
+  });
+}
+
+// Example: create a $5 card and poll until terminal
+const { envelope, exitCode } = await runAEON AI Gateway([
+  "--quiet",
+  "create",
+  "--amount", "5",
+  "--app-id", "MY_AGENT_001",
+  "--poll",
+]);
+
+if (envelope.ok) {
+  const { orderNo, data } = envelope.data;
+  console.log("Card ready:", data.model?.cardNumber, "order:", orderNo);
+} else {
+  // See docs/recipes/error-recovery.md for code-by-code guidance
+  console.error(`Failed [${envelope.error.code}] (exit ${exitCode}):`, envelope.error.message);
+}
+```
+
+### Why `--quiet`?
+
+`--quiet` silences progress logs on stderr. The stdout envelope is one line of JSON either way — but suppressing stderr makes child-process orchestration cleaner.
+
+### Why `.split("\n").pop()`?
+
+The envelope is **always the last line on stdout**. Tools that wrap the binary (npx, npm, asdf, fnm) may inject preamble lines; taking the last line is robust.
+
+## Python — Spawn & Parse Envelope
+
+```python
+import json, subprocess
+
+def run_aigateway(args):
+    result = subprocess.run(
+        ["aigateway", "--quiet", *args],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    envelope = json.loads(result.stdout.strip().splitlines()[-1])
+    return result.returncode, envelope
+
+exit_code, env = run_aigateway(["create", "--amount", "5", "--poll"])
+if env["ok"]:
+    print("Card ready:", env["data"]["data"]["model"]["cardNumber"])
+else:
+    print(f"Failed [{env['error']['code']}] exit={exit_code}: {env['error']['message']}")
+```
+
+## Probing Without Cost — `--dry-run`
+
+To validate inputs, balances, and allowance **without** signing or transacting, use `--dry-run` on `create-card`:
+
+```bash
+aigateway --quiet create-card --amount 5 --dry-run | jq '.data.will, .data.decision'
+```
+
+This is ideal for integration tests, configuration smoke checks, and "is everything ready?" probes.
+
+## Exit Code Strategy
+
+Treat exit codes as a fast filter, then branch on `error.code` for nuance:
+
+```js
+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 3: /* network / service — exponential backoff retry */ break;
+  case 4: /* internal — log + fail loud */ break;
+}
+```
+
+See [exit-codes.md](../exit-codes.md) for the full mapping.

package/docs/recipes/merchant-integration.md

@@ -0,0 +1,243 @@
+# Recipe — Merchant Integration
+
+This recipe shows how a merchant integrates AEON AI Gateway into their own product (SaaS, agent, mobile app, IDE extension) via the CLI. The core pattern is the same as the [generic spawn integration](./integrate-in-agent.md), with one key addition: **every call carries your merchant `--app-id`** so the backend can attribute usage, settle billing, and route customer support.
+
+## 1. Prerequisites
+
+### 1.1 Get your `appId`
+
+Ask the AEON team for a merchant `appId` (e.g. `MERCHANT_ACME_001`) to replace the public default `TEST000001`. All CLI calls should be made with `--app-id <yourId>`. The backend uses it for:
+
+- Per-merchant USDT accounting / settlement.
+- Usage analytics & rate limiting.
+- Revenue share / referral.
+- Support ticket correlation (`appId` echoes back in every envelope).
+
+### 1.2 Install the CLI on your target host
+
+```bash
+npm install -g @aeon-ai-pay/aigateway
+```
+
+### 1.3 Pick a wallet model
+
+| Model | Who owns the session key | Who pays | Use when |
+| --- | --- | --- | --- |
+| **A. User-managed** | User's machine (`~/.aigateway/`) | The end-user, via WalletConnect | Your product runs locally on the user's machine (IDE plugin, desktop CLI, agent) |
+| **B. Merchant-custodial** | Your backend (Vault / KMS) | You pre-fund, then resell | Your product is SaaS / web; users pay you in fiat, you pay USDT to upstream |
+
+Both modes use the same CLI; only the source of the session key (`EVM_PRIVATE_KEY`) differs.
+
+## 2. Wallet Model A — User-Managed
+
+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
+```
+
+Subsequent paid calls are spawned by your product (agent / IDE plugin / app):
+
+```js
+import { spawn } from "node:child_process";
+
+const APP_ID = "MERCHANT_ACME_001";
+
+function runAigateway(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("aigateway", ["--quiet", ...args, "--app-id", APP_ID]);
+    let stdout = "";
+    child.stdout.on("data", (b) => { stdout += b; });
+    child.on("close", (exitCode) => {
+      try {
+        resolve({ exitCode, envelope: JSON.parse(stdout.trim().split("\n").pop()) });
+      } catch (e) {
+        reject(new Error(`parse failed (exit ${exitCode}): ${e.message}`));
+      }
+    });
+  });
+}
+
+const { envelope } = await runAigateway(["create-card", "--amount", "5", "--poll"]);
+if (envelope.ok) {
+  showCard(envelope.data);  // card number already redacted to "•••• 4242"
+} else if (envelope.error.code === "TOPUP_REQUIRED") {
+  promptUserToTopup(envelope.error.presets);  // [5, 10, 20, 50]
+}
+```
+
+## 3. Wallet Model B — Merchant-Custodial (most common SaaS)
+
+Your backend holds a session private key (pre-generated, in Vault / AWS Secrets Manager / GCP Secret Manager). Pre-fund it once; route all customer requests through it.
+
+### 3.1 Inject the key via env var
+
+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
+```
+
+### 3.2 Express backend example
+
+```js
+import express from "express";
+import { spawn } from "node:child_process";
+
+const app = express();
+app.use(express.json());
+
+const APP_ID = process.env.AIGATEWAY_APP_ID;            // e.g. MERCHANT_ACME_001
+const SESSION_KEY = process.env.AIGATEWAY_SESSION_KEY;  // fetched from Vault on boot
+
+function runCmd(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("aigateway", ["--quiet", ...args, "--app-id", APP_ID], {
+      env: { ...process.env, EVM_PRIVATE_KEY: SESSION_KEY },
+    });
+    let stdout = "";
+    child.stdout.on("data", (b) => { stdout += b; });
+    child.on("close", (code) => {
+      try { resolve({ code, envelope: JSON.parse(stdout.trim().split("\n").pop()) }); }
+      catch (e) { reject(e); }
+    });
+  });
+}
+
+// User paid you in fiat upstream, now you fulfil via aigateway
+app.post("/api/issue-card", async (req, res) => {
+  const { userId, amount } = req.body;
+
+  // Your KYC / fraud / balance checks
+  if (!await canIssueCard(userId, amount)) return res.status(403).end();
+
+  const { code, envelope } = await runCmd(["create-card", "--amount", String(amount), "--poll"]);
+
+  if (envelope.ok) {
+    await db.cards.insert({
+      userId,
+      orderNo: envelope.data.orderNo,
+      cardNumber: envelope.data.data.model.cardNumber,
+      amount,
+      issuedAt: new Date(),
+    });
+    res.json({ ok: true, orderNo: envelope.data.orderNo });
+  } else {
+    await logErr(userId, envelope.error);
+    res.status(500).json({ error: envelope.error.code, message: envelope.error.message });
+  }
+});
+
+app.listen(3000);
+```
+
+### 3.3 Pre-funding the merchant pool
+
+Run **once on a workstation with a real wallet app**, not on the production server:
+
+```bash
+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**.
+
+### 3.4 Low-balance alerting
+
+```js
+const { envelope } = await runCmd(["wallet-balance"]);
+if (parseFloat(envelope.data.usdt) < 10) {
+  notifySlack(`aigateway USDT pool low: ${envelope.data.usdt}`);
+}
+```
+
+Schedule it via cron / your monitoring stack.
+
+## 4. Standard envelope handling
+
+```js
+function handleEnvelope(envelope, exitCode) {
+  if (envelope.ok) return { ok: true, data: envelope.data };
+
+  switch (envelope.error.code) {
+    case "WALLET_NOT_CONFIGURED":
+    case "SERVICE_URL_MISSING":
+      throw new ConfigError(envelope.error);
+
+    case "INSUFFICIENT_USDT":
+    case "TOPUP_REQUIRED":
+      await yourTopupFlow();
+      return { ok: false, retry: true };
+
+    case "AMOUNT_OUT_OF_RANGE":
+      return { ok: false, userMessage: `Amount must be $${envelope.error.min}~${envelope.error.max}` };
+
+    case "POLL_TIMEOUT":
+      await scheduleStatusCheck(envelope.error.orderNo);
+      return { ok: false, asyncPending: true };
+
+    case "SERVICE_UNAVAILABLE":
+    case "PAYMENT_FETCH_FAILED":
+    case "BALANCE_CHECK_FAILED":
+      return { ok: false, retryWithBackoff: true };
+
+    case "PAYMENT_REJECTED":
+    case "PAYMENT_TIMEOUT":
+      return { ok: false, userMessage: "Payment not confirmed" };
+
+    default:
+      throw new UnexpectedError(envelope.error);
+  }
+}
+```
+
+Full code table: [exit-codes.md](../exit-codes.md). Concrete recovery actions per code: [error-recovery.md](./error-recovery.md).
+
+## 5. Sandbox / test environments
+
+### Dry-run (no real USDT)
+
+```bash
+aigateway create-card --amount 5 --dry-run --app-id TEST000001
+# envelope.data.dryRun = true; preflight passes, nothing signed
+```
+
+### Staging service URL
+
+```bash
+AIGATEWAY_SERVICE_URL=https://staging-x402.aeon.xyz \
+  aigateway create-card --amount 5 --app-id YOUR_TEST_APPID --poll
+```
+
+### CI
+
+Never invoke real paid commands in CI. Use `--dry-run` to validate your subprocess wrapper + envelope parser only.
+
+## 6. Operational checklist for merchants
+
+| Item | Frequency | Command |
+| --- | --- | --- |
+| Session wallet USDT balance | Realtime / hourly | `wallet-balance` |
+| Session wallet BNB balance | When needed (withdraw only) | `wallet-balance` |
+| 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 |
+
+## 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.
+
+## 8. See also
+
+- [integrate-in-agent.md](./integrate-in-agent.md) — Generic spawn-and-parse template (no merchant-specific bits)
+- [error-recovery.md](./error-recovery.md) — Recovery per `error.code`
+- [cron-issue-cards.md](./cron-issue-cards.md) — Scheduled paid calls
+- [../exit-codes.md](../exit-codes.md) — Full error code reference
+- [../output-schema.md](../output-schema.md) — envelope schema per command