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