@kaleidorg/mind 0.0.1 → 0.1.0

package/skills/bitrefill/references/host-openclaw.md

@@ -0,0 +1,167 @@
+# Host: OpenClaw
+
+[OpenClaw](https://docs.openclaw.ai/) is a self-hosted Gateway that bridges chat apps (Telegram, WhatsApp, Slack, Discord, iMessage, Signal, Matrix, Teams, etc.) to coding agents like **Pi**. It is a **superset host**: full host shell, agentskills.io-compatible skill loader, first-class MCP, mobile-node camera/canvas, cron, and multi-channel routing.
+
+This file explains how to install + harden the Bitrefill skill inside OpenClaw and lists scenarios no other host can do. After setup, use the regular path files for the actual workflow.
+
+**OpenClaw path priority:** **guest CLI via `exec`** (no auth, fastest try) → signed-in CLI (`login`/`verify`, `balance`, cashback) → MCP → API → Browse. OpenClaw has shell + MCP — prefer guest CLI for purchases unless you need typed MCP tool calls or are already signed in for `balance`.
+
+## 1. Detect OpenClaw
+
+Check **any** of:
+
+- File: `~/.openclaw/openclaw.json` exists.
+- Dir: `~/.openclaw/skills/` exists.
+- Binary: `command -v openclaw` succeeds.
+- Tools in agent loop: `gateway`, `cron`, `nodes`, `canvas`, `sessions_*` (OpenClaw-only).
+
+If yes → continue here. Otherwise → return to [SKILL.md](../SKILL.md) and pick a path.
+
+## 2. Install this skill
+
+Loader paths (increasing precedence): `skills.load.extraDirs` → bundled → `~/.openclaw/skills/` → `~/.agents/skills/` → `<workspace>/.agents/skills/` → `<workspace>/skills/`.
+
+Manual:
+
+```bash
+cp -r path/to/bitrefill ~/.openclaw/skills/bitrefill
+openclaw skills list   # verify
+openclaw gateway restart   # or /new in chat
+```
+
+ClawHub (if/when published):
+
+```bash
+openclaw skills install bitrefill
+openclaw skills update --all
+```
+
+Skill is **agentskills.io-compatible** — no rewriting needed. Source: <https://docs.openclaw.ai/tools/skills.md>.
+
+## 3. Install Bitrefill CLI (preferred — guest checkout)
+
+Pi has first-class `exec` tool on Gateway host (sandboxing **off** by default). **Start here:** no login, no MCP config — search, buy, pay crypto or send payment link.
+
+```bash
+exec: npm install -g @bitrefill/cli
+exec: bitrefill search-products --query "Netflix" --country US
+exec: bitrefill buy-products \
+  --cart_items '[{"product_id":"steam-usa","package_id":10}]' \
+  --payment_method lightning \
+  --return_payment_link true \
+  --email "user@example.com"
+```
+
+Guest flow → [cli.md](cli.md) § Guest checkout. Optional: `bitrefill init --openclaw` (skill + MCP stub only — not required for guest).
+
+**Upgrade to signed-in** when human wants store-credit cap (`balance`), cashback, or order history:
+
+```bash
+exec: bitrefill login --email you@example.com
+exec: bitrefill verify --code <email-code> [--otp <totp>]
+```
+
+Headless sign-in inbox → [cli-headless-auth.md](cli-headless-auth.md) (AgentMail or equivalent).
+
+Docker sandbox: `setupCommand: "npm install -g @bitrefill/cli"`, `network` not `none`. Source: <https://docs.openclaw.ai/gateway/sandboxing.md>.
+
+## 4. Install Bitrefill MCP (optional)
+
+Use when: typed MCP tool calls in Pi loop without shell, or MCP-native integrations. **Not required for guest try** — guest CLI is faster (zero config).
+
+```bash
+openclaw mcp set bitrefill --url "https://api.bitrefill.com/mcp"
+```
+
+Or hand-edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "bitrefill": {
+        "url": "https://api.bitrefill.com/mcp"
+      }
+    }
+  }
+}
+```
+
+Developer API key (optional): see [mcp.md](mcp.md). Guest MCP checkout may still need OAuth; **guest CLI avoids this.**
+
+Transport: SSE/HTTP or `transport: "streamable-http"`. Restrict per-agent via `agents.list[].tools.allow`/`deny`. Source: <https://docs.openclaw.ai/cli/mcp.md>.
+
+Then: see [mcp.md](mcp.md).
+
+## 5. Raw API path
+
+`exec` + `curl`, or built-in `web_fetch` tool. No special config. See [api.md](api.md).
+
+## 6. Browser
+
+Pi has `browser` tool. **It uses the Gateway host's IP** — usually residential when Gateway runs on user's machine, but a VPS will hit Cloudflare 403. For richer DOM control attach a Playwright/Chrome MCP. The Mac menubar app drives user's actual Chrome and is fully residential. See [browse.md](browse.md).
+
+## 7. OpenClaw-only scenarios
+
+These are the differentiators. None of the other hosts can do them.
+
+### Buy a gift card from Telegram (away from desk)
+
+User DMs the bot: "buy a $50 Steam US card for me". Pi runs guest CLI via `exec` (or signed-in CLI with `balance` if human pre-funded account), prompts confirmation in chat, returns payment link or redemption code after poll.
+
+**Risk**: redemption codes are cash-like. Never deliver to group chats or via `MEDIA:` URLs. Lock down channel:
+
+```jsonc
+{
+  "channels": {
+    "telegram": {
+      "botToken": "${TELEGRAM_BOT_TOKEN}",
+      "dmPolicy": "pairing",
+      "allowFrom": ["123456789"],
+      "groups": { "*": { "requireMention": true } }
+    }
+  }
+}
+```
+
+Source: <https://docs.openclaw.ai/channels/telegram>.
+
+### Auto-renew mobile top-up monthly
+
+Use `cron` + `exec: bitrefill buy-products ...` for fixed SKU. Guest: crypto + poll `get-invoice-by-id`. Signed-in: `--payment_method balance` for instant pay without on-chain wait.
+
+### Multi-channel handoff
+
+Trigger purchase from Slack, deliver redemption code only to user's private Signal DM. Same Gateway, isolated session per channel/sender.
+
+### Mobile camera context
+
+Paired iOS/Android node exposes `camera.snap` and `canvas.*`. User photographs a request ("100 EUR Decathlon France"), Pi OCRs/parses, runs `exec: bitrefill search-products` + `exec: bitrefill buy-products` (guest or signed-in). Source: <https://docs.openclaw.ai/nodes/index.md>.
+
+### Heartbeat-driven invoice polling
+
+Default 30-min heartbeat or custom `cron` runs `exec: bitrefill get-invoice-by-id` until `status: complete`, then pushes redemption code to originating channel.
+
+## 8. OpenClaw-specific safeguards
+
+OpenClaw defaults are permissive: sandboxing off, `security: full`, `ask: off`. **Tighten before letting an agent buy on your behalf.**
+
+- **Restrict who triggers purchases**: `channels.<ch>.allowFrom: ["<your_id>"]` + `dmPolicy: "pairing"`. Same for WhatsApp, Signal, Slack, Discord.
+- **Require approval for buys**: `~/.openclaw/exec-approvals.json` with `security: allowlist` + `ask: on-miss`. Allowlist read-only CLI (`bitrefill search-products`, `bitrefill get-product-details`, `bitrefill get-invoice-by-id`); force `/approve` for `bitrefill buy-products`. Same pattern if using MCP `buy-products`.
+- **Isolate Bitrefill agent**: under `agents.list[]` declare a Bitrefill-scoped persona with `tools.deny: ["gateway"]` so the agent **cannot rewrite Gateway config** to bypass approvals. Source: <https://docs.openclaw.ai/tools/exec-approvals.md>.
+- **Guest first, balance when ready**: guest CLI + payment link = lowest friction; human pre-funds account + `login`/`verify` when agent needs capped `balance` spend. **Never** give the agent crypto wallet seeds. Skill is not a wallet.
+- **No voice readback of codes**: disable `audio_as_voice` / TTS for the Bitrefill agent. Pi's media pipeline could otherwise speak a cash-like code aloud over Telegram voice notes.
+- **No `MEDIA:<url>` for redemption codes**: enforce text-only delivery for the redemption tool output.
+
+## Source of truth
+
+- OpenClaw docs: <https://docs.openclaw.ai/>
+- Skills loader: <https://docs.openclaw.ai/tools/skills.md>
+- Creating skills: <https://docs.openclaw.ai/tools/creating-skills.md>
+- MCP CLI: <https://docs.openclaw.ai/cli/mcp.md>
+- Exec tool: <https://docs.openclaw.ai/tools/exec.md>
+- Sandboxing: <https://docs.openclaw.ai/gateway/sandboxing.md>
+- Exec approvals: <https://docs.openclaw.ai/tools/exec-approvals.md>
+- Nodes: <https://docs.openclaw.ai/nodes/index.md>
+- Channels: <https://docs.openclaw.ai/channels/telegram>
+- Bitrefill skill paths: [mcp.md](mcp.md), [cli.md](cli.md), [api.md](api.md), [browse.md](browse.md), [safeguards.md](safeguards.md)

package/skills/bitrefill/references/mcp.md

@@ -0,0 +1,150 @@
+# Path: MCP
+
+**Preferred purchase channel.** Typed tool calls, OAuth or API key, no shell, works in 10+ hosts.
+
+## Two MCP servers
+
+### eCommerce MCP — for purchases
+
+URL: `https://api.bitrefill.com/mcp` (OAuth) **or** `https://api.bitrefill.com/mcp/YOUR_API_KEY` (header-less, key-in-path).
+
+7 tools:
+
+- `search-products` — keyword + country + category
+- `product-details` — packages (denominations) + pricing
+- `buy-products` — create invoice
+- `get-invoice-by-id` — poll payment status
+- `get-order-by-id` — get redemption info (codes, eSIM QR)
+- `list-invoices` — invoice history
+- `list-orders` — order history
+
+Auth: OAuth (recommended for interactive use) or API key from <https://www.bitrefill.com/account/developers>.
+
+### Development MCP — for docs only
+
+URL: `https://docs.bitrefill.com/mcp`. Indexes the docs site for code-help. **Not for purchases.** Use only when authoring an integration against the Bitrefill API/CLI.
+
+## Per-client setup
+
+### Cursor — `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "autoApprove": [
+        "search-products", "product-details",
+        "list-invoices", "get-invoice-by-id",
+        "list-orders", "get-order-by-id"
+      ]
+    }
+  }
+}
+```
+
+Keep `buy-products` **out** of `autoApprove`. Cursor caps at 40 active tools across all servers.
+
+### Claude Code
+
+With the **bitrefill** plugin installed from this repo’s marketplace, the eCommerce MCP is auto-registered; `claude mcp add` below is for manual-only setups.
+
+```bash
+claude mcp add bitrefill --url https://api.bitrefill.com/mcp
+```
+
+Or edit `~/.claude.json`. Override output cap with `MAX_MCP_OUTPUT_TOKENS` (default 25 000).
+
+### Claude Desktop — `claude_desktop_config.json`
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`. Windows: `%APPDATA%\Claude\claude_desktop_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": { "url": "https://api.bitrefill.com/mcp" }
+  }
+}
+```
+
+### Claude.ai (web) — Pro / Max / Team / Enterprise
+
+Settings → Connectors → Add custom connector → URL `https://api.bitrefill.com/mcp`. Free tier cannot add custom URLs.
+
+### ChatGPT (Plus / Pro / Business / Enterprise / Edu)
+
+Settings → Apps & Connectors → Add → URL `https://api.bitrefill.com/mcp`. Toggle **Developer Mode** to allow `buy-products` (write tool). Free tier blocked.
+
+### Codex CLI — `~/.codex/config.toml`
+
+```toml
+[mcp_servers.bitrefill]
+url = "https://api.bitrefill.com/mcp"
+bearer_token_env_var = "BITREFILL_API_KEY"
+```
+
+OAuth: `codex mcp login bitrefill`.
+
+### Gemini CLI — `~/.gemini/settings.json` (or project `.gemini/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "headers": { "Authorization": "Bearer ${BITREFILL_API_KEY}" }
+    }
+  }
+}
+```
+
+OAuth: `gemini mcp auth bitrefill`.
+
+### OpenCode — `opencode.jsonc`
+
+```jsonc
+{
+  "mcp": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "headers": { "Authorization": "Bearer ${BITREFILL_API_KEY}" }
+    }
+  }
+}
+```
+
+### OpenClaw — see [host-openclaw.md](host-openclaw.md)
+
+```bash
+openclaw mcp set bitrefill --url "https://api.bitrefill.com/mcp/$BITREFILL_API_KEY"
+```
+
+## Workflow
+
+```
+search-products  →  product-details  →  buy-products  →  get-invoice-by-id  →  get-order-by-id
+```
+
+1. **Search**: `search-products(query="Steam", country="US", product_type="giftcard")`. `country` is uppercase Alpha-2.
+2. **Details**: `product-details(product_id="steam-usa", currency="USDC")`. Returns `packages` array with `package_id` in form `{product_id}<&>{value}`.
+3. **Buy**: `buy-products(cart_items=[{product_id, package_id}], payment_method, return_payment_link=true)`. Max 15 items per call.
+   - For instant fulfillment: `payment_method: "balance"` + `auto_pay: true`.
+   - For agent-driven crypto: `payment_method: "usdc_base"` + `return_payment_link: true` → use `x402_payment_url`.
+4. **Poll**: `get-invoice-by-id(invoice_id)`. Statuses: `unpaid` → `payment_detected` → `payment_confirmed` → `complete`.
+5. **Redeem**: `get-order-by-id(order_id, include_redemption_info=true)` → returns code / link / eSIM install URL.
+
+Confirm with user before step 3. Logging per [safeguards.md](safeguards.md).
+
+## Caveats
+
+- **ChatGPT** custom MCP requires Plus+; write tools require Developer Mode (admin-enabled on workspaces).
+- **Cursor** 40-tool cap across all servers.
+- **Claude.ai** consumer needs Pro+ for custom URLs.
+- **Code-execution sandboxes** (Claude.ai analysis tool, ChatGPT Code Interpreter) have **no network egress** — they can't call MCP servers; install MCP at the chat level instead.
+
+## Source of truth
+
+- <https://docs.bitrefill.com/docs/ecommerce-mcp>
+- <https://docs.bitrefill.com/docs/development-mcp>
+- <https://docs.bitrefill.com/docs/setup-guides>
+- Per-client setup: <https://docs.bitrefill.com/docs/use-with-cursor>, `/use-with-claude-chat`, `/use-with-claude-code`, `/use-with-chatgpt`

package/skills/bitrefill/references/safeguards.md

@@ -0,0 +1,138 @@
+# Spending Safeguards
+
+This skill enables **real-money transactions**. Purchases are fulfilled instantly after payment confirms. Digital codes are non-refundable per EU consumer rights once delivered.
+
+This page is the **agent-policy layer** — not in upstream Bitrefill or host docs. Read fully before any purchase tool call.
+
+## Universal rules
+
+- **Default: always confirm before purchasing.** Present product, denomination, price, payment method. Wait for explicit user approval. Autonomous purchasing only when user explicitly opts in for the current session.
+- **Codes are cash-like.** A gift card code or eSIM QR is bearer money. Store securely. Never share publicly.
+- **Prefer in-memory storage.** Don't write codes to plain-text logs, transcripts, or unencrypted files. Programmatically read code → use it → discard.
+- **If user asks for the code**: return it but advise to (a) store securely, (b) not share, (c) redeem ASAP.
+- **Dedicated, low-balance account.** Never give the agent access to high-balance accounts. Pre-fund only what the agent may spend in the current session.
+- **Headless CLI: agent-owned inbox.** Register Bitrefill with an agent inbox ([AgentMail](https://www.agentmail.to/) or equivalent — [cli-headless-auth.md](cli-headless-auth.md)), not the human's primary email. Inbox compromise = account takeover.
+- **Not a wallet.** This skill does not store private keys or manage crypto wallets. Never give the agent seed phrases, hardware-wallet PINs, or signing keys.
+- **Log every purchase.** `invoice_id`, product slug, amount, payment method, timestamp.
+- **Refunds**: digital goods refundable only if they don't work as expected (defective code). EU 14-day change-of-mind does **not** apply.
+- **Browser redemption fallback.** If trying to redeem on a brand site triggers anti-bot, ask the user to complete redemption manually and return the code.
+
+Terms: <https://www.bitrefill.com/terms/>.
+
+## Per-host hardening
+
+### OpenClaw
+
+Defaults are permissive (sandboxing off, `security: full`, `ask: off`). Tighten:
+
+- **Prefer guest CLI via `exec`** for first purchases (no auth); sign in only when human wants `balance` cap or cashback. See [host-openclaw.md](host-openclaw.md).
+
+- `channels.<ch>.allowFrom: ["<your_id>"]` + `dmPolicy: "pairing"` on every channel.
+- `~/.openclaw/exec-approvals.json`: `security: allowlist` + `ask: on-miss`. Allowlist read tools (`bitrefill search-products`, `bitrefill list-*`, `bitrefill get-*`). Force `/approve` for `bitrefill buy-products` and the MCP `buy-products` call.
+- `agents.list[]` Bitrefill persona with `tools.deny: ["gateway"]` so the agent cannot rewrite Gateway config.
+- Disable voice readback (`audio_as_voice` / TTS) for the Bitrefill agent. Codes spoken aloud over voice notes leak.
+- Force text-only delivery — no `MEDIA:<url>` for redemption code output.
+
+Full detail in [host-openclaw.md](host-openclaw.md) §8.
+
+### Cursor
+
+`.cursor/mcp.json` `autoApprove` may include read tools. **Never** include `buy-products`:
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "autoApprove": [
+        "search-products", "product-details",
+        "list-invoices", "get-invoice-by-id",
+        "list-orders", "get-order-by-id"
+      ]
+    }
+  }
+}
+```
+
+### Codex CLI
+
+Run with sandbox + approval:
+
+```bash
+codex --sandbox workspace-write --ask-for-approval on-request
+```
+
+Put `BITREFILL_API_KEY` in a profile (`~/.codex/config.toml` `[profiles.bitrefill]`), not in committed config.
+
+### Claude Code
+
+In `~/.claude/settings.json` (or project `.claude/settings.json`):
+
+```json
+{
+  "sandbox": {
+    "filesystem": {
+      "denyRead": ["~/.ssh", ".env", "*.pem", "**/.bitrefill_token"],
+      "denyWrite": ["~/.ssh", ".env"]
+    },
+    "network": {
+      "allow": ["api.bitrefill.com", "registry.npmjs.org"]
+    }
+  }
+}
+```
+
+### Claude Desktop / Claude.ai web
+
+Per-tool approval prompts on by default. Keep them on. Don't whitelist `buy-products`.
+
+### ChatGPT (web / Desktop / Atlas / Agent)
+
+Developer Mode required for write tools. Keep it **off** unless actively purchasing. Confirm in-chat before every `buy-products`.
+
+### Gemini CLI
+
+Run with `--sandbox` (Seatbelt / Docker / gVisor). Per-shell command confirmation prompts on by default.
+
+### OpenCode
+
+Set permissions per agent:
+
+```jsonc
+{
+  "agents": {
+    "bitrefill": {
+      "permissions": {
+        "edit": "ask",
+        "bash": { "*": "ask", "bitrefill list-*": "allow", "bitrefill get-*": "allow" },
+        "webfetch": "ask"
+      }
+    }
+  }
+}
+```
+
+## Payment method risk
+
+- `balance` — instant, capped by pre-funded amount. **Lowest blast radius.**
+- `usdc_base` via x402 — autonomous payment from agent-controlled wallet. Bound the wallet balance.
+- `lightning` — fast, low fee. Manual pay or Lightning-capable agent.
+- Other on-chain crypto — slow, requires polling. Higher chance of expired invoices (180 min).
+
+Default recommendation: pre-fund `balance` with low cap → use `payment_method: "balance"` + `auto_pay: true`.
+
+## What to NEVER do
+
+- Pass redemption codes through group chats, public channels, screen-shared sessions, or shared documents.
+- Speak codes aloud via TTS / voice notes.
+- Store codes in version control, even private repos.
+- Give the agent seed phrases or hardware-wallet PINs.
+- Auto-approve `buy-products` in any host's MCP config.
+- Run the Bitrefill skill from an account with stored payment cards or high balances.
+
+## Source of truth
+
+- Bitrefill ToS: <https://www.bitrefill.com/terms/>
+- Refund policy: <https://docs.bitrefill.com/docs/refunds>
+- Path setup: [mcp.md](mcp.md), [cli.md](cli.md), [api.md](api.md), [browse.md](browse.md)
+- OpenClaw hardening: [host-openclaw.md](host-openclaw.md)

