From a38546164d1de3dad88e82f6fee9ac49de6b56a2 Mon Sep 17 00:00:00 2001 From: Konrad Kleczkowski Date: Tue, 30 Jun 2026 12:16:23 +0200 Subject: [PATCH 1/3] Stop vendoring the bitrefill skill; install from upstream The bitrefill skill ships as an upstream plugin (bitrefill/agents) that registers both the skill and its eCommerce MCP. Vendoring a copy under skills/bitrefill/ drifts from upstream and isn't a supported install path. Remove the vendored skill and point qupick's docs at the plugin install (/plugin install bitrefill@bitrefill-skills). qupick already requires the Bitrefill MCP tools, which the plugin provides. --- AGENTS.md | 50 +--- README.md | 41 ++- skills/bitrefill/SKILL.md | 66 ----- skills/bitrefill/references/api.md | 99 -------- skills/bitrefill/references/browse.md | 71 ------ .../bitrefill/references/capability-matrix.md | 115 --------- .../bitrefill/references/cli-headless-auth.md | 133 ---------- skills/bitrefill/references/cli.md | 237 ------------------ skills/bitrefill/references/host-openclaw.md | 167 ------------ skills/bitrefill/references/mcp.md | 150 ----------- skills/bitrefill/references/safeguards.md | 138 ---------- .../bitrefill/references/troubleshooting.md | 182 -------------- skills/qupick/SKILL.md | 6 +- 13 files changed, 41 insertions(+), 1414 deletions(-) delete mode 100644 skills/bitrefill/SKILL.md delete mode 100644 skills/bitrefill/references/api.md delete mode 100644 skills/bitrefill/references/browse.md delete mode 100644 skills/bitrefill/references/capability-matrix.md delete mode 100644 skills/bitrefill/references/cli-headless-auth.md delete mode 100644 skills/bitrefill/references/cli.md delete mode 100644 skills/bitrefill/references/host-openclaw.md delete mode 100644 skills/bitrefill/references/mcp.md delete mode 100644 skills/bitrefill/references/safeguards.md delete mode 100644 skills/bitrefill/references/troubleshooting.md diff --git a/AGENTS.md b/AGENTS.md index a1f9f56..5ad951c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,49 +6,19 @@ Guidance for coding agents working in this repository. ### Bitrefill -Vendored at [`skills/bitrefill/`](skills/bitrefill/SKILL.md) (upstream: ). Read the full `SKILL.md` and follow its link-outs before acting. +The **bitrefill** skill (purchase mechanics — gift cards, mobile top-ups, eSIMs; pay with crypto, Lightning, USDC via x402, or pre-funded account balance) is an **external prerequisite**, not vendored here. Install it from upstream: -**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**. The same intent ("buy a Steam card") plays out differently across hosts — pick a path based on what the runtime can do. - -**Triggers:** 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. - -#### Pick a path (first match wins) - -1. **Inside OpenClaw?** Check for `~/.openclaw/openclaw.json`, `~/.openclaw/skills/`, or `openclaw` on PATH. Default purchase path: guest CLI via `exec` (no auth). Sign in for `balance`/cashback. -2. **Browse-only intent (no purchase)?** Residential-IP browser → browse path. Datacenter egress only → `www.bitrefill.com` returns 403 Cloudflare; use MCP `search-products` / `product-details` instead. -3. **MCP supported?** Remote HTTP/SSE MCP at `https://api.bitrefill.com/mcp`. Highest-fidelity purchase channel — typed tool calls, OAuth or API key, no shell needed. -4. **Shell + `npm install` available?** CLI ≥ 0.3.0: guest checkout first (`buy-products --email` + crypto). Sign in for `balance`, cashback, order history. -5. **Outbound HTTP from agent loop?** REST API as last resort — verbose, no typed validation. -6. **None of the above?** Give the user a `bitrefill.com` link and stop. - -#### Spending safeguards (read before any purchase) - -This skill enables **real-money transactions**. Codes deliver instantly and digital goods are non-refundable. - -- **Confirm before buying.** Present product, denomination, price, and payment method. Wait for explicit user approval. Autonomous purchasing only when the user opts in for the current session. -- **Treat codes as cash.** Never paste them in group chats or public channels. Prefer in-memory storage over plain-text logs. Advise the 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. - -#### Reference files - -| File | Use when | -|------|----------| -| [browse.md](skills/bitrefill/references/browse.md) | Agent has residential-IP browser; user wants to explore | -| [mcp.md](skills/bitrefill/references/mcp.md) | MCP-capable host; preferred purchase path | -| [cli.md](skills/bitrefill/references/cli.md) | Shell + npm; guest checkout or signed-in CLI ≥ 0.3.0 | -| [cli-headless-auth.md](skills/bitrefill/references/cli-headless-auth.md) | Inbox + magic-link auth for headless agents | -| [api.md](skills/bitrefill/references/api.md) | HTTP-only runtime; Personal / Business / Affiliate REST tiers | -| [host-openclaw.md](skills/bitrefill/references/host-openclaw.md) | OpenClaw Gateway — guest CLI via `exec` preferred | -| [capability-matrix.md](skills/bitrefill/references/capability-matrix.md) | Per-client viable paths cheat sheet | -| [safeguards.md](skills/bitrefill/references/safeguards.md) | Spending policy + per-host hardening | -| [troubleshooting.md](skills/bitrefill/references/troubleshooting.md) | Common errors across all paths | +``` +/plugin marketplace add bitrefill/agents +/plugin install bitrefill@bitrefill-skills +/reload-plugins +``` -#### Source of truth +This registers the skill and its eCommerce MCP (`https://api.bitrefill.com/mcp`, OAuth or API key on first use). The installed skill routes by host capability and carries the full spending safeguards — read its own `SKILL.md` and reference link-outs before any purchase. -For exhaustive enums (countries, payment methods, full endpoint list), see . +- **Upstream:** +- **Enum/endpoint source of truth:** +- **Real money:** codes deliver instantly and are non-refundable. Confirm product, price, and payment method before buying; use a dedicated low-balance account; never expose high-balance accounts or wallet seeds. ### Qupick diff --git a/README.md b/README.md index 3b67a08..cc7748a 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,16 @@ Pay for a Bitrefill product (gift card, top-up, eSIM) with the **worst-performin portfolio — the asset with the lowest expected return μ — then retune the portfolio without it. The agent logic lives in [`SKILL.md`](skills/qupick/SKILL.md); this README is the operator's quick-start. -Purchase mechanics are delegated to the sibling [`bitrefill`](skills/bitrefill/SKILL.md) skill. +Purchase mechanics are delegated to the **bitrefill** skill, installed separately from upstream (see +[Install the skill](#install-the-skill)). ## Register & set up (hosted) The fastest path uses the **live hosted server** at `https://qupick.quip.network` — you don't run any backend yourself. Five steps from clone to first run: -1. **Install the skill.** Install `qupick` and its sibling `bitrefill` together (see - [Install the skill](#install-the-skill)). +1. **Install the skills.** Install `qupick` (this repo) and the `bitrefill` plugin (from upstream) — + see [Install the skill](#install-the-skill). 2. **Configure your defaults.** Copy the example and fill it in (see [Configure](#configure)): @@ -63,8 +64,10 @@ server, see [Development](#development). - The **qupick MCP server** — the portfolio backend, registered via `.mcp.json` and exposing `mcp__qupick__*` tools. Use the hosted server at `https://qupick.quip.network/mcp` (above) or run it locally at `http://127.0.0.1:8000/mcp` (see [Development](#development)). -- The **Bitrefill MCP** connected (`https://api.bitrefill.com/mcp`, OAuth or API key), or the - Bitrefill REST API key — used for product search, balance reads, and invoice creation. +- The **bitrefill skill + Bitrefill MCP**, installed from upstream via + `/plugin install bitrefill@bitrefill-skills` (see [Install the skill](#install-the-skill)). The MCP + (`https://api.bitrefill.com/mcp`, OAuth or API key) drives product search, balance reads, and + invoice creation; the Bitrefill REST API key is an alternative for the balance probe. - A funding source the waterfall can draw on: a pre-funded **Bitrefill account balance** (USD, EUR, and/or the worst-performing asset) and/or a funded on-chain wallet for that asset. The funding order is configurable (see [Configure](#configure)). @@ -74,14 +77,25 @@ server, see [Development](#development). ## Install the skill -Claude Code discovers skills under `.claude/skills/`. Because `qupick` links the bitrefill -skill via the relative path `../bitrefill/SKILL.md`, install **both** as siblings: +This repo ships the **qupick** skill. Its purchase layer — the **bitrefill** skill — is **not** +vendored here; install it from upstream. -```bash -mkdir -p .claude/skills -cp -R skills/qupick .claude/skills/ -cp -R skills/bitrefill .claude/skills/ -``` +1. **bitrefill (upstream plugin).** Registers the skill and its eCommerce MCP in one step: + + ``` + /plugin marketplace add bitrefill/agents + /plugin install bitrefill@bitrefill-skills + /reload-plugins + ``` + + Upstream: . Authenticate via OAuth or API key on first use. + +2. **qupick (this repo).** Claude Code discovers skills under `.claude/skills/`: + + ```bash + mkdir -p .claude/skills + cp -R skills/qupick .claude/skills/ + ``` `.claude/` is gitignored — the skill install is local, not committed. The one tracked exception is `backend/.claude/settings.json`, the shared permission allowlist (see @@ -230,7 +244,8 @@ Retune: drop BTC, re-optimize over the remaining 10 currencies - The agent **never buys without explicit approval** — it always pauses at step 6. - Codes deliver instantly and are **non-refundable**; treat redemption codes as cash and redeem ASAP. -- Use a dedicated, low-balance wallet. Full policy: [`safeguards.md`](skills/bitrefill/references/safeguards.md). +- Use a dedicated, low-balance wallet. Full policy: the bitrefill skill's `safeguards.md` (installed + with the plugin). - The step-7 retune is irreversible — the spent asset leaves the basket until you re-add it. ## Development diff --git a/skills/bitrefill/SKILL.md b/skills/bitrefill/SKILL.md deleted file mode 100644 index b6d8e2a..0000000 --- a/skills/bitrefill/SKILL.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -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 . diff --git a/skills/bitrefill/references/api.md b/skills/bitrefill/references/api.md deleted file mode 100644 index 006acfb..0000000 --- a/skills/bitrefill/references/api.md +++ /dev/null @@ -1,99 +0,0 @@ -# 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: . - -```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: . - -```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: . 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: . - -## 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: . - -## Source of truth - -- — tier comparison + auth -- — 6-step purchase flow -- — full endpoint catalog -- — error codes -- — webhook payload spec diff --git a/skills/bitrefill/references/browse.md b/skills/bitrefill/references/browse.md deleted file mode 100644 index 94ba392..0000000 --- a/skills/bitrefill/references/browse.md +++ /dev/null @@ -1,71 +0,0 @@ -# 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: . - -## 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 - -- -- -- diff --git a/skills/bitrefill/references/capability-matrix.md b/skills/bitrefill/references/capability-matrix.md deleted file mode 100644 index 13d1268..0000000 --- a/skills/bitrefill/references/capability-matrix.md +++ /dev/null @@ -1,115 +0,0 @@ -# Capability Matrix - -Per-host cheat sheet. Each entry = viable paths in priority order + one-line reason. Pick the first that fits, fall back as needed. - -Legend: - -- **MCP** → [mcp.md](mcp.md) -- **CLI** → [cli.md](cli.md) (≥ 0.3.0: `login`/`verify`, not API key) -- **API** → [api.md](api.md) -- **Browse** → [browse.md](browse.md) (residential IP required) -- **OpenClaw** → [host-openclaw.md](host-openclaw.md) - -## Anthropic - -### Claude.ai web — Free - -- No MCP custom URLs (Pro+ only). No shell. No residential browser. -- **Path**: none viable for purchases. For browse: only if user installs Claude-for-Chrome extension → Browse. -- **Fallback**: send user `bitrefill.com` link. - -### Claude.ai web — Pro / Max / Team / Enterprise / Cowork - -- MCP custom URLs allowed. Cowork adds desktop shell. -- **Paths**: MCP first → Browse via Claude-for-Chrome ext. -- Cowork only: + CLI via desktop shell. - -### Claude Desktop - -- MCP first-class (stdio + remote). No native shell, no native FS, no native HTTP — wire via MCP servers. -- **Paths**: MCP first → CLI via stdio MCP wrapping `npx @bitrefill/cli` → Browse via Chrome ext or Computer Use. - -### Claude Code (CLI) - -- Most flexible. Full host shell, MCP, WebFetch, Chrome ext. -- **Paths**: MCP first → CLI second → API via WebFetch / curl → Browse via Chrome ext or browser-use skill. -- Tighten: sandbox allowlist `api.bitrefill.com`, `registry.npmjs.org`. Deny `~/.ssh`, `.env`. - -## OpenAI - -### ChatGPT web — Free - -- No custom MCP, no shell, datacenter browser → Cloudflare 403. -- **Path**: none. Send user `bitrefill.com` link. - -### ChatGPT web — Plus / Pro / Business / Enterprise / Edu - -- Custom MCP via Apps & Connectors (Developer Mode for write tools). Code Interpreter has no network. -- **Path**: MCP only. Browser is OpenAI datacenter — **do NOT route to Browse** (Cloudflare). - -### ChatGPT Desktop - -- Same as ChatGPT web. "Work with Apps" can read IDE/terminal panes but not execute. -- **Path**: MCP only. - -### ChatGPT Atlas - -- Built-in Chromium with **residential IP** (user's network). Inherits account connectors. No shell. -- **Paths**: Browse first (its superpower) → MCP via account connectors. - -### ChatGPT Agent (formerly Operator) - -- Sandboxed Linux + code interpreter. Hosted browser uses **OpenAI datacenter IP**. -- **Paths**: MCP via account connectors → CLI inside sandbox shell → API via curl. **Do NOT route to Browse** (Cloudflare). - -### OpenAI Codex CLI - -- Full host shell (Seatbelt/Landlock sandboxable). MCP stdio + HTTP. Profiles in `config.toml`. -- **Paths**: MCP first → CLI second → API via curl. Browser via MCP only. -- Tighten: `--sandbox workspace-write --ask-for-approval on-request`. API key in profile, not committed config. - -## Google - -### Gemini consumer — Free - -- No MCP. No shell. No residential browser. -- **Path**: none. Send user `bitrefill.com` link. - -### Gemini consumer — AI Pro / Ultra (US) - -- "Auto Browse" runs from Google IPs → likely Cloudflare-blocked on bitrefill.com. -- **Path**: try Auto Browse + bitrefill.com URL; if blocked, send user the link. - -### Gemini CLI - -- Full host shell (sandboxable: Seatbelt / Docker / gVisor). MCP stdio + SSE + streamable-http. -- **Paths**: MCP first → CLI second → API via `web_fetch` or curl. Browser via MCP (Chrome DevTools / Playwright). - -### Jules (async coding agent) - -- Ephemeral Ubuntu VM, Google IPs, no MCP exposed to user, no residential browser. -- **Paths**: CLI inside VM → API via curl. **Not interactive** — best for batch tasks. No purchases recommended. - -## Other - -### Cursor IDE - -- Built-in browser tool, terminal tool, MCP (40-tool cap across servers). Cloud Agents in isolated VM. -- **Paths**: MCP first → CLI in terminal → API via shell or built-in browser → Browse via built-in browser. -- Tighten: keep `buy-products` out of `autoApprove` in `.cursor/mcp.json`. - -### OpenCode (sst/opencode) - -- Full host shell. MCP stdio + HTTP. Permission model per agent (`allow`/`ask`/`deny`). -- **Paths**: MCP first → CLI second → API via `webfetch` or shell. Browser via MCP. - -### OpenClaw — superset host - -- Agentskills.io loader. MCP via `openclaw mcp set`. Full host shell + FS. `browser` tool uses host IP. Mobile nodes (camera, canvas, voice). Cron. Multi-channel chat (Telegram, WhatsApp, Slack, Discord, iMessage, Signal, Matrix, Teams, etc.). -- **Paths**: read [host-openclaw.md](host-openclaw.md) **first**. **Guest CLI via `exec`** (preferred) → signed-in CLI (`balance`, cashback) → MCP → API → Browse. -- Default agent: **Pi** (Anthropic / OpenAI / Google compatible via API key). -- Unique scenarios: chat-channel purchase from phone, cron auto-renew top-ups, mobile camera OCR of receipts, multi-channel handoff. - -## Quick decision - -If user says "what host am I in?": run `command -v openclaw` and check `~/.openclaw/`. OpenClaw → guest CLI first. Else: MCP first (most hosts), fall back to CLI, then API. diff --git a/skills/bitrefill/references/cli-headless-auth.md b/skills/bitrefill/references/cli-headless-auth.md deleted file mode 100644 index 58b7876..0000000 --- a/skills/bitrefill/references/cli-headless-auth.md +++ /dev/null @@ -1,133 +0,0 @@ -# Headless CLI auth (agents) - -Use when: agent must **sign up / sign in** without human at keyboard — unlock `balance`, cashback, order history. - -**Guest checkout needs no inbox** — pass `--email` on `buy-products` and pay crypto. Fastest first try; see [cli.md](cli.md) § Guest checkout. - -Use this doc when graduating guest → signed-in account with AgentMail or equivalent inbox. - -Requires `@bitrefill/cli` ≥ 0.3.0. Agent-owned inbox via **AgentMail or equivalent** — any provider with programmatic receive (list messages, parse body). - -## Why AgentMail or equivalent - -Bitrefill `login` sends magic-link code to email. Agent needs inbox API or MCP to poll/read messages without human. [AgentMail](https://www.agentmail.to/) is the reference implementation below; equivalent = Gmail API, IMAP, Mailgun inbound, etc. if your runtime already has access. - -## One-time inbox setup (AgentMail example) - -Human verifies provider account once. Agent handles Bitrefill after. Substitute your equivalent provider's sign-up + list/receive commands. - -```bash -npm install -g agentmail-cli - -agentmail agent sign-up \ - --human-email you@example.com \ - --username bitrefill-agent -# → api_key, inbox_id (e.g. bitrefill-agent@agentmail.to) - -export AGENTMAIL_API_KEY="am_..." # from sign-up response - -agentmail agent verify --otp-code 123456 # human reads OTP from you@example.com -``` - -Official refs: [quickstart](https://docs.agentmail.to/quickstart.md), [agent onboarding](https://docs.agentmail.to/agent-onboarding.md). - -Optional (AgentMail): [AgentMail MCP](https://docs.agentmail.to/agent-onboarding.md) (`npx -y agentmail-mcp`) with `AGENTMAIL_API_KEY` — tools `list_threads`, `get_thread`, `get_message`. Equivalent providers: use their MCP/API instead. - -## Bitrefill auth flow - -Use agent inbox address as Bitrefill email (`inbox_id` from AgentMail or equivalent). Signup = login (same command). - -```bash -npm install -g @bitrefill/cli - -bitrefill init --openclaw # optional - -bitrefill login --email bitrefill-agent@agentmail.to -``` - -Poll inbox for Bitrefill verification email. AgentMail ([official list command](https://docs.agentmail.to/messages)): - -```bash -agentmail inboxes:messages list --inbox-id bitrefill-agent@agentmail.to -``` - -Parse `extracted_text` or `text` from latest message for numeric code. Then: - -```bash -bitrefill verify --code 123456 -``` - -If Bitrefill account has TOTP, add `--otp` ([1Password](#totp-via-1password) below). - -Confirm: - -```bash -bitrefill whoami --json -# → { "identity": "registered", "email": "bitrefill-agent@agentmail.to", ... } -``` - -Then run catalog/purchase commands per [cli.md](cli.md). - -## End-to-end script sketch - -```bash -INBOX="bitrefill-agent@agentmail.to" - -bitrefill login --email "$INBOX" -sleep 5 # allow delivery - -CODE=$(agentmail inboxes:messages list --inbox-id "$INBOX" \ - | jq -r '.messages[0].extracted_text // .messages[0].text' \ - | grep -oE '[0-9]{6,8}' | head -1) - -bitrefill verify --code "$CODE" -bitrefill whoami --json -``` - -Adjust regex/poll loop for your environment. Codes expire (~12–20 min server-side); on expiry re-run `login`. - -## TOTP via 1Password - -When Bitrefill account has authenticator enrolled, pass TOTP on verify. - -Secret reference ([official `op read`](https://www.1password.dev/cli/reference/commands/read)): - -```bash -bitrefill verify --code "$CODE" \ - --otp "$(op read 'op://Vault/Bitrefill/one-time password?attribute=otp')" -``` - -Item flag ([official `op item get --otp`](https://developer.1password.com/llms-cli.txt)): - -```bash -bitrefill verify --code "$CODE" --otp "$(op item get Bitrefill --otp)" -``` - -Requires 1Password desktop app integration or service account. See [Get started with 1Password CLI](https://www.1password.dev/cli/get-started). - -## Safeguards - -- Dedicated low-balance Bitrefill account tied to agent inbox — not human primary email. -- Agent inbox (AgentMail or equivalent) = auth surface; restrict who can read it. -- `bitrefill reset` + re-login to rotate after compromise. -- Never log magic-link codes or redemption codes to shared transcripts. - -Spending policy → [safeguards.md](safeguards.md). - -## Troubleshooting - -| Symptom | Fix | -|---------|-----| -| `Access token is required for login/verify` | Run any CLI command first (MCP connect mints token), or `bitrefill reset` then retry | -| `No pending login` | Re-run `login --email` before `verify` | -| Code invalid / expired | Re-run `login --email`; poll inbox again | -| `browser_url` in login response | Passkey/WebAuthn — human opens URL, then retry | -| Inbox empty after login | Wait + re-list; check spam; confirm inbox address matches provider setup | - -More CLI errors → [troubleshooting.md](troubleshooting.md). - -## Source of truth - -- AgentMail (reference): , -- Bitrefill CLI: (≥ 0.3.0) -- 1Password CLI: diff --git a/skills/bitrefill/references/cli.md b/skills/bitrefill/references/cli.md deleted file mode 100644 index c3ac7e9..0000000 --- a/skills/bitrefill/references/cli.md +++ /dev/null @@ -1,237 +0,0 @@ -# Path: CLI - -Use when: shell + `npm install` available, **host has no MCP client** (CLI talks to Bitrefill MCP under the hood). Runtimes: Claude Code, Codex CLI, Cursor terminal, Gemini CLI, OpenCode, OpenClaw, Jules (ephemeral VM), ChatGPT Agent (sandbox). - -Requires **`@bitrefill/cli` ≥ 0.3.0**. Sandboxed shells must allowlist `registry.npmjs.org` and `api.bitrefill.com`. - -## Install - -```bash -npm install -g @bitrefill/cli -``` - -From source: `git clone https://github.com/bitrefill/cli.git && cd cli && pnpm install && pnpm build && npm link`. - -## Guest checkout (fastest first try) - -**No `login` / `verify`.** Works while `whoami` shows `identity: unregistered`. Fastest path for autonomous agents to try Bitrefill — search, quote, create invoice, pay crypto or open payment link. - -```bash -bitrefill search-products --query "Amazon" --country IT -bitrefill get-product-details --product_id "amazon_it-italy" - -bitrefill buy-products \ - --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \ - --payment_method lightning \ - --return_payment_link true \ - --email "agent@example.com" -``` - -Response: `invoice_id`, `payment_link`, optional `x402_payment_url` / Lightning invoice. Poll `get-invoice-by-id --invoice_id `. Receipt goes to `--email`. Invoice expires in ~30 minutes. - -Guest payment methods: crypto (`lightning`, `usdc_base`, `bitcoin`, …) or `--return_payment_link true` (human/browser checkout, x402). **`balance` and `cashback` require a signed-in account** (below). - -## Sign up / sign in (balance, cashback, order history) - -After guest try, sign in when human wants **managed agent spending** or **rewards**: - -| Signed-in benefit | Why | -|-------------------|-----| -| **`--payment_method balance`** | Instant pay from store credit human pre-funds — natural spending cap, no on-chain wait | -| **`--payment_method cashback`** | Pay from accumulated rewards balance (BTC) | -| **Cashback on purchases** | Eligible products earn rewards back to account | -| **`list-orders` / `list-invoices`** | Full order history + redemption codes in one place | - -Same `login` for new + existing accounts. Headless inbox → [cli-headless-auth.md](cli-headless-auth.md). - -```bash -bitrefill login --email you@example.com -bitrefill verify --code GGWK87DR # email magic-link code -bitrefill verify --code GGWK87DR --otp 122407 # + TOTP when account has 2FA -bitrefill whoami --json - -# signed-in buy — instant from balance -bitrefill buy-products \ - --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \ - --payment_method balance \ - --email "you@example.com" -``` - -**Verify gotchas** (from real agent sessions): - -- Email code → `verify --code `, **not** `login --code` (unknown option). -- `--otp` = **authenticator TOTP only** when account has 2FA — not the email code. Need both `--code` and `--otp` when enrolled. -- After sign-in, `login` disappears from `--help`; run `logout` first to switch accounts or sign up another email. - -## Bootstrap (optional) - -```bash -bitrefill init # optional OpenClaw wiring only -``` - -`init` no longer stores API keys. OpenClaw only: merges MCP config + generates `~/.openclaw/skills/bitrefill/SKILL.md`. - -## Auth - -CLI 0.3.0: **guest checkout needs no sign-in.** Account auth = OAuth client_credentials (automatic on first MCP connect) + email magic-link. No `--api-key`, no `credentials.json`. - -| Step | Command | Notes | -|------|---------|-------| -| Register client | any command (or `login`) | MCP connect mints `access_token`; stored in `~/.config/bitrefill-cli/.v1.json` | -| Sign up or sign in | `login --email ` | same command for new + existing accounts | -| Complete auth | `verify --code [--otp ]` | code from email; `--otp` when account has TOTP | -| Check session | `whoami [--json]` | `identity: registered` + `email` when signed in | -| Sign out | `logout` | revokes session; keeps `client_id` | -| Full reset | `reset` | clears all local state + revokes session | - -**TOTP via 1Password** ([official `op read`](https://www.1password.dev/cli/reference/commands/read)): - -```bash -bitrefill verify --code "$CODE" --otp "$(op read 'op://Vault/Bitrefill/one-time password?attribute=otp')" -``` - -Shorthand ([official `op item get --otp`](https://developer.1password.com/llms-cli.txt)): - -```bash -bitrefill verify --code "$CODE" --otp "$(op item get Bitrefill --otp)" -``` - -Server may return `browser_url` for passkey/WebAuthn — open in browser, then retry. - -**Developer API keys** (Personal REST / key-in-path MCP) are separate from CLI auth. See [mcp.md](mcp.md) and [api.md](api.md). - -## Global flags - -Place **before** the subcommand: - -- **`--json`** — stdout is a single JSON value per run (TOON decoded to JSON); status/errors on **stderr**. Use with `jq`. - -```bash -bitrefill --json search-products --query "Amazon" --per_page 1 | jq '.products[0].name' -``` - -## Agent discovery - -`manifest` emits JSON schema for every built-in + MCP command: - -```bash -bitrefill manifest --json | jq '.commands[].name' -bitrefill manifest -o bitrefill-manifest.json -``` - -`llm-context` embeds the same manifest in a fenced JSON block. - -## `llm-context` - -Regenerates Markdown from live MCP `tools/list` (params, JSON Schema, example invocations). Use for **CLAUDE.md**, Cursor rules, or **`.github/copilot-instructions.md`**. Connection line shows redacted MCP URL — safe to commit. - -```bash -bitrefill llm-context -o BITREFILL-MCP.md -``` - -## OpenClaw quick-bootstrap - -Optional `bitrefill init --openclaw`: merges MCP stub into `~/.openclaw/openclaw.json` + emits skill SKILL.md. **Not required for guest CLI** — install CLI and run guest checkout directly via `exec`. OpenClaw prefers guest CLI first; see [host-openclaw.md](host-openclaw.md). Hardening → exec-approvals for `bitrefill buy-products`. - -## Workflow - -Subcommands discovered from remote MCP (`bitrefill --help` after connect). Core flow: - -``` -search-products → get-product-details → buy-products → get-invoice-by-id -``` - -### 1. Search - -```bash -bitrefill search-products --query "Netflix" --country US -bitrefill --json search-products --query "Netflix" --country US --per_page 5 | jq '.products' -bitrefill search-products --query "eSIM" --product_type esim --country IT -bitrefill search-products --query "*" --category games --country US -``` - -`--country` = uppercase Alpha-2. `--product_type` = `giftcard` or `esim` (singular). Discover categories: `--query "*"` returns a `categories` array with slugs. - -### 2. Details - -```bash -bitrefill get-product-details --product_id "steam-usa" --currency USDC -``` - -Returns `packages` array. Each entry has `package_value` — that's the `package_id` for `buy-products`. Ignore the `<&>` compound key. - -Three denomination types: - -- **Numeric**: `5`, `50`, `200` (pass as number). -- **Duration**: `"1 Month"`, `"12 Months"` (exact, case-sensitive). -- **Named**: `"1GB, 7 Days"`, `"PUBG New State 300 NC"` (exact, case-sensitive). - -Only values from `get-product-details` accepted. Arbitrary amounts rejected. - -### 3. Buy - -`--cart_items` = JSON **array**, even single item. Max 15 items. **`--email`** = receipt address (required for guest; optional when signed in). - -```bash -# Guest — crypto + payment link (no login) -bitrefill buy-products \ - --cart_items '[{"product_id":"amazon_it-italy","package_id":"10"}]' \ - --payment_method lightning \ - --return_payment_link true \ - --email "agent@example.com" - -# Signed-in — instant from store credit -bitrefill buy-products \ - --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \ - --payment_method balance \ - --email "you@example.com" - -# Signed-in — crypto via x402 -bitrefill buy-products \ - --cart_items '[{"product_id": "steam-usa", "package_id": 5}]' \ - --payment_method usdc_base - -# Duration package -bitrefill buy-products \ - --cart_items '[{"product_id": "spotify-usa", "package_id": "1 Month"}]' \ - --payment_method balance - -# Named eSIM -bitrefill buy-products \ - --cart_items '[{"product_id": "bitrefill-esim-europe", "package_id": "1GB, 7 Days"}]' \ - --payment_method usdc_base -``` - -Response: `invoice_id`, `payment_link`, `x402_payment_url`, `payment_info` (`address`, `paymentUri`, `altcoinPrice`). - -### 4. Track / Redeem - -```bash -bitrefill get-invoice-by-id --invoice_id "UUID" # works guest (save invoice_id from buy response) -bitrefill list-orders --include_redemption_info true # signed-in only -bitrefill get-order-by-id --order_id "ID" # signed-in only -``` - -Invoices expire after 180 minutes. Expired = create new one. - -## Critical gotchas - -- `--cart_items` must be **array** `[...]`, not object `{...}`. Shell quoting matters: single quotes outside, double inside. -- Use `package_value` after `<&>`, not the compound key. WRONG `"steam-usa<&>5"`. RIGHT `5`. -- Named/duration `package_id` exact and case-sensitive. WRONG `"1GB"`. RIGHT `"1GB, 7 Days"`. -- Country code uppercase Alpha-2. WRONG `us`, `USA`, `"United States"`. RIGHT `US`. -- `login` / `verify` only when not signed in. After verify, `logout` before switching accounts. -- Guest: `--payment_method balance` / `cashback` fail — use crypto or sign in first. -- Signed-in + 2FA: `verify` needs **both** `--code` (email) and `--otp` (authenticator). - -## Recommended payment methods (for agents) - -**Guest (try first):** `lightning` or `usdc_base` + `x402_payment_url` → `--return_payment_link true` for human/browser pay. - -**Signed-in (production):** `balance` (instant, human caps spend via store credit) → `cashback` (rewards balance) → `usdc_base` x402 → `lightning`. Full list: `bitrefill buy-products --help`. - -## Source of truth - -- — full command reference, options, flags -- — payment methods -- `bitrefill manifest --json` / `bitrefill llm-context` — live tool list + schemas diff --git a/skills/bitrefill/references/host-openclaw.md b/skills/bitrefill/references/host-openclaw.md deleted file mode 100644 index 911e0d3..0000000 --- a/skills/bitrefill/references/host-openclaw.md +++ /dev/null @@ -1,167 +0,0 @@ -# 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/` → `/.agents/skills/` → `/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: . - -## 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 [--otp ] -``` - -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: . - -## 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: . - -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: . - -### 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: . - -### 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..allowFrom: [""]` + `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: . -- **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:` for redemption codes**: enforce text-only delivery for the redemption tool output. - -## Source of truth - -- OpenClaw docs: -- Skills loader: -- Creating skills: -- MCP CLI: -- Exec tool: -- Sandboxing: -- Exec approvals: -- Nodes: -- Channels: -- Bitrefill skill paths: [mcp.md](mcp.md), [cli.md](cli.md), [api.md](api.md), [browse.md](browse.md), [safeguards.md](safeguards.md) diff --git a/skills/bitrefill/references/mcp.md b/skills/bitrefill/references/mcp.md deleted file mode 100644 index 4dd4de6..0000000 --- a/skills/bitrefill/references/mcp.md +++ /dev/null @@ -1,150 +0,0 @@ -# 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 . - -### 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 - -- -- -- -- Per-client setup: , `/use-with-claude-chat`, `/use-with-claude-code`, `/use-with-chatgpt` diff --git a/skills/bitrefill/references/safeguards.md b/skills/bitrefill/references/safeguards.md deleted file mode 100644 index 0821369..0000000 --- a/skills/bitrefill/references/safeguards.md +++ /dev/null @@ -1,138 +0,0 @@ -# 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: . - -## 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..allowFrom: [""]` + `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:` 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: -- Refund policy: -- 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) diff --git a/skills/bitrefill/references/troubleshooting.md b/skills/bitrefill/references/troubleshooting.md deleted file mode 100644 index 6c1e320..0000000 --- a/skills/bitrefill/references/troubleshooting.md +++ /dev/null @@ -1,182 +0,0 @@ -# Troubleshooting - -Common errors across all paths. Full enum: and . - -## 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 '--' 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/.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 ` (codes expire 1 hr). - -## Source of truth - -- Bitrefill error codes: -- Bitrefill error handling: -- Rate limits: -- OpenClaw troubleshooting: + per-tool pages diff --git a/skills/qupick/SKILL.md b/skills/qupick/SKILL.md index c0ce436..d7b30f2 100644 --- a/skills/qupick/SKILL.md +++ b/skills/qupick/SKILL.md @@ -1,7 +1,7 @@ --- name: qupick description: "This skill uses quantum computers to pick the best crypto asset to pay with, given current market conditions." -compatibility: "Requires: (1) the qupick MCP server (the portfolio backend's /mcp transport) wired into .mcp.json as an HTTP MCP — local dev http://127.0.0.1:8000/mcp or a deployed instance such as https://qupick.quip.network/mcp — exposing mcp__qupick__* tools; (2) Bitrefill MCP (https://api.bitrefill.com/mcp) or CLI available; (3) a local skills/qupick/config.json (see config.example.json). Delegates all purchase mechanics to the bitrefill skill." +compatibility: "Requires: (1) the qupick MCP server (the portfolio backend's /mcp transport) wired into .mcp.json as an HTTP MCP — local dev http://127.0.0.1:8000/mcp or a deployed instance such as https://qupick.quip.network/mcp — exposing mcp__qupick__* tools; (2) the bitrefill skill + its Bitrefill MCP (https://api.bitrefill.com/mcp), installed separately via /plugin install bitrefill@bitrefill-skills; (3) a local skills/qupick/config.json (see config.example.json). Delegates all purchase mechanics to the bitrefill skill." metadata: author: hackathon version: "5.3.0" @@ -11,7 +11,7 @@ metadata: Identify the most suitable crypto in the portfolio (lowest annualised expected return) using a quantum unconstrained binary optimization, settle a Bitrefill product against the cheapest available funding source, then retune the portfolio only if the chosen crypto was actually sold. -Delegates all purchase mechanics to the [`bitrefill`](../bitrefill/SKILL.md) skill — read and invoke that skill for product search, pricing, buying, and payment polling. This skill adds portfolio seeding, selection logic, and an account-aware funding waterfall on top. +Delegates all purchase mechanics to the **bitrefill** skill — install it separately (`/plugin marketplace add bitrefill/agents` → `/plugin install bitrefill@bitrefill-skills` → `/reload-plugins`; upstream ), then read and invoke it for product search, pricing, buying, and payment polling. This skill adds portfolio seeding, selection logic, and an account-aware funding waterfall on top. The flow is designed to stop for the user in **exactly one** place — the purchase approval (step 6). Defaults, a config file, and a permission allowlist remove the other interruptions. @@ -454,7 +454,7 @@ mcp__qupick__optimize({ ## Safeguards -This skill executes real-money purchases. See [`skills/bitrefill/references/safeguards.md`](../bitrefill/references/safeguards.md) for the full spending policy: +This skill executes real-money purchases. The bitrefill skill carries the full spending policy; the essentials: - Confirm before every purchase — step 6 is the single, non-negotiable approval stop. `buy-products` is deliberately **not** on the Claude Code allowlist, so the harness also prompts. - Stop before `buy-products` unless the user opts into a real purchase (real money). - Treat codes as cash — never log or paste redemption codes in public channels. From e6c175ac90535d7c9f0466898b9ddb13b4a333d8 Mon Sep 17 00:00:00 2001 From: Konrad Kleczkowski Date: Tue, 30 Jun 2026 12:24:11 +0200 Subject: [PATCH 2/3] docs: frame Bitrefill MCP as qupick's dependency, plugin optional qupick calls the mcp__bitrefill__* tools directly; it never uses the bitrefill skill's own mechanics. Lead the docs with connecting the Bitrefill MCP (claude mcp add) and present the upstream plugin as an optional superset that also bundles the skill. --- AGENTS.md | 13 +++++-------- README.md | 34 ++++++++++++++++++---------------- skills/qupick/SKILL.md | 12 ++++++------ 3 files changed, 29 insertions(+), 30 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5ad951c..8d0ac95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,23 +6,20 @@ Guidance for coding agents working in this repository. ### Bitrefill -The **bitrefill** skill (purchase mechanics — gift cards, mobile top-ups, eSIMs; pay with crypto, Lightning, USDC via x402, or pre-funded account balance) is an **external prerequisite**, not vendored here. Install it from upstream: +qupick's purchase layer is the **Bitrefill MCP** (`https://api.bitrefill.com/mcp`) — the `mcp__bitrefill__*` tools (`search-products`, `product-details`, `buy-products`, `get-invoice-by-id`). That MCP is the only hard dependency, and nothing from Bitrefill is vendored here. Connect it separately: -``` -/plugin marketplace add bitrefill/agents -/plugin install bitrefill@bitrefill-skills -/reload-plugins +```bash +claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp --scope user ``` -This registers the skill and its eCommerce MCP (`https://api.bitrefill.com/mcp`, OAuth or API key on first use). The installed skill routes by host capability and carries the full spending safeguards — read its own `SKILL.md` and reference link-outs before any purchase. +Optionally, the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *skill* (capability routing, CLI/browse/REST fallbacks, safeguards prose) — `/plugin install bitrefill@bitrefill-skills` (). qupick uses only the MCP tools, not the skill's mechanics. -- **Upstream:** - **Enum/endpoint source of truth:** - **Real money:** codes deliver instantly and are non-refundable. Confirm product, price, and payment method before buying; use a dedicated low-balance account; never expose high-balance accounts or wallet seeds. ### Qupick -Vendored at [`skills/qupick/SKILL.md`](skills/qupick/SKILL.md). Delegates purchase mechanics to the bitrefill skill above and adds portfolio selection on top. +Vendored at [`skills/qupick/SKILL.md`](skills/qupick/SKILL.md). Delegates purchase mechanics to the Bitrefill MCP above and adds portfolio selection on top. **Triggers:** "pay with my worst performer", "use my worst crypto to buy X". diff --git a/README.md b/README.md index cc7748a..a28d46c 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ Pay for a Bitrefill product (gift card, top-up, eSIM) with the **worst-performin portfolio — the asset with the lowest expected return μ — then retune the portfolio without it. The agent logic lives in [`SKILL.md`](skills/qupick/SKILL.md); this README is the operator's quick-start. -Purchase mechanics are delegated to the **bitrefill** skill, installed separately from upstream (see -[Install the skill](#install-the-skill)). +Purchase mechanics run on the **Bitrefill MCP** (the `mcp__bitrefill__*` tools), connected separately +(see [Install the skill](#install-the-skill)). ## Register & set up (hosted) @@ -64,10 +64,10 @@ server, see [Development](#development). - The **qupick MCP server** — the portfolio backend, registered via `.mcp.json` and exposing `mcp__qupick__*` tools. Use the hosted server at `https://qupick.quip.network/mcp` (above) or run it locally at `http://127.0.0.1:8000/mcp` (see [Development](#development)). -- The **bitrefill skill + Bitrefill MCP**, installed from upstream via - `/plugin install bitrefill@bitrefill-skills` (see [Install the skill](#install-the-skill)). The MCP - (`https://api.bitrefill.com/mcp`, OAuth or API key) drives product search, balance reads, and - invoice creation; the Bitrefill REST API key is an alternative for the balance probe. +- The **Bitrefill MCP** connected (`https://api.bitrefill.com/mcp`, OAuth or API key) — qupick's + purchase layer. The `mcp__bitrefill__*` tools drive product search, balance reads, `buy-products`, + and invoice polling. Add it with `claude mcp add` (see [Install the skill](#install-the-skill)); the + Bitrefill REST API key is an alternative for the balance probe. - A funding source the waterfall can draw on: a pre-funded **Bitrefill account balance** (USD, EUR, and/or the worst-performing asset) and/or a funded on-chain wallet for that asset. The funding order is configurable (see [Configure](#configure)). @@ -77,18 +77,20 @@ server, see [Development](#development). ## Install the skill -This repo ships the **qupick** skill. Its purchase layer — the **bitrefill** skill — is **not** -vendored here; install it from upstream. +This repo ships the **qupick** skill. Its purchase layer is the **Bitrefill MCP** — connect that +separately; the `mcp__bitrefill__*` tools are what qupick actually calls. Nothing from Bitrefill is +vendored here. -1. **bitrefill (upstream plugin).** Registers the skill and its eCommerce MCP in one step: +1. **Bitrefill MCP (required).** Connect the hosted MCP; authenticate via OAuth (`/mcp`) or API key: - ``` - /plugin marketplace add bitrefill/agents - /plugin install bitrefill@bitrefill-skills - /reload-plugins + ```bash + claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp --scope user ``` - Upstream: . Authenticate via OAuth or API key on first use. + Optional: the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *skill* + (multi-channel purchase guidance) in one step — `/plugin marketplace add bitrefill/agents` → + `/plugin install bitrefill@bitrefill-skills` → `/reload-plugins` + (). qupick needs only the MCP, not the skill. 2. **qupick (this repo).** Claude Code discovers skills under `.claude/skills/`: @@ -244,8 +246,8 @@ Retune: drop BTC, re-optimize over the remaining 10 currencies - The agent **never buys without explicit approval** — it always pauses at step 6. - Codes deliver instantly and are **non-refundable**; treat redemption codes as cash and redeem ASAP. -- Use a dedicated, low-balance wallet. Full policy: the bitrefill skill's `safeguards.md` (installed - with the plugin). +- Use a dedicated, low-balance wallet. Never expose high-balance accounts or wallet seeds. (If you + install the optional bitrefill plugin, its `safeguards.md` covers per-host hardening too.) - The step-7 retune is irreversible — the spent asset leaves the basket until you re-add it. ## Development diff --git a/skills/qupick/SKILL.md b/skills/qupick/SKILL.md index d7b30f2..5b39a5b 100644 --- a/skills/qupick/SKILL.md +++ b/skills/qupick/SKILL.md @@ -1,7 +1,7 @@ --- name: qupick description: "This skill uses quantum computers to pick the best crypto asset to pay with, given current market conditions." -compatibility: "Requires: (1) the qupick MCP server (the portfolio backend's /mcp transport) wired into .mcp.json as an HTTP MCP — local dev http://127.0.0.1:8000/mcp or a deployed instance such as https://qupick.quip.network/mcp — exposing mcp__qupick__* tools; (2) the bitrefill skill + its Bitrefill MCP (https://api.bitrefill.com/mcp), installed separately via /plugin install bitrefill@bitrefill-skills; (3) a local skills/qupick/config.json (see config.example.json). Delegates all purchase mechanics to the bitrefill skill." +compatibility: "Requires: (1) the qupick MCP server (the portfolio backend's /mcp transport) wired into .mcp.json as an HTTP MCP — local dev http://127.0.0.1:8000/mcp or a deployed instance such as https://qupick.quip.network/mcp — exposing mcp__qupick__* tools; (2) the Bitrefill MCP (https://api.bitrefill.com/mcp) connected — the mcp__bitrefill__* tools that drive every purchase; add it with claude mcp add or the upstream bitrefill plugin; (3) a local skills/qupick/config.json (see config.example.json). Delegates all purchase mechanics to the Bitrefill MCP." metadata: author: hackathon version: "5.3.0" @@ -11,7 +11,7 @@ metadata: Identify the most suitable crypto in the portfolio (lowest annualised expected return) using a quantum unconstrained binary optimization, settle a Bitrefill product against the cheapest available funding source, then retune the portfolio only if the chosen crypto was actually sold. -Delegates all purchase mechanics to the **bitrefill** skill — install it separately (`/plugin marketplace add bitrefill/agents` → `/plugin install bitrefill@bitrefill-skills` → `/reload-plugins`; upstream ), then read and invoke it for product search, pricing, buying, and payment polling. This skill adds portfolio seeding, selection logic, and an account-aware funding waterfall on top. +Delegates all purchase mechanics to the **Bitrefill MCP** (`mcp__bitrefill__*` tools) — connect it separately (`claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp`, or install the upstream bitrefill plugin which bundles it; ), then invoke it for product search, pricing, buying, and payment polling. This skill adds portfolio seeding, selection logic, and an account-aware funding waterfall on top. The flow is designed to stop for the user in **exactly one** place — the purchase approval (step 6). Defaults, a config file, and a permission allowlist remove the other interruptions. @@ -44,7 +44,7 @@ curl https://api.bitrefill.com/v2/accounts/balance -H "Authorization: Bearer $BI ``` That one is allowlisted (write the URL first so prefix matching works). Real purchases go through -the bitrefill skill's `buy-products`, deliberately **not** allowlisted, so the approval gate in +the Bitrefill MCP's `buy-products`, deliberately **not** allowlisted, so the approval gate in step 6 always fires. ## Backend tool reference @@ -313,7 +313,7 @@ mcp__qupick__optimize({}) ### 3. Pick the product (MCP) -Use the bitrefill skill's `search-products` (with `country = config.defaults.country`) → `product-details` to settle on: +Use the Bitrefill MCP's `search-products` (with `country = config.defaults.country`) → `product-details` to settle on: - Product name + country - Price in USD (from the `packages` array — use the field `payment_price` with `payment_currency == "USD"`) - Accepted `payment_methods` list (from `product-details` — the authoritative per-product filter) @@ -383,7 +383,7 @@ Settle: [chosen source] Approve? ``` -After explicit approval, use the bitrefill skill to buy, mapping the chosen token to `buy-products` +After explicit approval, use the Bitrefill MCP to buy, mapping the chosen token to `buy-products` arguments. Each `cart_items` entry is `{product_id, package_value}` (no `quantity` field — repeat the entry for multiples; `package_id` is deprecated). Balance payments settle instantly and have no `auto_pay` flag — pick the sub-account with `balance_currency`: @@ -454,7 +454,7 @@ mcp__qupick__optimize({ ## Safeguards -This skill executes real-money purchases. The bitrefill skill carries the full spending policy; the essentials: +This skill executes real-money purchases. The spending policy: - Confirm before every purchase — step 6 is the single, non-negotiable approval stop. `buy-products` is deliberately **not** on the Claude Code allowlist, so the harness also prompts. - Stop before `buy-products` unless the user opts into a real purchase (real money). - Treat codes as cash — never log or paste redemption codes in public channels. From 1cb5c44e0767bc62bf8b1fda8b6b451b42a6cfad Mon Sep 17 00:00:00 2001 From: Konrad Kleczkowski Date: Tue, 30 Jun 2026 12:33:49 +0200 Subject: [PATCH 3/3] docs: note the bitrefill /plugin commands run inside Claude Code --- AGENTS.md | 2 +- README.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8d0ac95..ed892de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ qupick's purchase layer is the **Bitrefill MCP** (`https://api.bitrefill.com/mcp claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp --scope user ``` -Optionally, the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *skill* (capability routing, CLI/browse/REST fallbacks, safeguards prose) — `/plugin install bitrefill@bitrefill-skills` (). qupick uses only the MCP tools, not the skill's mechanics. +Optionally, the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *skill* (capability routing, CLI/browse/REST fallbacks, safeguards prose) — `/plugin install bitrefill@bitrefill-skills`, run inside Claude Code (). qupick uses only the MCP tools, not the skill's mechanics. - **Enum/endpoint source of truth:** - **Real money:** codes deliver instantly and are non-refundable. Confirm product, price, and payment method before buying; use a dedicated low-balance account; never expose high-balance accounts or wallet seeds. diff --git a/README.md b/README.md index a28d46c..e90a01e 100644 --- a/README.md +++ b/README.md @@ -88,9 +88,9 @@ vendored here. ``` Optional: the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *skill* - (multi-channel purchase guidance) in one step — `/plugin marketplace add bitrefill/agents` → - `/plugin install bitrefill@bitrefill-skills` → `/reload-plugins` - (). qupick needs only the MCP, not the skill. + (multi-channel purchase guidance). Run these as slash-commands **inside Claude Code** (not a + shell): `/plugin marketplace add bitrefill/agents` → `/plugin install bitrefill@bitrefill-skills` + → `/reload-plugins` (). qupick needs only the MCP, not the skill. 2. **qupick (this repo).** Claude Code discovers skills under `.claude/skills/`: