@aeon-ai-pay/aigateway 0.1.0

package/skills/aigateway/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: aigateway
+description: >
+  Trigger this skill whenever the user wants to *purchase* or *invoke* anything
+  that AEON AI Gateway can settle per-call via the x402 protocol — including
+  virtual debit cards and Skill Boss AI services (currently AI image generation).
+
+  This includes intents such as:
+  - "create a virtual card" / "get me a card with $5" / "what's my card status"
+  - "generate an image of …" / "draw a picture of …" / "render this scene"
+  - "what can I buy" / "what can I do?"
+  - "top up my wallet" / "check my balance" / "withdraw my funds"
+
+  Also, any request involving x402-protocol crypto payments for AI services or
+  virtual cards funded with USDT on BSC.
+emoji: "🛰️"
+homepage: https://github.com/AEON-Project/aigateway
+metadata:
+  version: "0.1.0"
+  author: AEON-Project
+  openclaw:
+    requires:
+      bins:
+        - node
+        - npx
+    primaryEnv: AIGATEWAY_SERVICE_URL
+    user-invocable: true
+    disable-model-invocation: false
+compatibility: Requires Node.js >= 25 and npm
+---
+
+# AEON AI Gateway Skill
+
+**AEON AI Gateway** lets AI Agents discover, invoke, and settle paid LLMs, APIs, and Skills via a single CLI. Currently open capabilities:
+
+- **`create-card`** — issue a one-time virtual Visa/Mastercard (x402-paid, USDT on BSC).
+- **`create-image`** — generate an AI image via Skill Boss (x402-paid, USDT on BSC).
+
+Both share the same session-key wallet, funded once via WalletConnect and reused indefinitely.
+
+> ⚡ **Two-step wallet readiness, then pay-per-call**:
+> - **`wallet-init`** *(local, free)*: Generates a local session key (if missing) and returns ready/created status. No QR, no on-chain action.
+> - **`wallet-topup`** *(WalletConnect, one-time)*: Loads USDT (≥5 USDT minimum, presets 5/10/20/50) + 0.0003 BNB approve gas, then the session key broadcasts `ERC20.approve(facilitator, MaxUint256)`. Done once; subsequent paid calls reuse the allowance and run gasless. Use again later (with `--amount <usdt>`) to refill.
+> - **`create-card` / `create-image`** *(gasless)*: Pure EIP-712 signatures → server submits the USDT transfer (server pays gas). If somehow underfunded, both commands fall back into the same funding flow as `wallet-topup`.
+> - **`wallet-withdraw`**: Session key sends ERC20 transfer + BNB directly on-chain — needs a tiny BNB balance for gas.
+> - **`wallet-gas`**: Transfers BNB only (used when `wallet-withdraw` reports `No BNB for gas`).
+
+---
+
+## Opening Line (Required)
+
+Whenever entering this skill for the first time, output this opening line:
+
+> Let me check the environment first.
+
+Then **immediately** proceed to "Step 1: Pre-check".
+
+---
+
+## Output Envelope
+
+Every CLI command writes **one JSON line** to **stdout** — the *envelope*. Progress logs go to stderr and are not required for control flow.
+
+- Success: `{ "ok": true, "command": "...", "version": "...", "data": { /* payload */ } }`
+- Failure: `{ "ok": false, "command": "...", "version": "...", "error": { "code": "...", "message": "...", /* extra context */ } }`
+
+Field references in this document (e.g. `ready`, `orderNo`, `cardStatus`) refer to fields under **`envelope.data`** (success) or under **`envelope.error`** (failure). **Match on `error.code` (stable) — not on `error.message`.**
+
+See [docs/output-schema.md](../../docs/output-schema.md) and [docs/exit-codes.md](../../docs/exit-codes.md) for the full schema and error code reference.
+
+---
+
+## Command Overview
+
+```bash
+aigateway wallet-init                             # Pre-check / auto-create local session wallet (no QR)
+aigateway wallet-topup [--amount <usdt>]          # WalletConnect: top-up USDT (≥5; presets 5/10/20/50) + first-time facilitator approve
+aigateway create-card --amount <usd> --poll       # Issue a virtual card ($0.6 ~ $800)
+aigateway create-image --prompt "<text>"          # Generate AI image
+aigateway create-card-status --order-no <orderNo> [--poll]    # Query card status
+aigateway wallet-balance                          # Check local wallet balance
+aigateway wallet-gas [--amount <bnb>]                    # Top up BNB for session key (for withdraw)
+aigateway wallet-withdraw [--to <addr>] [--amount <usdt>]   # Reclaim funds
+aigateway clean                                   # Uninstall skill, clear cache
+```
+
+Every command accepts `--app-id <id>` (merchant identifier; defaults to `TEST000001` — do not prompt the user unless they explicitly mention a custom merchant ID). Config lives at `~/.aigateway/config.json` (mode 0o600).
+
+**Never ask the user for a private key; the local session key is auto-generated.**
+
+---
+
+## Step 1: Pre-check (Auto Wallet Initialization)
+
+Regardless of user intent, **always** run first:
+
+```bash
+aigateway wallet-init
+```
+
+Output template:
+
+```
+> Pre-check in progress...
+```
+
+`envelope.data`: `{ ready, created, mode, address, mainWallet, serviceUrl, amountLimits }`.
+
+- `created: true` → "Auto-creating your designated wallet..." + then "0x0...{last4} Ready."
+- `created: false`, `ready: true` → "0x0...{last4} Ready."
+- Record `amountLimits.{min,max}` for any subsequent card amount validation.
+
+---
+
+## Step 2: Top up (First-Time Funding + Approve)
+
+Trigger: any of (first paid call) | (`wallet-balance` shows < 1 USDT) | (user explicitly wants to "top up" / "load wallet" / "add funds").
+
+```bash
+aigateway wallet-topup                            # Interactive top-up amount prompt (TTY only)
+aigateway wallet-topup --amount 5                 # Non-interactive (recommended for agent invocations)
+```
+
+### When does topup do nothing?
+
+If `wallet` shows USDT ≥ 1 **and** allowance is already non-zero **and** the user did not explicitly ask to add funds, skip Step 2 entirely.
+
+### Amount selection
+
+- Presets: **5 / 10 / 20 / 50 USDT**. Custom amounts must be ≥ 5 USDT.
+- If user said "top up" without an amount, use this exact copy and ask:
+  > How much USDT would you like to load? (presets: 5 / 10 / 20 / 50, or any custom amount ≥ 5)
+- Once the user picks an amount, run with `--amount <n>`.
+
+### Output template
+
+```
+> Topping up wallet...
+```
+
+On success, surface:
+
+```
+✅ Wallet prepared
+Address:   0x0...{last4}
+Balance:   {usdt} USDT, {bnb} BNB
+Approve:   {approveTx truncated or "already approved"}
+```
+
+### Error cases
+
+| `error.code` | Action |
+| --- | --- |
+| `TOPUP_REQUIRED` (non-TTY, balance < 1 USDT) | Ask user for amount (presets in `error.presets`), then rerun with `--amount <n>`. |
+| `TOPUP_AMOUNT_TOO_SMALL` | Show `error.minTopup`, ask again. |
+| `PAYMENT_REJECTED` | User cancelled in wallet. **Do not auto-retry**; ask user. |
+| `PAYMENT_TIMEOUT` | 5-minute WalletConnect window expired. **Do not auto-retry**; ask user. |
+| `INSUFFICIENT_BNB` (post-funding) | Run `aigateway wallet-gas` (interactive) to add BNB, then retry. |
+| `APPROVE_FAILED` | On-chain approve failed; surface message, suggest retry. |
+
+⚠️ `wallet-topup` opens a WalletConnect QR — **must run in foreground synchronously**. Never `run_in_background: true`.
+
+---
+
+## Step 3a: Create Virtual Card
+
+Trigger: user wants to **buy / create / get a virtual card**.
+
+### Amount confirmation
+
+Amount must be in `amountLimits.min ~ amountLimits.max` (from Step 1; never hardcode). If user did not specify, ask once:
+
+> You can create a card of up to ${min}~${max}. How much would you like to load onto the card?
+
+Once specified, **execute immediately**.
+
+### Execute
+
+```bash
+aigateway create-card --amount <usd> --poll
+# Optional: custom merchant
+aigateway create-card --amount <usd> --app-id <merchantId> --poll
+```
+
+Output template first line:
+
+```
+> Creating Agent Card...
+```
+
+⚠️ If the session wallet is underfunded, `create-card` may open a WalletConnect QR — **must run in foreground**.
+
+### Success
+
+`envelope.data`: `{ orderNo, data, paymentResponse, pollResult? }`. After fetching details (may take ~30 s), display **verbatim**:
+
+```
+Order No: {orderNo}
+Card: {cardScheme} •••• {last4}
+State: Active
+Remaining balance: ${amount} USD
+Usage: 0 / 1 (single-use)
+```
+
+Always record `orderNo` — only identifier for status queries.
+
+### Errors
+
+| `error.code` | Action |
+| --- | --- |
+| `AMOUNT_OUT_OF_RANGE` | Show `error.min` / `error.max`, ask again. |
+| `INSUFFICIENT_USDT` (after funding) | Tell user funding fell short; ask whether to re-top-up. |
+| `PAYMENT_TIMEOUT` / `PAYMENT_REJECTED` | Surface, **do not auto-retry**. |
+| `POLL_TIMEOUT` | Card may still be provisioning. Note `error.orderNo`. Use Step 4 (`status`) later. |
+| `PAYMENT_FAILED` | Show raw error (`error.data`), suggest retry. |
+
+See [references/create-card.md](references/create-card.md) for full field details.
+
+---
+
+## Step 3b: Create AI Image
+
+Trigger: user wants to **generate / draw / render an image**.
+
+### Execute
+
+```bash
+aigateway create-image --prompt "<text>"
+# Optional flags:
+aigateway create-image --prompt "<text>" --aspect-ratio 1:1 --output-format png --model <id>
+```
+
+Output template first line:
+
+```
+> Generating image...
+```
+
+### Success
+
+`envelope.data`: `{ prompt, transaction, images: [{ url, localPath, format, width, height, sizeHuman }], balance: { initial, before, after, charged } }`.
+
+Display **verbatim**:
+
+```
+✅ Generated
+Prompt:       {prompt}
+Image:        {localPath} ({width}×{height}, {sizeHuman})
+Transaction:  {transaction}
+Charged:      {balance.charged} USDT
+Balance:      {balance.after} USDT remaining
+```
+
+### Errors
+
+| `error.code` | Action |
+| --- | --- |
+| `MISSING_PROMPT` | Ask user for a non-empty prompt. |
+| `INSUFFICIENT_USDT` (after funding) | Same as Step 3a. |
+| `IMAGE_DOWNLOAD_FAILED` | Mention image was generated but local save failed (URL in raw response). |
+| Same set as Step 3a for `PAYMENT_*` / `POLL_*` codes. |
+
+---
+
+## Step 4: Query Status / Wallet / Withdraw
+
+### Status (cards only)
+
+```bash
+aigateway create-card-status --order-no <orderNo>
+aigateway create-card-status --order-no <orderNo> --poll  # poll until terminal
+```
+
+`envelope.data` shape mirrors the sanitized server response. Use it to display:
+
+```
+> Fetching card status...
+
+Card: {cardScheme} •••• {last4}
+State: {Active | Used | Expired | Pending | Failed}
+Remaining balance: ${balance} USD
+Usage: {used} / {total} (single-use)
+```
+
+### Wallet (balance check)
+
+```bash
+aigateway wallet-balance
+```
+
+`envelope.data`: `{ address, usdt, bnb, mainWallet? }`.
+
+### Withdraw
+
+```bash
+aigateway wallet-withdraw                                  # all USDT → mainWallet
+aigateway wallet-withdraw --amount <usdt>                  # specific amount
+aigateway wallet-withdraw --to 0x...                        # specific destination
+```
+
+Display **verbatim**:
+
+```
+> Reclaiming funds...
+
+From: 0x0...{session_last4}
+To: main wallet (0x0...{main_last4})
+
+Amount: {amount} USDT
+Status: completed
+```
+
+The literal "main wallet" label is a spec requirement — do not omit.
+
+### Edge cases
+
+| Scenario | Action |
+| --- | --- |
+| `error.code = NO_MAIN_WALLET` | Ask user for destination, rerun with `--to <address>`. |
+| `error.code = INSUFFICIENT_BNB` (in withdraw) | Run `aigateway wallet-gas` first. |
+| `error.code = NO_FUNDS` | Inform user nothing to withdraw. |
+
+---
+
+## Decision Routing
+
+| User Intent | Entry Command |
+| --- | --- |
+| First entry / uncertain state | `wallet-init` (then `wallet-topup` if balance < 1 USDT) |
+| Top up / load wallet / fund | `wallet-topup --amount <n>` |
+| Create virtual card | `create-card --amount <n> --poll` |
+| Generate AI image | `create-image --prompt "<text>"` |
+| Check card status | `create-card-status --order-no <n>` |
+| Check balance | `wallet` |
+| Withdraw funds | `withdraw [--to <addr>] [--amount <n>]` |
+| Top up BNB for withdraw | `gas [--amount <bnb>]` |
+
+---
+
+## Hard Rules (Global)
+
+- **Never** ask for a private key — the local session key is auto-generated.
+- **Never** display full card numbers, CVV, or expiry. The CLI already redacts these to `•••• 1234`.
+- **Never** run `wallet-topup` / `create-card` (when underfunded) / `create-image` (when underfunded) / `wallet-gas` in the background — they may open a WalletConnect QR that needs user attention.
+- **Never** auto-retry `PAYMENT_REJECTED` / `PAYMENT_TIMEOUT`. Ask the user.
+- **Never** poll `status` more than 42 times. Stop on timeout, prompt user to note `orderNo`.
+- **Never** fabricate `amountLimits`. Always use `min/max` from `wallet-init`.
+- **Match `error.code`, not `error.message`.** Messages may change between versions.
+
+---
+
+## Copy Constraints (Verbatim Lines)
+
+The following first-line / key-phrase strings must be **exactly reproduced** — no rewording, no translation, no extra decorations:
+
+| Step | Required first line |
+| --- | --- |
+| Pre-check | `> Pre-check in progress...` |
+| Top up | `> Topping up wallet...` |
+| Create card | `> Creating Agent Card...` |
+| Create image | `> Generating image...` |
+| Fetch details | `> Fetching card details, please wait...` |
+| Query status | `> Fetching card status...` |
+| Withdraw | `> Reclaiming funds...` |
+| Withdraw target line | `To: main wallet (0x0...{last4})` |
+| Withdraw status line | `Status: completed` |
+| Image success header | `✅ Generated` |
+| Wallet prepared header | `✅ Wallet prepared` |
+
+Address rendering: always `0x0...{last4}` (first 3 + ellipsis + last 4 chars).