package/skills/bitrefill/references/troubleshooting.md

@@ -0,0 +1,182 @@
+# Troubleshooting
+
+Common errors across all paths. Full enum: <https://docs.bitrefill.com/docs/error-codes> and <https://docs.bitrefill.com/docs/References>.
+
+## Browse path
+
+### `403 Forbidden` when fetching bitrefill.com
+
+Cloudflare blocks datacenter IPs. Fix: switch to residential browser (ChatGPT Atlas, Cursor browser, Claude+Chrome ext, OpenClaw on user host) or pivot to MCP/CLI/API.
+
+### Product appears in listing but not purchasable
+
+Geolock at IP level. URL country only filters listed inventory; checkout enforces user's IP. Tell user to access from the matching country (or VPN) — but warn this may violate ToS.
+
+## MCP path
+
+### Tool not visible to agent
+
+- Cursor: 40-tool cap exceeded across all servers. Disable an unused MCP server.
+- ChatGPT: Developer Mode off → write tools (`buy-products`) hidden. Toggle in Settings.
+- Claude.ai consumer: Free tier cannot add custom MCP URLs. Upgrade to Pro+.
+- OpenClaw: `tools.deny: ["bundle-mcp"]` accidentally hiding the server, or per-agent `tools.allow` whitelist excluding it.
+
+### `StreamableHTTPError` with HTML body
+
+Wrong `MCP_URL` — pointing at non-Bitrefill endpoint. Unset `MCP_URL` env var or set to `https://api.bitrefill.com/mcp`.
+
+### OAuth loop in Cursor / Claude.ai
+
+Clear browser cookies for `bitrefill.com`, try a different browser, ensure pop-ups not blocked.
+
+### MCP server filtered out (OpenClaw)
+
+OpenClaw startup safety filter rejects env keys: `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4`. Use only standard `*_API_KEY` / `GITHUB_TOKEN` / proxy vars in MCP server `env` blocks.
+
+### MCP output truncated
+
+Default cap varies by host. Claude Code: `MAX_MCP_OUTPUT_TOKENS=50000` to raise. OpenClaw: `tools.toolResultMaxChars` (default 16000). Use pagination: `--per_page 25`, multiple `list-orders` calls.
+
+## CLI path
+
+### `cart_items` JSON shape error
+
+```
+# WRONG (object)
+--cart_items '{"product_id": "steam-usa", "package_id": 5}'
+
+# RIGHT (array)
+--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
+```
+
+### `Invalid denomination 'undefined'`
+
+Both `product_id` AND `package_id` required per item.
+
+### `Too big: expected array to have <=15 items`
+
+Split into multiple `buy-products` calls.
+
+### `per_page must be less than 500`
+
+Server limit. Use 500 max.
+
+### `error: required option '--<name>' not specified`
+
+Client-side validation. Add the missing option.
+
+### "Must be one of" enum errors
+
+| Option | Valid values | Common mistakes |
+|--------|--------------|-----------------|
+| `--payment_method` | `bitcoin`, `lightning`, `ethereum`, `usdc_polygon`, `usdt_polygon`, `usdc_erc20`, `usdt_erc20`, `usdc_arbitrum`, `usdc_solana`, `usdc_base`, `eth_base`, `balance` | `paypal`, `visa`, `USDC_BASE` (case-sensitive) |
+| `--product_type` | `giftcard`, `esim` | `giftcards`, `gift_card`, `sim` |
+| `--country` | `US`, `IT`, `BR` (uppercase Alpha-2) | `us`, `USA`, `"United States"` |
+
+### Wrong `package_id` for named denominations
+
+Exact, case-sensitive. WRONG `"1GB"`, `"300 nc"`. RIGHT `"1GB, 7 Days"`, `"PUBG New State 300 NC"`. Get exact strings from `get-product-details` `packages` array.
+
+### Compound key in `package_id`
+
+```
+# WRONG
+--cart_items '[{"product_id": "steam-usa", "package_id": "steam-usa<&>5"}]'
+
+# RIGHT (value after <&>)
+--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
+```
+
+### CLI auth failure (≥ 0.3.0)
+
+CLI uses OAuth client_credentials + email magic link — not API keys, not browser OAuth.
+
+```bash
+bitrefill reset                                    # clear corrupt state
+bitrefill login --email you@example.com
+bitrefill verify --code 123456                     # add --otp for TOTP
+bitrefill whoami --json
+```
+
+| Error | Fix |
+|-------|-----|
+| `Access token is required for login/verify` | Any command first (MCP connect), or `reset` then retry |
+| `No pending login` | Run `login --email` before `verify` |
+| `No OTP code provided` on verify | Account has 2FA — add `--otp` (authenticator), keep `--code` (email magic link) |
+| `Invalid code` on verify | Wrong email code or wrong TOTP; don't swap them — email code → `--code`, authenticator → `--otp` |
+| `unknown option '--code'` on login | Code goes on `verify --code`, not `login` |
+| `unknown command 'login'` | Already signed in — `logout` first |
+| `Failed to establish a session` | `reset`, then retry |
+| Invalid / expired code | Re-run `login --email`; headless → poll agent inbox (AgentMail or equivalent — [cli-headless-auth.md](cli-headless-auth.md)) |
+| Missing TOTP | `verify --code … --otp "$(op read 'op://Vault/Item/one-time password?attribute=otp')"` |
+
+State: `~/.config/bitrefill-cli/<host>.v1.json`. `logout` revokes session; `reset` clears everything.
+
+Pre-0.3.0 (`credentials.json`, `--api-key`): upgrade CLI. Developer API keys still work for [mcp.md](mcp.md) / [api.md](api.md) paths only.
+
+### Empty search results, no error
+
+`found: 0` with no error message. Causes:
+
+- `--category` slug doesn't exist (silent miss).
+- Product not available in `--country`.
+- `--in_stock true` (default) filters out-of-stock.
+
+Fix: drop `--category`, change `--country`, or `--in_stock false`.
+
+### Unpaid invoices missing from list
+
+`list-invoices` defaults `--only_paid true`. Use `--only_paid false`.
+
+## API path
+
+### `401 Unauthorized`
+
+- Personal: `Authorization: Bearer $BITREFILL_API_KEY` missing or wrong key.
+- Business / Affiliate: `Authorization: Basic $(echo -n "$ID:$SECRET" | base64)` malformed.
+
+### `429 Too Many Requests`
+
+Rate limited. Defaults: 60 req / 10 min on most endpoints, 60 req/min on `/products` + `/products/search` plus 1000 product req/hr quota, 1 req / 3 s on `/ping`. Back off + retry. Cache product catalog locally.
+
+### `RESOURCE_NOT_FOUND` on `GET /invoices/{id}`
+
+Bad invoice ID. Verify via `list-invoices`.
+
+### `Product '{slug}' is not available`
+
+Bad product slug. Verify via `search-products`.
+
+### Invoice expired
+
+Invoices expire after **180 minutes**. Cannot re-pay. Create new one.
+
+## OpenClaw-specific
+
+### Cron purchase failed silently
+
+`exec-approvals.json` set to `ask: on-miss` but no operator online to `/approve`. Either pre-approve `bitrefill buy-products` for trusted SKU/amount, or schedule when operator available.
+
+### Pi agent can't see the Bitrefill MCP
+
+Check:
+
+1. `openclaw mcp list` shows entry.
+2. `~/.openclaw/openclaw.json` parses (no trailing commas).
+3. Agent profile not denying `bundle-mcp` or whitelisting tools narrowly.
+4. CLI signed in (`bitrefill whoami --json`) or MCP OAuth completed — not just shell env vars.
+
+### Mobile node camera tool unavailable
+
+Node not paired or paired but offline. Check `openclaw nodes list`. Re-pair via Control UI (`openclaw dashboard`).
+
+### Telegram message not reaching agent
+
+`channels.telegram.dmPolicy: "pairing"` and sender not paired. Run `openclaw pairing approve telegram <CODE>` (codes expire 1 hr).
+
+## Source of truth
+
+- Bitrefill error codes: <https://docs.bitrefill.com/docs/error-codes>
+- Bitrefill error handling: <https://docs.bitrefill.com/docs/References>
+- Rate limits: <https://docs.bitrefill.com/docs/rate-limits>
+- OpenClaw troubleshooting: <https://docs.openclaw.ai/help> + per-tool pages

