Add Bitrefill hybrid plugin for Base MCP agent commerce

[marcopesani]

Summary

Adds Bitrefill as the eighth native plugin in the Base MCP skill — a hybrid integration that lets agents discover and purchase real-world digital goods (gift cards, mobile top-ups, eSIMs) and settle usdc_base invoices through Base Account on Base.

This extends the Base MCP agent-commerce surface beyond DeFi: an agent can search Bitrefill's catalog, create an invoice via Bitrefill MCP/CLI/REST, and pay with USDC on Base using Base MCP's x402 flow (primary) or a direct send fallback — both routed through the same approval-mode UX documented in references/approval-mode.md.

What's included

• skills/base-mcp/plugins/bitrefill.md — full hybrid plugin reference (detection, installation, auth, surface routing, orchestration, submission, risks)
• skills/base-mcp/SKILL.md — registers Bitrefill in the native plugins table
• skills/base-mcp/references/plugin-spec.md — new routing tags (gift-cards, esim, mobile-topup, payments) and conformance row

Design choices (aligned with Base MCP patterns)

Decision	Rationale
integration: hybrid	Bitrefill MCP/CLI/REST for catalog + invoices; Base MCP for onchain USDC settlement
x402 primary, send fallback	Matches how Base MCP exposes payments today; fallback documented for harnesses or x402 endpoint errors
buy-products excluded from autoApprove	Consistent with irreversible-spend guardrails across native plugins
chains: [base]	Settlement is USDC-on-Base only; other Bitrefill payment methods stay out of Base MCP scope
risk: [pii, irreversible]	Gift card codes are bearer assets; agent must confirm before purchase and handle redemption securely

Live validation

End-to-end purchase tests were run in Cursor with Base MCP + Bitrefill MCP connected, following the plugin orchestration flow. Product: Amazon.it Italy 10 EUR (amazon_it-italy, usdc_base).

Onchain proof (Base mainnet)

Path	Invoice	Result	BaseScan
x402 via initiate_x402_request → complete_x402_request	ffd6b0cd-…	Payment confirmed onchain; invoice polling unavailable via MCP on first attempt	tx
Direct USDC send fallback	4cf05e37-…	Full success — payment_detected → complete → gift card delivered (~37s)	tx
x402 (retried after wallet funded)	ddda365c-…	Full success — x402 signed, get-invoice-by-id → complete → delivered; complete_x402_request returned HTTP 500 but payment settled	tx

All three transactions settle USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) to Bitrefill payment addresses. Invoice amounts: 10.59 USDC per 10 EUR denomination.

Operational notes surfaced during testing

These are documented in the plugin so future agents don't hit the same dead ends:

1. Poll get-invoice-by-id after every payment path — even when complete_x402_request returns HTTP 500, Bitrefill may still mark the invoice complete (observed on the successful x402 retry).
2. Ensure sufficient USDC balance before x402 — underfunded wallets produced signed status without settlement; funding the Base Account resolved it.
3. send fallback is production-viable — identical invoice lifecycle (unpaid → payment_detected → complete) with reliable MCP polling.
4. Redemption is bearer PII — codes delivered only on explicit user request; update-order tracks spend via remaining_amount.

Why this fits the Base MCP ecosystem

Bitrefill is an x402-enabled merchant on Base with a first-party MCP (api.bitrefill.com/mcp). This plugin documents the handoff boundary clearly:

• Bitrefill transport — search, quote, invoice, poll, redeem
• Base MCP transport — USDC payment via x402 or send, with Base Account approval

That split keeps Base MCP focused on wallet operations while enabling agent commerce — a concrete use case for x402 on Base that complements existing DeFi plugins (Morpho, Uniswap, etc.).

Upstream references: Bitrefill agents repo, Bitrefill docs.

Test plan

• Plugin conforms to references/plugin-spec.md (frontmatter, sections, conformance table)
• Registered in SKILL.md native plugins list
• Bitrefill MCP: search-products → get-product-details → buy-products
• Base MCP x402: initiate_x402_request → user approval → complete_x402_request → get-invoice-by-id poll
• Base MCP send fallback: USDC transfer → invoice complete → redemption delivered
• Post-purchase: update-order with remaining_amount: 0
• Maintainer review: x402 HTTP 500 behavior on complete_x402_request (payment still settles — worth confirming expected)

Reviewer notes

Happy to adjust wording, tag vocabulary, or orchestration steps based on Base team feedback. The plugin intentionally defers tool parameter names to the live MCP catalogs (per existing native plugin convention) so it stays resilient as Base MCP and Bitrefill MCP evolve.

/cc — this is a contribution toward agent-native commerce on Base; appreciate any guidance on x402 edge cases or allowlist requirements for api.bitrefill.com.

Made with Cursor

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[youssefea]

Note: this is an AI-generated review. An automated, read-only API/endpoint health check — not a human review.

Thanks for the submission — the Bitrefill plugin looks healthy overall and the core paths all behave as documented. As part of reviewing the Wave 2 submissions I ran an automated, read-only health check against the documented endpoints. Just two small notes:

Findings

• REST GET /v2/ping — documented as a plain "Health check" but returns 401 {"status":"no_token"} unauthenticated (and 401 {"status":"invalid_token"} with a bad bearer). It is bearer-gated like the rest of /v2; the doc should note /ping also requires Authorization.
• Allowlist — requires.allowlist is [api.bitrefill.com] only, but the body references docs.bitrefill.com as a docs-only MCP (https://docs.bitrefill.com/mcp → 200) and as the rate-limits source (https://docs.bitrefill.com/docs/rate-limits → 200). If the agent ever fetches those via web_request, they'd be blocked. www.bitrefill.com is correctly excluded (confirmed 403 to datacenter IPs, matching the doc's warning).
• REST /v2 auth — search, products/{id}, invoices, invoices/{id}, orders/{id} all return 401 no_token unauthenticated, confirming the documented Bearer/api-key model; nothing is unexpectedly public. POST /invoices was probed only with an empty, unauthenticated body and rejected at the auth layer — no order created.
• MCP — https://api.bitrefill.com/mcp is live: OPTIONS 200, GET 400 (Accept header must include text/event-stream, valid streamable-HTTP), POST initialize 401 (gated), consistent with oauth-on-install / api-key.
• CLI — @bitrefill/cli exists, latest=0.3.0 (satisfies the documented ≥ 0.3.0), bin: bitrefill matches bitrefill --help.
• Contract — USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 has non-empty bytecode on Base and symbol() returns USDC (canonical). The Base MCP leg is an x402/send payment, not send_calls, so the smart-account signature-width concern does not apply.

What was checked

Read-only probes of: DNS (dig) and TLS for api./docs./www.bitrefill.com; HTTP status + response-shape vs doc via curl GET/HEAD/OPTIONS on /v2/ping, /v2/products/search, /v2/products/{id}, /v2/invoices (empty body), /v2/invoices/{id}, /v2/orders/{id}, and both MCP endpoints; unauthenticated and bogus-bearer probes to verify the auth model (401 no_token vs invalid_token); npm view for @bitrefill/cli existence/version/bin; GitHub repo reachability; and on-chain cast code + cast call symbol() for the USDC contract on Base (https://mainnet.base.org). This was strictly read-only: no transactions were submitted, no funds moved, and no API keys were used.

Really appreciate the contribution — happy to clarify any of the above. Since this is an automated check, please double-check anything that looks unexpected on your end before changing it.

---

Generated by an AI assistant (Claude) after an automated, read-only deep analysis of the API/endpoint health documented in this plugin. It checks endpoint reachability, HTTP status codes, response shapes, auth behavior, SDK/package existence, and on-chain contract presence — it does not submit transactions or move funds. Please independently verify any finding before acting on it.