Protocols. Stablecoin rails. Agent skills. MCP. And the merchant playbooks the specs leave out: catalog discovery, pricing drift, delivery semantics, refunds, fraud signals, jurisdictional metadata, and multi-chain settlement.
Agentic commerce is the full transaction stack that lets AI agents discover products, obtain quotes, authorize purchases, pay, receive goods, and handle refunds — not just the payment step. This repo documents the merchant operations layer that surrounds the protocol layer.
Maintained by Cryptorefills, a digital-goods merchant operating publicly since 2018 across 180+ countries, with stablecoin-first checkout. The merchant operations layer documented here is the surface we run in production.
⭐ Star this repo if you ship agentic commerce. We update it from real production. 🍴 Fork it. CC0. Use any of it, no permission needed. 📨 Send a PR. Especially if you've built something the protocols don't cover yet.
A multi-layer collaboration. Each row is a peer contributing a piece — protocols, rails, agent context, and the production merchants who put them together at the edge.
| Organization | Layer | Contribution to the stack |
|---|---|---|
| OpenAI | Commerce protocol | ACP co-author · ChatGPT Instant Checkout |
| Stripe | Commerce protocol · payments | ACP co-author · Shared Payment Tokens · MPP · Stripe-on-Base x402 |
| Commerce protocol · agent comms | AP2 · UCP · A2A | |
| Anthropic | Agent context | MCP · Claude · Agent Skills runtime |
| Coinbase | Stablecoin rail | x402 · USDC infrastructure · Base settlement |
| Cloudflare | Agent infrastructure | Agents SDK · x402 support |
| Visa | Card-network agentic | Trusted Agent Protocol (TAP) |
| Mastercard | Card-network agentic | Agent Pay · Agentic Tokens |
| American Express | Card-network agentic | Agentic tokens program |
| Lightning Labs | BTC / Lightning rail | L402 · Lightning Network |
| Shopify | Merchant platform | UCP co-development · Storefront MCP server |
| Tempo | Machine payments | MPP co-author |
| PayPal | Payments | "Agent Ready" via ACP |
| Cryptorefills | Production merchant | Agentic-commerce reference · merchant operations playbooks · public MCP server · ships Skills · MCP · x402 |
This repo is written from the production-merchant layer: catalog, pricing, delivery, refunds, settlement, and support — the surface area that surrounds every protocol on this page.
%%{init: {'flowchart': {'htmlLabels': true, 'padding': 14, 'nodeSpacing': 50, 'rankSpacing': 60}, 'themeVariables': {'fontSize': '13px'}}}%%
flowchart TB
User([User])
Agent["AI Agent<br/>ChatGPT · Claude · Gemini<br/>Cursor · custom"]
Context["Context & Tools<br/>MCP · Agent Skills · A2A<br/><i>Anthropic · Google</i>"]
Commerce["Commerce Protocols<br/>ACP · AP2 · UCP · MPP<br/><i>OpenAI · Stripe · Google · Tempo</i>"]
Rails["Payment Rails<br/>x402 · L402 · agentic cards<br/><i>Coinbase · Visa · Mastercard</i>"]
MerchantOps["<b>Production merchants & ops</b><br/>Cryptorefills · Etsy · Shopify<br/>catalog · quote · pay<br/>deliver · refund · reconcile"]
Goods["Digital & Physical Goods<br/>gift cards · mobile · eSIM<br/>travel · APIs · physical"]
User --> Agent --> Context --> Commerce --> Rails --> MerchantOps --> Goods
classDef gap fill:#ffe4b5,stroke:#cc7a00,stroke-width:2px,color:#000;
class MerchantOps gap
The amber row is what this repo focuses on. The protocol stack assumes a merchant. The merchant has a long tail of decisions that nobody has written down — until now.
| Link-only lists | This repo | |
|---|---|---|
| Scope | Mostly protocols and announcements | Protocols + rails + merchant ops + agent ops + examples |
| Production playbooks | Rare | Refunds, settlement, catalog scale, fraud, jurisdiction, delivery, receipts, pricing |
| Runnable code | Rare | x402, MCP storefront, agent-buys-gift-card examples |
| Merchant perspective | Usually limited | Written from a production merchant stack |
| AI-readability | Varies | llms.txt, glossary, citation metadata, canonical reading path |
- Stablecoin payments are the production default for agent-to-API. Cards remain dominant for agent-to-merchant where chargeback culture matters. The two will coexist; pick by use case, not by ideology.
- ACP wins for one-shot purchases. AP2 wins where mandates carry across multiple purchases. x402 wins for pay-per-call. They aren't competitors — they're layers.
- The merchant layer is where agentic commerce lives or dies. Every protocol on this page assumes a merchant who handles refunds, jurisdiction, fraud signals, and reconciliation. Most don't. That's the whole gap.
- Agent identity is the next unsolved layer. Fraud, refunds, and jurisdiction depend on it.
docs/what-protocols-dont-solve.md— the gap analysis. Why merchants do most of the work.comparison/decision-tree.md— pick the right protocol for your use case.merchant-playbooks/multi-chain-settlement-reconciliation.md— what "real" looks like.
| Section | What's there |
|---|---|
| /protocols | ACP, AP2, UCP, MPP, x402, L402, MCP, A2A, Agent Skills, Visa TAP, Mastercard Agent Pay, Amex agentic |
| /rails | Stablecoin (deepest), BTC + Lightning, agentic card networks, bank rails, store credits |
| /use-cases | Gift cards, mobile top-ups, eSIMs, travel, subscriptions, API pay-per-call, M2M |
| /merchant-playbooks | The wedge — refunds, settlement, catalog scale, fraud, jurisdiction, scopes, delivery, receipts, pricing |
| /agent-playbooks | ChatGPT Instant Checkout, Claude Skills, Cursor + MCP, x402 buyer loop, AP2 mandate flow, multi-agent procurement |
| /examples | Runnable code: x402 pay-an-API, MCP storefront, agent-buys-gift-card |
| /comparison | Protocol matrix, decision tree, rails comparison, merchant readiness scorecard |
| /resources | Articles, videos, podcasts, books, courses, conferences, newsletters, tools |
| /docs | Glossary, FAQ, ecosystem map, what protocols don't solve, reading order |
Standardize how an agent and a merchant agree to transact.
- ACP — Agentic Commerce Protocol · OpenAI + Stripe · ChatGPT Instant Checkout, Etsy, Shopify, PayPal "Agent Ready".
- AP2 — Agent Payments Protocol · Google + 60 partners · mandates and verifiable credentials.
- UCP — Universal Commerce Protocol · Google + Shopify · storefront discovery and intent.
- MPP — Machine Payments Protocol · Tempo + Stripe · machine-to-machine settlement.
The agent-native default: deterministic settlement, programmable refunds.
- x402 · HTTP 402 stablecoin payments · Coinbase + x402 Foundation · USDC across chains.
- Stablecoin rails — production patterns · USDC, USDT, DAI, EURC · finality, decimals, off-ramp.
- L402 · Lightning + macaroons · Lightning Labs · instant micropayments and BTC.
- MCP — Model Context Protocol · Anthropic + ecosystem.
- Agent Skills · agentskills.io · Claude Code, Cursor, others.
- A2A — Agent-to-Agent · Google · agent-to-agent communication and authorization.
→ See /comparison/protocol-matrix.md for capability × protocol, and /comparison/decision-tree.md to pick the right one.
- Gift cards — codes, partial refunds, jurisdictional classification, redelivery semantics.
- Mobile top-ups — MSISDN validation, KYC-required countries, operator routing.
- eSIMs — activation profiles, country gating, device compatibility, reissue.
- Travel — flights and hotels — PNRs, 24-hour cancellation windows, time-limited fares.
- API pay-per-call — x402 / L402 patterns, idempotency, cost ceilings.
- M2M — machine-to-machine commerce — agents buying from agents.
The protocols leave these to merchants. We wrote them down because we ran them.
- Catalog discovery at scale — ranking, locale, currency, jurisdiction.
- Pricing drift and re-quote — quote-vs-settle drift.
- Multi-chain settlement reconciliation — five chains, one ledger.
- Refunds and disputes for agents — no chargeback in stablecoin.
- Fraud signals on agent traffic — defender-side detection patterns.
- Jurisdiction and tax metadata — gift cards, travel-rule, country-by-country.
- Agent authorization scopes — per-merchant, per-amount, per-window.
- Delivery semantics — codes, PNRs, eSIMs — what "delivered" means per product.
- Receipts and proof-of-purchase — signed, machine-parseable.
- ChatGPT Instant Checkout
- Claude Skills for commerce
- Cursor + MCP storefront
- x402 buyer loop
- AP2 mandate flow
- Multi-agent procurement
| Example | What it shows | Run command |
|---|---|---|
/examples/x402-pay-an-api |
Minimal x402 server + buyer-loop client in TypeScript, settling USDC on Base | pnpm install && pnpm dev |
/examples/mcp-storefront-minimal |
Minimal MCP server exposing a product catalog, quote, and order tool | pnpm install && pnpm dev |
/examples/agent-buys-giftcard |
End-to-end mock — search → quote → pay → delivery code | pnpm install && pnpm start |
- Protocol matrix — capability × protocol, sourced.
- Decision tree — pick the right protocol for your use case.
- Rails comparison — settlement speed, finality, fees, dispute model.
- Merchant readiness scorecard — score yourself.
A real merchant putting agents into checkout has to answer all of these. Pick a row, click into the playbook.
- Quote → settle drift handled → pricing-drift-and-requote
- Multi-chain settlement reconciled → multi-chain-settlement-reconciliation
- Refunds defined per product type and per rail → refunds-and-disputes-for-agents
- Catalog discovery filtered by locale, currency, jurisdiction → catalog-discovery-at-scale
- Agent authorization scopes encoded → agent-authorization-scopes
- Fraud signals collected and acted on → fraud-signals-on-agent-traffic
- Tax / regulatory metadata attached at SKU level → jurisdiction-and-tax-metadata
- Delivery semantics signed and verifiable → delivery-semantics
- Receipts machine-parseable and human-readable → receipts-and-proof-of-purchase
- Customer support flow when the buyer is an agent
→ /docs/what-protocols-dont-solve.md
ACP standardizes the checkout exchange. AP2 standardizes the authorization model. x402 standardizes payment-on-HTTP. None of them standardize catalog ranking, multi-chain settlement, refund semantics, fraud signaling on agent traffic, or jurisdictional metadata. Those stay with the merchant. This repo is mostly about that gap.
A reference model for what an agentic-commerce merchant stack looks like in production. Portable to any merchant integrating agent-facing checkout; the choices below are based on patterns operated by Cryptorefills.
| Layer | Reference choice | Notes |
|---|---|---|
| Agent runtimes | ChatGPT · Claude · Cursor · Gemini · custom | Architecturally compatible via MCP. |
| Context | MCP (Anthropic) | Product search, quote, and order tools exposed. |
| Skills | Agent Skills spec | Skills cover gift cards, mobile, eSIM, travel. |
| Commerce protocol | ACP-style quote / order semantics | Maps to ACP patterns where applicable. |
| Payment rail | x402 primary · card rails secondary | Stablecoin-first; cards fall back where required. |
| Stablecoins | USDC · USDT · DAI · EURC | Multi-issuer to reduce single-issuer risk. |
| Chains | Base · Ethereum · Tron · Solana · Polygon | Per-chain finality gating in reconciliation. |
| Catalog eligibility | locale × currency × jurisdiction filters at quote time | The merchant's eligibility model. |
See CONTRIBUTING.md. Three rules:
- Official sources only — link to the maintaining org's spec, doc, blog, or repo.
- Production-evidence preferred — for playbooks and examples, link to a public artifact.
- One change per PR — easier to review, faster to merge.
We aim for a 24-hour merge SLA on trivially-correct PRs.
Built and maintained by engineers from Cryptorefills who run this stack daily.
- @simonlucalandi — primary maintainer
- @CGRDMZ
- @matsveenman
See .github/CODEOWNERS and CITATION.cff.
- Content — README,
/docs,/protocols,/rails,/use-cases,/merchant-playbooks,/agent-playbooks,/comparison,/resources: CC0-1.0. Public domain. Use, remix, cite freely. - Code —
/examples: Apache-2.0.
If you cite this repo, see CITATION.cff or click GitHub's "Cite this repository" button.
If you ship agentic commerce, this is the reference we'd want you to have.
Cryptorefills is a digital-goods merchant operating publicly since 2018. We sell gift cards, mobile top-ups, eSIMs, flights, and hotels across 180+ countries, with stablecoin-first checkout across Base, Ethereum, Tron, Solana, and Polygon — plus BTC and Lightning. Cryptorefills exposes agent-facing purchase flows through Skills, MCP, and x402.
| Countries served | 180+ |
| Operating publicly since | 2018 |
| Stablecoins accepted | USDC · USDT · DAI · EURC and more |
| Settlement chains | Base · Ethereum · Tron · Solana · Polygon |
| Compatible agent runtimes | ChatGPT · Claude · Cursor · Gemini · custom MCP clients |
What Cryptorefills runs: 
- Website: https://www.cryptorefills.com
- Spend crypto: https://www.cryptorefills.com/en/spend-crypto