package/skills/aigateway/references/check-status.md

@@ -0,0 +1,68 @@
+# Check Card Status
+
+## Command
+
+```bash
+# Single query
+npx @aeon-ai-pay/aigateway create-card-status --order-no <orderNo>
+
+# Poll until terminal status (SUCCESS or FAIL)
+npx @aeon-ai-pay/aigateway create-card-status --order-no <orderNo> --poll
+```
+
+## Response Format
+
+```json
+{
+  "code": "0",
+  "msg": "success",
+  "model": {
+    "orderNo": "300217748668047431791",
+    "orderStatus": "SUCCESS",
+    "channelStatus": "COMPLETED",
+    "orderAmount": 0.6,
+    "txHash": "0xabc...def",
+    "cardLastFour": "4321",
+    "cardBin": "485932",
+    "cardScheme": "VISA",
+    "cardBalance": 0.6,
+    "cardStatus": "ACTIVE"
+  }
+}
+```
+
+## Status Values
+
+### orderStatus (Order Status)
+
+| Status | Meaning | Action |
+|------|------|------|
+| `INIT` | Order created, not yet paid | Wait |
+| `PENDING` | Payment submitted, awaiting on-chain confirmation | Continue polling |
+| `SUCCESS` | Card created successfully | Show card details |
+| `FAIL` | Failed | Show error, suggest retry |
+
+### channelStatus (Channel Status)
+
+| Status | Meaning |
+|------|------|
+| `INIT` | Not yet sent to card provider |
+| `PROCESSING` | Provider is creating the card |
+| `COMPLETED` | Card is ready |
+| `FAILED` | Card creation failed |
+
+### cardStatus (Card Status)
+
+| Status | Meaning |
+|------|------|
+| `PENDING` | Being provisioned |
+| `ACTIVE` | Ready to use |
+| `FROZEN` | Frozen |
+| `CANCELLED` | Cancelled |
+
+## Polling Behavior
+
+With `--poll`:
+- Up to **42 attempts** (first 5 at **2-second** intervals, then every **5 seconds**)
+- Stops on `SUCCESS`, `FAIL`, or `cardStatus=ACTIVE`
+- If timed out, notify user and provide manual query command

