Agentic Commerce

The reference for production agentic commerce.

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.

The agentic commerce stack

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.

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.

How the pieces fit together

%%{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 &amp; 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 &amp; ops</b><br/>Cryptorefills · Etsy · Shopify<br/>catalog · quote · pay<br/>deliver · refund · reconcile"]
    Goods["Digital &amp; 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.

Why this exists

The field in four claims

1. 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.
2. 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.
3. 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.
4. Agent identity is the next unsolved layer. Fraud, refunds, and jurisdiction depend on it.

If you only read three files

1. docs/what-protocols-dont-solve.md — the gap analysis. Why merchants do most of the work. 2. comparison/decision-tree.md — pick the right protocol for your use case. 3. merchant-playbooks/multi-chain-settlement-reconciliation.md — what "real" looks like.

Navigate

Commerce protocols

Standardize how an agent and a merchant agree to transact.

• [ACP — Agentic Commerce Protocol](./protocols/acp.md) · OpenAI + Stripe · ChatGPT Instant Checkout, Etsy, Shopify, PayPal "Agent Ready".
• [AP2 — Agent Payments Protocol](./protocols/ap2.md) · Google + 60 partners · mandates and verifiable credentials.
• [UCP — Universal Commerce Protocol](./protocols/ucp.md) · Google + Shopify · storefront discovery and intent.
• [MPP — Machine Payments Protocol](./protocols/mpp.md) · Tempo + Stripe · machine-to-machine settlement.

Stablecoin payment rails

The agent-native default: deterministic settlement, programmable refunds.

• [x402](./protocols/x402.md) · HTTP 402 stablecoin payments · Coinbase + x402 Foundation · USDC across chains.
• [Stablecoin rails — production patterns](./rails/crypto-stablecoin.md) · USDC, USDT, DAI, EURC · finality, decimals, off-ramp.
• [L402](./protocols/l402.md) · Lightning + macaroons · Lightning Labs · instant micropayments and BTC.

Agentic card networks

• [Visa Trusted Agent Protocol (TAP)](./protocols/agentic-card-networks.md#visa-trusted-agent-protocol-tap)
• [Mastercard Agent Pay](./protocols/agentic-card-networks.md)
• [American Express agentic tokens](./protocols/agentic-card-networks.md)

Agent context, skills, and identity

• [MCP — Model Context Protocol](./protocols/mcp.md) · Anthropic + ecosystem.
• [Agent Skills](./protocols/agent-skills.md) · agentskills.io · Claude Code, Cursor, others.
• [A2A — Agent-to-Agent](./protocols/a2a.md) · Google · agent-to-agent communication and authorization.

→ See [/comparison/protocol-matrix.md](./comparison/protocol-matrix.md) for capability × protocol, and [/comparison/decision-tree.md](./comparison/decision-tree.md) to pick the right one.

Use cases — real, shippable

• [Gift cards](./use-cases/gift-cards.md) — codes, partial refunds, jurisdictional classification, redelivery semantics.
• [Mobile top-ups](./use-cases/mobile-topups.md) — MSISDN validation, KYC-required countries, operator routing.
• [eSIMs](./use-cases/esims.md) — activation profiles, country gating, device compatibility, reissue.
• [Travel — flights and hotels](./use-cases/travel-flights-hotels.md) — PNRs, 24-hour cancellation windows, time-limited fares.
• [API pay-per-call](./use-cases/m2m-and-api.md) — x402 / L402 patterns, idempotency, cost ceilings.
• [M2M — machine-to-machine commerce](./use-cases/m2m-and-api.md) — agents buying from agents.

Merchant playbooks (the wedge)

The protocols leave these to merchants. We wrote them down because we ran them.

• [Catalog discovery at scale](./merchant-playbooks/catalog-discovery-at-scale.md) — ranking, locale, currency, jurisdiction.
• [Pricing drift and re-quote](./merchant-playbooks/pricing-drift-and-requote.md) — quote-vs-settle drift.
• [Multi-chain settlement reconciliation](./merchant-playbooks/multi-chain-settlement-reconciliation.md) — five chains, one ledger.
• [Refunds and disputes for agents](./merchant-playbooks/refunds-and-disputes-for-agents.md) — no chargeback in stablecoin.
• [Fraud signals on agent traffic](./merchant-playbooks/fraud-signals-on-agent-traffic.md) — defender-side detection patterns.
• [Jurisdiction and tax metadata](./merchant-playbooks/jurisdiction-and-tax-metadata.md) — gift cards, travel-rule, country-by-country.
• [Agent authorization scopes](./merchant-playbooks/agent-authorization-scopes.md) — per-merchant, per-amount, per-window.
• [Delivery semantics — codes, PNRs, eSIMs](./merchant-playbooks/delivery-semantics-codes-pnrs-esims.md) — what "delivered" means per product.
• [Receipts and proof-of-purchase](./merchant-playbooks/receipts-and-proof-of-purchase.md) — signed, machine-parseable.

Agent playbooks

• [ChatGPT Instant Checkout](./agent-playbooks/agent-runtimes.md#chatgpt-instant-checkout-acp)
• [Claude Skills for commerce](./agent-playbooks/agent-runtimes.md)
• [Cursor + MCP storefront](./agent-playbooks/agent-runtimes.md)
• [x402 buyer loop](./agent-playbooks/x402-buyer-loop.md)
• [AP2 mandate flow](./agent-playbooks/ap2-mandate-flow.md)
• [Multi-agent procurement](./agent-playbooks/multi-agent-procurement.md)

Examples (runnable)

Comparison

• [Protocol matrix](./comparison/protocol-matrix.md) — capability × protocol, sourced.
• [Decision tree](./comparison/decision-tree.md) — pick the right protocol for your use case.
• [Rails comparison](./comparison/rails-comparison.md) — settlement speed, finality, fees, dispute model.
• [Merchant readiness scorecard](./comparison/merchant-readiness-scorecard.md) — score yourself.

Production merchant checklist

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

What protocols don't solve

→ [/docs/what-protocols-dont-solve.md](./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.

Production merchant reference model

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.

Contributing

See CONTRIBUTING.md. Three rules:

1. Official sources only — link to the maintaining org's spec, doc, blog, or repo.
2. Production-evidence preferred — for playbooks and examples, link to a public artifact.
3. One change per PR — easier to review, faster to merge.

We aim for a 24-hour merge SLA on trivially-correct PRs.

Maintainers

Built and maintained by engineers from Cryptorefills who run this stack daily.

• @simonlucalandi — primary maintainer
• @CGRDMZ
• @matsveenman

See .github/CODEOWNERS and CITATION.cff.

License

• 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.

Citation

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.

About the Maintainer

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.

What Cryptorefills runs:

• Website: https://www.cryptorefills.com
• Spend crypto: https://www.cryptorefills.com/en/spend-crypto