@kaleidorg/mind 0.0.1 → 0.2.0

package/dist/wallet/contract.js

@@ -0,0 +1,113 @@
+/**
+ * Canonical multi-L2 wallet tool contract — the single source of truth for
+ * KaleidoMind's wallet tools (names + JSON schemas + spend flags).
+ *
+ * Every surface implements THESE EXACT tools, only the transport differs:
+ *   - mobile  → in-process handlers over the WDK adapters (`bindWalletTools`)
+ *   - desktop → kaleido-mcp (tools namespaced per layer) + a `kaleido` CLI
+ *   - eval    → stub handlers
+ *
+ * Because the schemas are identical everywhere, skills are portable and the
+ * model comparison is honest. Tools are namespaced per layer (`spark_*`,
+ * `rln_*`, `arkade_*`, `liquid_*`); cross-cutting router/helpers are unprefixed.
+ *
+ * Spend tools (move funds) carry `spend: true` → `requiresConfirmation: true`,
+ * so the Engine always pauses for the host's confirm gate before executing.
+ *
+ * Pure data — no deps, RN-safe.
+ */
+import { InProcessToolSource } from '../tools/in-process.js';
+function t(layer, name, description, properties = {}, required = [], spend = false) {
+    return {
+        layer,
+        name,
+        description,
+        spend,
+        requiresConfirmation: spend,
+        parameters: { type: 'object', properties, required },
+    };
+}
+const sats = { type: 'number', description: 'Amount in satoshis' };
+const asset = { type: 'string', description: "Asset ticker, e.g. 'USDT', 'XAUT', 'BTC'" };
+/** The full contract. Keep descriptions terse — small models read every word. */
+export const WALLET_TOOLS = [
+    // ── Spark ──────────────────────────────────────────────────────────────
+    t('spark', 'spark_get_balance', 'Get the Spark wallet BTC balance.'),
+    t('spark', 'spark_get_address', 'Get a Spark deposit address to receive BTC.'),
+    t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice to receive BTC.', { amount_sats: sats }),
+    t('spark', 'spark_send', 'Send BTC from Spark to an address or invoice.', { amount_sats: sats, to: { type: 'string', description: 'Address or invoice' } }, ['amount_sats', 'to'], true),
+    // ── RLN / RGB ──────────────────────────────────────────────────────────
+    t('rln', 'rln_get_balances', 'Get RLN node balances (BTC + RGB assets).'),
+    t('rln', 'rln_get_node_info', 'Get RLN node status and sync state.'),
+    t('rln', 'rln_list_channels', 'List the RLN node Lightning channels.'),
+    t('rln', 'rln_create_ln_invoice', 'Create a Lightning (BTC) invoice on the RLN node.', { amount_sats: sats }),
+    t('rln', 'rln_create_rgb_invoice', 'Create an RGB asset invoice to receive an asset (e.g. USDT).', { asset, amount: { type: 'number', description: 'Asset amount' } }, ['asset', 'amount']),
+    t('rln', 'rln_pay_invoice', 'Pay a Lightning invoice from the RLN node.', { invoice: { type: 'string' } }, ['invoice'], true),
+    t('rln', 'rln_send_asset', 'Send an RGB asset (e.g. USDT) to a recipient.', { asset, amount: { type: 'number' }, to: { type: 'string' } }, ['asset', 'amount', 'to'], true),
+    // ── Arkade ─────────────────────────────────────────────────────────────
+    t('arkade', 'arkade_get_balance', 'Get the Arkade wallet balance.'),
+    t('arkade', 'arkade_get_address', 'Get an Arkade address to receive funds.'),
+    t('arkade', 'arkade_send', 'Send BTC from Arkade to a recipient.', { amount_sats: sats, to: { type: 'string' } }, ['amount_sats', 'to'], true),
+    // ── Liquid (later) ─────────────────────────────────────────────────────
+    t('liquid', 'liquid_get_balance', 'Get the Liquid wallet balance (L-BTC + assets).'),
+    t('liquid', 'liquid_create_invoice', 'Create a Liquid invoice/address to receive (L-BTC or L-USDt).', { asset, amount: { type: 'number' } }),
+    t('liquid', 'liquid_send', 'Send a Liquid asset (L-BTC or L-USDt) to a recipient.', { asset, amount: { type: 'number' }, to: { type: 'string' } }, ['asset', 'amount', 'to'], true),
+    // ── Core: router + helpers ─────────────────────────────────────────────
+    t('core', 'get_balances', 'Get balances across all layers (or one layer).', { layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'], description: 'Optional: a single layer' } }),
+    t('core', 'resolve_contact', 'Resolve a contact name to a Lightning address / Nostr / preferred rail.', { name: { type: 'string', description: 'Contact name, e.g. "bob"' } }, ['name']),
+    t('core', 'get_price', 'Get the current price of an asset, optionally in a fiat currency.', { asset, fiat: { type: 'string', description: "Fiat code, e.g. 'EUR', 'USD'" } }),
+    t('core', 'fiat_to_sats', 'Convert a fiat amount to satoshis at the current rate.', { amount: { type: 'number' }, currency: { type: 'string', description: "Fiat code, e.g. 'EUR'" } }, ['amount', 'currency']),
+    t('core', 'get_swap_quote', 'Quote a swap between two assets.', { from_asset: asset, to_asset: asset, amount: { type: 'number' } }, ['from_asset', 'to_asset', 'amount']),
+    t('core', 'execute_swap', 'Execute a previously quoted swap.', { quote_id: { type: 'string' }, from_asset: asset, to_asset: asset, amount: { type: 'number' } }, [], true),
+    // The high-level entry a skill prefers — picks the rail for the asset, or uses `layer`.
+    t('core', 'send_payment', 'Send a payment, automatically choosing the best layer for the asset (or use `layer`).', { asset, amount_sats: sats, to: { type: 'string', description: 'Contact, address, or invoice' }, layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'] } }, ['to'], true),
+    // High-level receive — picks the right invoice/address tool for the asset/layer.
+    t('core', 'create_invoice', 'Create an invoice or address to receive funds, choosing the rail for the asset (or use `layer`). Omit amount for an any-amount invoice.', { asset, amount: { type: 'number', description: 'Amount (sats for BTC, asset units otherwise) — optional' }, layer: { type: 'string', enum: ['spark', 'rln', 'arkade', 'liquid'] } }),
+];
+// ── Selectors ───────────────────────────────────────────────────────────────
+export const WALLET_LAYERS = ['spark', 'rln', 'arkade', 'liquid', 'core'];
+/** Names of all spend (fund-moving) tools — these are confirmation-gated. */
+export const SPEND_TOOLS = new Set(WALLET_TOOLS.filter((x) => x.spend).map((x) => x.name));
+export function isSpendTool(name) {
+    return SPEND_TOOLS.has(name);
+}
+export function getWalletTool(name) {
+    return WALLET_TOOLS.find((x) => x.name === name);
+}
+/** Pick the contract tools for the given layers (core helpers included by default). */
+export function walletTools(opts = {}) {
+    const layers = new Set(opts.layers ?? ['spark', 'rln', 'arkade', 'liquid']);
+    if (opts.includeCore !== false)
+        layers.add('core');
+    return WALLET_TOOLS.filter((x) => layers.has(x.layer));
+}
+/** Strip to plain ToolDefs (drop the layer/spend metadata). */
+export function toToolDefs(tools) {
+    return tools.map(({ name, description, parameters, requiresConfirmation }) => ({ name, description, parameters, requiresConfirmation }));
+}
+/**
+ * Bind contract tools to in-process handlers → an InProcessToolSource. The
+ * mobile (and eval) binding: pass a map of `{ toolName: handler }` and you get a
+ * ToolSource implementing the canonical schemas with spend flags preserved.
+ */
+export function bindWalletTools(handlers, opts = {}) {
+    const tools = walletTools(opts);
+    const bound = [];
+    for (const def of tools) {
+        const handler = handlers[def.name];
+        if (!handler) {
+            if (opts.allowMissing)
+                continue;
+            throw new Error(`bindWalletTools: no handler for "${def.name}"`);
+        }
+        bound.push({
+            name: def.name,
+            description: def.description,
+            parameters: def.parameters,
+            requiresConfirmation: def.requiresConfirmation,
+            handler,
+        });
+    }
+    return new InProcessToolSource(opts.id ?? 'wallet', bound);
+}
+//# sourceMappingURL=contract.js.map

package/dist/wallet/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/wallet/contract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaleidorg/mind",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Local-first reasoning + function-calling engine for KaleidoSwap. QVAC-powered.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,21 +16,31 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     },
     "./mcp": {
+      "types": "./dist/tools/mcp.d.ts",
       "import": "./dist/tools/mcp.js",
-      "types": "./dist/tools/mcp.d.ts"
+      "default": "./dist/tools/mcp.js"
+    },
+    "./skills": {
+      "types": "./dist/skills/loader.d.ts",
+      "import": "./dist/skills/loader.js",
+      "default": "./dist/skills/loader.js"
     },
     "./logger": {
+      "types": "./dist/logger.d.ts",
       "import": "./dist/logger.js",
-      "types": "./dist/logger.d.ts"
+      "default": "./dist/logger.js"
     }
   },
   "files": [
     "dist",
     "src",
+    "skills",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
@@ -38,7 +48,8 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "lint": "eslint src"
+    "lint": "eslint src",
+    "bundle-skills": "node scripts/bundle-skills.mjs"
   },
   "devDependencies": {
     "vitest": "^1.6.0"

package/scripts/bundle-skills.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * bundle-skills — serialise one or more skill directories into a SkillBundle
+ * JSON file, so hosts without a filesystem (React Native) can load the same
+ * SKILL.md skills the Node fs loader reads.
+ *
+ * Usage:
+ *   node bundle-skills.mjs --out <file.json> <skills-dir> [<more-dirs>...]
+ *
+ * Example (mobile: ship the packaged bitrefill skill + the app's own skills):
+ *   node bundle-skills.mjs --out ./skills.bundle.json \
+ *     node_modules/@kaleidorg/mind/skills/bitrefill ./skills
+ *
+ * Each positional arg may be either a single skill folder (contains SKILL.md)
+ * or a parent folder of skill folders. References under <skill>/references/*.md
+ * are inlined. The output matches the `SkillBundle` type in src/skills/bundle.ts.
+ */
+
+import { readdirSync, readFileSync, existsSync, writeFileSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+function parseArgs(argv) {
+  const dirs = [];
+  let out = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--out') out = argv[++i];
+    else dirs.push(argv[i]);
+  }
+  if (!out || dirs.length === 0) {
+    console.error('usage: bundle-skills.mjs --out <file.json> <skills-dir> [<more-dirs>...]');
+    process.exit(2);
+  }
+  return { out, dirs };
+}
+
+function readSkillFolder(dir) {
+  const md = join(dir, 'SKILL.md');
+  if (!existsSync(md)) return null;
+  const refDir = join(dir, 'references');
+  const references = existsSync(refDir)
+    ? readdirSync(refDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((name) => ({ name, content: readFileSync(join(refDir, name), 'utf8') }))
+    : [];
+  return {
+    dir: basename(dir),
+    markdown: readFileSync(md, 'utf8'),
+    ...(references.length ? { references } : {}),
+  };
+}
+
+/** Expand a path into skill folders: itself if it has a SKILL.md, else its children. */
+function collectSkillDirs(path) {
+  if (!existsSync(path)) {
+    console.error(`bundle-skills: path not found: ${path}`);
+    return [];
+  }
+  if (existsSync(join(path, 'SKILL.md'))) return [path];
+  return readdirSync(path)
+    .map((e) => join(path, e))
+    .filter((p) => statSync(p).isDirectory() && existsSync(join(p, 'SKILL.md')))
+    .sort();
+}
+
+const { out, dirs } = parseArgs(process.argv.slice(2));
+const seen = new Set();
+const skills = [];
+for (const arg of dirs) {
+  for (const skillDir of collectSkillDirs(arg)) {
+    const s = readSkillFolder(skillDir);
+    if (!s) continue;
+    if (seen.has(s.dir)) {
+      console.error(`bundle-skills: duplicate skill folder "${s.dir}" — skipping ${skillDir}`);
+      continue;
+    }
+    seen.add(s.dir);
+    skills.push(s);
+  }
+}
+
+const bundle = { version: 1, skills };
+writeFileSync(out, JSON.stringify(bundle, null, 2));
+console.error(`bundle-skills: wrote ${skills.length} skill(s) → ${out} [${skills.map((s) => s.dir).join(', ')}]`);

package/skills/README.md

@@ -0,0 +1,74 @@
+# Skills
+
+Claude-style **Agent Skills** the KaleidoMind brain (QVAC) loads at runtime.
+Skills are the top layer of tool use: entering one injects a focused playbook
+into the system prompt and (optionally) scopes the model to a subset of tools —
+*progressive disclosure*, so a small local model never sees every tool or
+instruction at once.
+
+Each subfolder is a skill: a `SKILL.md` (YAML frontmatter + playbook) plus
+optional `references/*.md` files loaded on demand. The format is the Anthropic
+Agent Skills spec, so skills published for Claude (e.g. `bitrefill/agents`) run
+the QVAC brain unchanged.
+
+## Frontmatter
+
+```yaml
+---
+name: my-skill                 # required — stable id
+description: When to use this…  # required — selection signal (embed triggers here)
+tools: tool_a, tool_b          # optional — scope the model to these tools
+triggers: foo, bar             # optional — keywords that boost selection
+metadata:                      # optional — anything else (author, version, …)
+  author: kaleidoswap
+---
+# Playbook
+Markdown instructions injected into the system prompt when this skill is active.
+```
+
+## Loading (same skills, every surface)
+
+**Node** (desktop sidecar, kaleidoagent) — read folders from disk:
+
+```ts
+import { loadSkillsDir, packagedSkillsDir } from '@kaleidorg/mind/skills';
+import { SkillRegistry, createSkillReferenceToolSource } from '@kaleidorg/mind';
+
+const skills = loadSkillsDir(packagedSkillsDir());   // these shipped skills
+const registry = new SkillRegistry(skills);
+const refSource = createSkillReferenceToolSource(registry); // read_skill_reference
+```
+
+**React Native** (rate) — no filesystem, so bundle the folders to JSON at build
+time and rehydrate:
+
+```bash
+node node_modules/@kaleidorg/mind/scripts/bundle-skills.mjs \
+  --out skills.bundle.json ./skills
+```
+```ts
+import { SkillRegistry, skillsFromBundle } from '@kaleidorg/mind';
+import bundle from './skills.bundle.json';
+const registry = new SkillRegistry(skillsFromBundle(bundle));
+```
+
+Then per query: `const skill = registry.select(query)` →
+`registry.compose(systemPrompt, skill)` → pass `{ system, allowedTools }` to
+`engine.runAgentic(...)`.
+
+## Adding a skill
+
+1. Create `skills/<name>/SKILL.md` (and `references/*.md` if needed).
+2. Node hosts pick it up automatically. For mobile, re-run the bundler.
+3. That's it — no code changes. The selector routes to it by description/triggers.
+
+## Shipped skills
+
+- **bitrefill/** — official Bitrefill agent skill (gift cards, mobile top-ups,
+  eSIMs; pay in crypto / Lightning / USDC-x402 / balance). Capability-routes to
+  the best channel; preferred purchase path is the Bitrefill remote MCP at
+  `https://api.bitrefill.com/mcp` (needs `BITREFILL_API_KEY` — anonymous = 401).
+  Source: https://github.com/bitrefill/agents (MIT). Update with
+  `npx skills add bitrefill/agents` or re-vendor the folder.
+- **kaleido-wallet/** — balances, receive, pay, channels over `kaleido-mcp`.
+- **kaleido-trading/** — prices, quotes, atomic swaps, LSP channels.

package/skills/bitrefill/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: bitrefill
+description: "Buy or browse Bitrefill — 1,500+ gift cards, mobile top-ups, and eSIMs across 180+ countries, payable in crypto, Lightning, USDC via x402, or pre-funded account balance. Routes the host agent to its highest-fidelity channel (residential browser, MCP server, npm CLI, or REST API) based on detected runtime capabilities, with a dedicated OpenClaw integration guide for chat-channel scenarios. Triggers when the user mentions Bitrefill, gift cards, mobile top-up, eSIM data plan, refilling a phone, or asks to pay or check out with crypto, Lightning, USDC, or x402."
+compatibility: "Detects host capabilities at runtime. Paths require: browse — residential-IP browser; MCP — MCP-capable client + Bitrefill OAuth/API key; CLI — Node.js >=18 + shell + npm + @bitrefill/cli >=0.3.0 (headless login/verify via magic link); API — outbound HTTP + Bitrefill API key (Personal) or API ID/Secret (Business/Affiliate). OpenClaw host gets a dedicated guide."
+metadata:
+  author: bitrefill
+  version: "2.1.5"
+  homepage: "https://www.bitrefill.com"
+  docs: "https://docs.bitrefill.com"
+  repository: "https://github.com/bitrefill/cli"
+---
+
+# Bitrefill
+
+Bitrefill sells digital goods (gift cards, mobile top-ups, eSIMs) across 180+ countries and 1,500+ brands. Pay with crypto, Lightning, USDC via x402, or pre-funded account balance. Codes deliver instantly after payment confirms.
+
+This skill **routes by capability, not by use case**. Same intent ("buy a Steam card") plays out differently across hosts. Pick a path below based on what your runtime can do.
+
+## Pick a path
+
+Walk these checks **in order**. First match wins.
+
+1. **Inside OpenClaw?** Check for `~/.openclaw/openclaw.json`, `~/.openclaw/skills/`, or `openclaw` on PATH. If yes → read [host-openclaw.md](references/host-openclaw.md) first. **Default purchase path: guest CLI via `exec`** (no auth). Sign in for `balance`/cashback. OpenClaw also supports MCP, API, Browse, chat-channel scenarios (Telegram, cron, mobile camera).
+
+2. **Browse-only intent (no purchase)?** If the user only wants to explore, compare prices, or learn how products work:
+   - Have a residential-IP browser (ChatGPT Atlas, Cursor browser tool, Claude/Playwright Chrome extension, OpenClaw on user host)? → [browse.md](references/browse.md).
+   - Datacenter egress only (ChatGPT web/Agent, Gemini consumer, Jules)? `www.bitrefill.com` returns **403 Cloudflare** to datacenter IPs. Use [mcp.md](references/mcp.md) `search-products` / `product-details` instead — they return the same catalog without scraping.
+
+3. **MCP supported?** Bitrefill ships a remote HTTP/SSE MCP at `https://api.bitrefill.com/mcp`. Works on Claude.ai (Pro+), Cowork, Claude Desktop, Claude Code, ChatGPT (Plus+), Atlas, Codex CLI, Gemini CLI, Cursor, OpenCode, OpenClaw. **Highest-fidelity purchase channel — typed tool calls, OAuth or API key, no shell needed.** → [mcp.md](references/mcp.md).
+
+4. **Shell + `npm install` available?** CLI ≥ 0.3.0: **guest checkout first** (no auth — `buy-products --email` + crypto). Sign in for `balance`, cashback, order history. → [cli.md](references/cli.md). Headless sign-in → [cli-headless-auth.md](references/cli-headless-auth.md).
+
+5. **Outbound HTTP from agent loop?** Anywhere shell exists, plus Claude Code `WebFetch`. Last resort — verbose, no typed validation. → [api.md](references/api.md).
+
+6. **None of the above** (e.g. Gemini consumer free tier): give the user a `bitrefill.com` link and stop.
+
+Don't know which host you're in? Read [capability-matrix.md](references/capability-matrix.md) — per-client cheat sheet maps every leading agent product to its viable paths.
+
+## Top spending safeguards (read full list before any purchase)
+
+This skill enables **real-money transactions**. Codes deliver instantly and digital goods are non-refundable per EU consumer rights.
+
+- **Confirm before buying.** Present product, denomination, price, payment method. Wait for explicit user approval. Autonomous purchasing only when user opts in for the current session.
+- **Treat codes as cash.** Never paste in group chats or public channels. Prefer in-memory storage over plain-text logs. Advise user to redeem ASAP.
+- **Use a dedicated, low-balance account.** Never give the agent access to high-balance accounts or crypto wallet seeds. This skill is **not a wallet**.
+- **Log every purchase.** `invoice_id`, product, amount, payment method.
+
+Full safeguards + per-host hardening (OpenClaw exec-approvals, Cursor auto-approve, Codex sandbox, Claude Code allowlist) → [safeguards.md](references/safeguards.md).
+
+## References
+
+| File | Use when |
+|------|----------|
+| [browse.md](references/browse.md) | Agent has residential-IP browser; user wants to explore |
+| [mcp.md](references/mcp.md) | MCP-capable host; preferred purchase path |
+| [cli.md](references/cli.md) | Shell + npm; guest checkout or signed-in CLI ≥ 0.3.0 |
+| [cli-headless-auth.md](references/cli-headless-auth.md) | AgentMail or equivalent inbox + magic-link auth for headless agents |
+| [api.md](references/api.md) | HTTP-only runtime; Personal / Business / Affiliate REST tiers |
+| [host-openclaw.md](references/host-openclaw.md) | OpenClaw Gateway — guest CLI via `exec` preferred |
+| [capability-matrix.md](references/capability-matrix.md) | Per-client viable paths cheat sheet |
+| [safeguards.md](references/safeguards.md) | Spending policy + per-host hardening |
+| [troubleshooting.md](references/troubleshooting.md) | Common errors across all paths |
+
+## Source of truth
+
+Skill summarizes and routes. For exhaustive enums (countries, payment methods, full endpoint list), follow link-outs to <https://docs.bitrefill.com>.

package/skills/bitrefill/references/api.md

@@ -0,0 +1,99 @@
+# Path: REST API
+
+Use when: outbound HTTP available but no MCP and no shell. Last resort — verbose, no typed validation. Examples below use `curl` but any HTTP client works.
+
+Base URL: `https://api.bitrefill.com/v2`
+
+## Three tiers
+
+| Tier | Auth | Use case |
+|------|------|----------|
+| Personal | Bearer token | Personal projects, agent automation |
+| Business | Basic auth (`API_ID:API_SECRET`) | Platforms, resellers, BRGC batches, deposits, test products |
+| Affiliate | Basic auth | Same as Business + commission tracking, results filtered by `referrer_id` |
+
+## Personal API (agent default)
+
+Get key: <https://www.bitrefill.com/account/developers>.
+
+```bash
+export BITREFILL_API_KEY=YOUR_API_KEY
+H="Authorization: Bearer $BITREFILL_API_KEY"
+
+# 1. Ping
+curl -H "$H" https://api.bitrefill.com/v2/ping
+# → {"data":{"message":"pong"}}
+
+# 2. Balance
+curl -H "$H" https://api.bitrefill.com/v2/accounts/balance
+
+# 3. Search
+curl -H "$H" "https://api.bitrefill.com/v2/products/search?q=amazon"
+
+# 4. Product details
+curl -H "$H" https://api.bitrefill.com/v2/products/amazon-us
+
+# 5. Buy (balance, instant)
+curl -X POST -H "$H" -H "Content-Type: application/json" \
+  -d '{
+    "products": [{"product_id":"amazon-us","package_id":"amazon-us<&>50","quantity":1}],
+    "payment_method": "balance",
+    "auto_pay": true
+  }' \
+  https://api.bitrefill.com/v2/invoices
+
+# 6. Order / redemption
+curl -H "$H" https://api.bitrefill.com/v2/orders/{order_id}
+# → data.redemption_info.code, .link, .pin, .instructions
+```
+
+For crypto: omit `auto_pay`, set `payment_method: "bitcoin"|"lightning"|"usdc_base"|...`, include `refund_address` for crypto methods, then poll `GET /invoices/{id}` until `status: "complete"`.
+
+## Business API
+
+Apply: <https://www.bitrefill.com/integrate>.
+
+```bash
+TOKEN=$(printf "%s:%s" "$BITREFILL_API_ID" "$BITREFILL_API_SECRET" | base64)
+H="Authorization: Basic $TOKEN"
+
+curl -H "$H" https://api.bitrefill.com/v2/ping
+```
+
+Adds: BRGC (Bitrefill Reusable Gift Card) batches, account deposits via crypto, full product catalog including test products. Same endpoints + `POST /brgc-batches`, `POST /accounts/deposit`.
+
+## Affiliate API
+
+Apply: <https://www.bitrefill.com/affiliate>. Same auth as Business. Adds `GET /commissions` with `after`/`before` date filters. Order/invoice queries return data filtered by `referrer_id` instead of `user_id`.
+
+## Key endpoints
+
+- `GET /ping` — health check (1 req / 3 s)
+- `GET /accounts/balance` — current balance
+- `GET /products` — paginated catalog (cache locally, refresh daily; 1000 product req/hr quota shared with search)
+- `GET /products/search?q=...` — keyword search
+- `GET /products/{id}` — product details with `packages` array
+- `POST /invoices` — create invoice (max 20 products)
+- `POST /invoices/{id}/pay` — pay unpaid balance invoice
+- `GET /invoices/{id}` — status
+- `GET /orders/{id}` — redemption info
+- `POST /esims` — create eSIM invoice (or top-up existing via `esim_id`)
+- `GET /esims` / `GET /esims/{id}` — list / get user eSIMs
+
+Webhooks: `webhook_url` field on invoice creation → notification when delivered.
+
+## Test products
+
+Business/Affiliate only. No money charged. Examples: `test-gift-card-code`, etc. Full list: <https://docs.bitrefill.com/docs/test-products>.
+
+## Rate limits
+
+Most endpoints 60 req / 10 min. `/products` and `/products/search` 60 req/min + 1000 product req/hr quota. `/ping` 1 req / 3 s. Full table: <https://docs.bitrefill.com/docs/rate-limits>.
+
+## Source of truth
+
+- <https://docs.bitrefill.com/docs/api-overview> — tier comparison + auth
+- <https://docs.bitrefill.com/docs/quickstart-2> — 6-step purchase flow
+- <https://docs.bitrefill.com/reference> — full endpoint catalog
+- <https://docs.bitrefill.com/docs/error-codes> — error codes
+- <https://docs.bitrefill.com/docs/webhooks> — webhook payload spec

package/skills/bitrefill/references/browse.md

@@ -0,0 +1,71 @@
+# Path: Browse the Website
+
+Use when: user wants to **explore** Bitrefill (compare prices, learn product types, check denominations, see country availability) AND your runtime has a **residential-IP browser**. Browse-only by default — for purchases prefer [mcp.md](mcp.md).
+
+## Hard requirement: residential IP
+
+`www.bitrefill.com` sits behind Cloudflare. **Datacenter egress = 403.** Do NOT use Firecrawl, raw `fetch`, `curl`, or any scraping API.
+
+Viable runtimes:
+
+- **ChatGPT Atlas** — built-in residential Chromium.
+- **Cursor** — built-in browser tool runs from user's machine.
+- **Claude Code / Desktop / Cowork + Claude-for-Chrome** extension drives local Chrome.
+- **Any host + Playwright/Chrome MCP** running on user's machine.
+- **OpenClaw Gateway on user's host** — `browser` tool uses host IP. (See [host-openclaw.md](host-openclaw.md).)
+
+Not viable: ChatGPT web/Agent (OpenAI datacenter), Gemini consumer (Google datacenter), Jules (Google VM), any cloud sandbox without residential proxy.
+
+## URL patterns
+
+First path segment = **country** (Alpha-2 lowercase). Second = **language**.
+
+- Gift cards listing: `https://www.bitrefill.com/{country}/{lang}/gift-cards/`
+- Gift card category: `https://www.bitrefill.com/{country}/{lang}/gift-cards/{category-slug}/` (e.g. `/us/en/gift-cards/food/`)
+- Gift card product: `https://www.bitrefill.com/{country}/{lang}/gift-cards/{product-slug}/`
+- Direct search: `https://www.bitrefill.com/{country}/{lang}/gift-cards/?q={query}` (covers gift cards + top-ups + eSIMs; in-country prioritized)
+- Mobile top-ups: `https://www.bitrefill.com/refill/`
+- eSIMs (locale): `https://www.bitrefill.com/{country}/{lang}/esims/`
+- eSIMs (browse all destinations): `https://www.bitrefill.com/esim/all-destinations`
+- Single eSIM: `https://www.bitrefill.com/{country}/{lang}/esims/bitrefill-esim-{destination-slug}/` (e.g. `bitrefill-esim-japan`, `bitrefill-esim-global`)
+- Auth (no locale prefix): `/login`, `/signup`
+
+## Country in URL vs geolock
+
+- **URL country** filters which inventory is **listed**.
+- **Geolock** is enforced at **IP level** at checkout. A product may appear in listing but be unpurchasable if user's IP is outside allowed region.
+
+Match URL country to recipient's country to surface usable cards.
+
+## Listing filters & sort (gift cards)
+
+Query params on any gift-card listing (`/{country}/{lang}/gift-cards/[category/]`):
+
+- `redemptionMethod` — `online` | `instore`
+- `minRating` — `2` | `3` | `4` | `5`
+- `minRewards` — `1`–`10` (cashback %)
+- `s` — sort: `2` = A–Z, `3` = recently added, `4` = cashback. Default = popularity.
+
+Example: `https://www.bitrefill.com/us/en/gift-cards/food/?minRating=5&minRewards=4&redemptionMethod=instore`
+
+## Categories (popular slugs)
+
+`top-products`, `retail`, `apparel`, `electronics`, `food`, `restaurants`, `food-delivery`, `streaming`, `games`, `travel`, `flights`, `accommodation`, `entertainment`, `gasoline`, `vpn`, `multi-brand`, `digital-wallet`, `groceries`, `pharmacy`, `experiences`, `gifts`. Full list: <https://docs.bitrefill.com/docs/Products>.
+
+## Suggested flow
+
+1. Clarify product type (gift card / top-up / eSIM) + country (+ carrier for top-ups).
+2. Send user to direct search URL or category path.
+3. For top-ups: country → carrier → amount.
+4. For eSIMs: destination → data + duration.
+5. Remind user to check denomination matches recipient's needs and that geolock applies at checkout.
+
+## Purchase from the browser?
+
+Possible but slow and risky. Anti-bot may block agent on brand redemption sites. Prefer [mcp.md](mcp.md) or [cli.md](cli.md) for purchases. If browser checkout is the only option, follow [safeguards.md](safeguards.md) — confirm with user, log invoice ID, treat redemption code as cash.
+
+## Source of truth
+
+- <https://www.bitrefill.com>
+- <https://help.bitrefill.com>
+- <https://docs.bitrefill.com/docs/Products>