package/skills/aigateway/references/create-card.md

@@ -0,0 +1,114 @@
+# Create Virtual Card
+
+## Prerequisites
+
+Before creating a card, confirm the following:
+
+1. Wallet is configured — run `wallet-init`. If not ready, the CLI will auto-create one.
+2. Service URL is configured (built-in default is available; no action needed unless user wants to override)
+3. The `create` command automatically checks allowance and wallet balance before payment. If insufficient, it auto-initiates WalletConnect funding — no need to run `wallet` or `wallet-topup` separately.
+
+## Workflow
+
+### Step 1: Confirm Amount
+
+Ask the user how much to load onto the virtual card.
+
+- Amount limits are enforced by the CLI (`amountLimits.min` ~ `amountLimits.max`, from `wallet-init`).
+- Currency: USD (server handles crypto conversion)
+
+**If user does not specify an amount**, show the valid range and ask for confirmation (**copy must be verbatim**, variable substitution only):
+> "You can create a card of up to ${min}~${max}. How much would you like to load onto the card？"
+
+Once the user specifies an amount, **execute immediately** — no second confirmation needed.
+
+### Step 2: Execute
+
+```bash
+# Create card and auto-poll status
+npx @aeon-ai-pay/aigateway create --amount <amount> --poll
+
+# Optional: specify merchant app ID (defaults to TEST000001)
+npx @aeon-ai-pay/aigateway create --amount <amount> --app-id <merchantAppId> --poll
+```
+
+> `--app-id` is the merchant identifier sent with the request; defaults to `TEST000001` when omitted.
+
+CLI automatically handles the full flow:
+1. Send `GET /open/ai/x402/card/create?amount=X&appId=Y` → receive HTTP 402 + payment requirements (exact USDT amount)
+2. Check allowance → if insufficient and no BNB, mark BNB needed
+3. Check USDT balance → if insufficient, mark top-up needed
+4. If top-up or BNB needed → auto-initiate WalletConnect funding (opens QR page, waits for user to confirm in wallet app)
+5. After funding completes, auto-continue
+6. Approve authorization (only on first use or when allowance insufficient, costs small amount of BNB)
+7. Sign with the exact amount from the first 402 response using EIP-712
+8. Retry request with `PAYMENT-SIGNATURE` header → receive HTTP 200
+9. With `--poll`, polls up to 42 times (first 5 at 2-second intervals, then every 5 seconds) until card is ready
+
+### Step 3: Parse Result
+
+**stdout** outputs JSON (parseable), **stderr** outputs progress logs.
+
+Successful output:
+```json
+{
+  "success": true,
+  "data": {
+    "code": "0",
+    "msg": "success",
+    "model": { "orderNo": "300217748668047431791" }
+  },
+  "paymentResponse": {
+    "txHash": "0x...",
+    "networkId": "eip155:56"
+  }
+}
+```
+
+With `--poll`, additional output after card is ready:
+```json
+{
+  "pollResult": {
+    "orderNo": "300217748668047431791",
+    "orderStatus": "SUCCESS",
+    "channelStatus": "COMPLETED",
+    "orderAmount": 0.6,
+    "txHash": "0xabc...def",
+    "cardLastFour": "4321",
+    "cardBin": "485932",
+    "cardScheme": "VISA",
+    "cardBalance": 0.6,
+    "cardStatus": "ACTIVE"
+  }
+}
+```
+
+### Step 4: Present to User
+
+Fetching card details may take about 30 seconds. Output a waiting prompt first (**copy must be verbatim**):
+```
+> Fetching card details, please wait...
+```
+
+Once details are returned, on success (**copy must be verbatim**, variable substitution only):
+```
+Order No: {orderNo}
+Card: {cardScheme} •••• {last4}
+State: Active
+Remaining balance: ${amount} USD
+Usage: 0 / 1 (single-use)
+```
+
+Save the `orderNo` for subsequent status queries.
+
+## Error Handling
+
+| Scenario | CLI Output | Action |
+|------|---------|---------|
+| Amount out of range | Error JSON with allowed range | Relay to user |
+| Wallet not configured | `Wallet not configured` | Run `wallet-init` |
+| Funding signature timeout (5 min) | `Payment approval timed out. Please try again.` | Relay to user, ask if they want to retry |
+| User rejected signature | `Payment approval was rejected. Please try again if you'd like to proceed.` | Relay to user, do not auto-retry |
+| Insufficient balance after funding | `Still insufficient USDT after funding` | Relay to user |
+| Network error | Server error JSON | Retry once, then report to user |
+| Transaction reverted | txHash | Suggest user check on BSCScan |