package/skills/kaleido-trading/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: kaleido-trading
+description: "Trade and manage a portfolio on KaleidoSwap: get live prices and market data, quote and place atomic swaps between BTC and RGB assets (USDT, XAUT), acquire inbound liquidity from the LSP, and check positions. Triggers when the user wants a price, a quote, to swap or trade assets, to rebalance a portfolio, or to acquire a Lightning channel from the LSP."
+tools: get_price, get_market_data, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_place_order, kaleidoswap_get_order_status, kaleidoswap_get_position, kaleidoswap_lsp_get_info, kaleidoswap_lsp_create_order
+triggers: price, quote, swap, trade, rebalance, portfolio, market, slippage, liquidity, channel order
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+  surface: "kaleido-mcp (KaleidoSwap maker + market data)"
+---
+
+# KaleidoSwap trading
+
+Quote, swap, and manage a portfolio through the KaleidoSwap maker and market
+data MCP tools.
+
+## Flow
+
+1. **Price first.** Use `get_price` / `get_market_data` for context and
+   `kaleidoswap_get_quote` for an executable price before proposing a trade.
+2. **Confirm the trade.** Show pair, direction, amount in, expected amount out,
+   and fees. Wait for explicit approval before `kaleidoswap_place_order`.
+3. **Track it.** After placing, poll `kaleidoswap_get_order_status` until the
+   swap settles, then report the result and the new `kaleidoswap_get_position`.
+4. **Need inbound liquidity?** If a swap can't route for lack of a channel, use
+   `kaleidoswap_lsp_get_info` then `kaleidoswap_lsp_create_order` to buy one.
+
+## Rules
+
+- Never trade on a stale quote — re-quote if the user hesitates.
+- Surface slippage and fees explicitly; small local models must not hide cost.