diff --git a/AGENTS.md b/AGENTS.md index a1f9f56..ed892de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,53 +6,20 @@ 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. +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: -**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 | +```bash +claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp --scope user +``` -#### Source of truth +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. -For exhaustive enums (countries, payment methods, full endpoint list), see . +- **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 3b67a08..e90a01e 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 run on the **Bitrefill MCP** (the `mcp__bitrefill__*` tools), connected separately +(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 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)). @@ -74,14 +77,27 @@ 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 is the **Bitrefill MCP** — connect that +separately; the `mcp__bitrefill__*` tools are what qupick actually calls. Nothing from Bitrefill is +vendored here. -```bash -mkdir -p .claude/skills -cp -R skills/qupick .claude/skills/ -cp -R skills/bitrefill .claude/skills/ -``` +1. **Bitrefill MCP (required).** Connect the hosted MCP; authenticate via OAuth (`/mcp`) or API key: + + ```bash + claude mcp add --transport http bitrefill https://api.bitrefill.com/mcp --scope user + ``` + + Optional: the upstream **bitrefill plugin** bundles the same MCP plus the bitrefill *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/`: + + ```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 +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: [`safeguards.md`](skills/bitrefill/references/safeguards.md). +- 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/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..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) 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 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`](../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 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. See [`skills/bitrefill/references/safeguards.md`](../bitrefill/references/safeguards.md) for the full spending policy: +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.