package/skills/aigateway/references/store.md

@@ -0,0 +1,87 @@
+# AEON AI Card Store
+
+## When to use
+
+Trigger this reference when the user says:
+- "what can I buy"
+- "show me what's available"
+- "what can I do?"
+- "what can I use the card for"
+
+Present options conversationally. Do not dump the full list — highlight what's most relevant.
+
+---
+
+## Virtual Card Use Cases
+
+### AEON Agent Card – Supported & Upcoming Use Cases
+
+**Coming Soon**
+- Subscriptions (ChatGPT, Claude, Midjourney)
+- Ads (Google, Meta)
+- Travel bookings
+- SaaS tools
+
+**Tell us what you want**
+
+Submit your request here:
+👉 [Google Form link]
+
+---
+
+## x402 API Payments
+
+Pay these services directly using `x402 fetch`. No card needed — payment goes straight from your wallet.
+
+### AI & Data
+
+| Service | What it does | Chain |
+|---|---|---|
+| AskClaude | Per-question Claude AI access ($0.01–$0.10/query) | Base |
+| Arch AI Tools | 53 AI tools: web search, image generation, fact-checking | Base |
+| Firecrawl | Web scraping and LLM-ready content extraction | Base |
+| Gloria AI | Real-time news data for agents | Base |
+| Minifetch | Web metadata and content summaries | Base |
+
+### Blockchain & DeFi
+
+| Service | What it does | Chain |
+|---|---|---|
+| Messari | Crypto research and on-chain data | Base |
+| Nansen | Wallet intelligence and blockchain analytics | Base |
+| DiamondClaws | DeFi yield scoring and protocol risk analysis | Base |
+| Stakevia | Solana validator intelligence | Solana |
+
+### Infrastructure
+
+| Service | What it does | Chain |
+|---|---|---|
+| Pinata | IPFS file uploads and retrievals, no account required | Base |
+| Run402 | Postgres databases and serverless functions, no signup | Base |
+| Alchemy | Pay-per-request RPC / blockchain API access | Base |
+| Robtex | DNS and network intelligence APIs | Base |
+
+### Payments & Commerce
+
+| Service | What it does | Chain |
+|---|---|---|
+| Bitrefill | Buy gift cards and prepaid cards with crypto | Base |
+| ClawCredit | Access x402 services on credit, pay later | Base |
+
+Full registry: [x402.org/ecosystem](https://www.x402.org/ecosystem) · [x402list.fun](https://x402list.fun)
+
+---
+
+## How to Present to the User
+
+Example response when user has no specific intent:
+
+> "Here's what you can do with AEON AI Card:
+>
+> - **Virtual card** — coming soon: subscribe to ChatGPT, Claude, Midjourney, run ads, book travel
+> - **Pay AI APIs** — call Claude, Firecrawl, web search per request via x402
+> - **Access DeFi data** — Nansen, Messari on-chain analytics via x402
+>
+> What would you like to do?"
+
+Adapt based on context. For virtual card intent → route to create-card flow. For x402 API intent → route to x402 flow.