Snappy Agents

Let any AI agent buy from the Snappy Marketplace. Snappy Agents is the connector platform behind agents.snappy.com: an OAuth 2.1 server, a REST API with an OpenAPI 3.1 contract, an MCP endpoint, a hosted Stripe checkout and an operations portal. Meta Muse is the first agent platform it is registered with; Claude, ChatGPT or a partner agent connect the same way.

What a user can do through their agent

• Search the marketplace by words and budget, browse curated collections (shipping to the US).
• See the exact all-in price (item + shipping + duties + optional service fee) before committing.
• Put several items in one cart and pay once on a secure Stripe page the agent never sees; Snappy fulfils each item as its own order.
• Get the confirmation in real time inside the conversation, then the receipt by email or SMS (with explicit SMS consent).
• Track delivery, cancel before fulfilment for a refund, open a support request for returns or damaged items, and re-send receipts.

How it fits together

 Agent platform (Muse, Claude, ...)        agents.snappy.com (Cloud Run, this repo)              Snappy / providers
 ─────────────────────────────────         ─────────────────────────────────────────            ─────────────────────
 OAuth 2.1 + PKCE  ───────────────▶  /oauth/*  authorize · token · register · revoke
 REST  /v1/*  or  MCP  /mcp  ─────▶  Catalog ─▶ CatalogService ────────────────────────────▶  Snappy Public API v3
                                     Quote  ─▶ availability + fee ─▶ 15 min price lock       (products, variants,
                                     Checkout (cart) ─▶ Stripe Checkout Session ─▶ paymentUrl  availability, orders)
 user pays on Stripe  ────────────▶  /webhooks/stripe ─▶ one order per item (idempotent) ───▶  POST /v3/orders
 SSE / poll / callback ◀──────────  order.confirmed ─▶ email (SendGrid) · SMS (Twilio)
                                     /webhooks/snappy ◀────────────────────────────────────  order status / delivery
 Operators ───────────────────────▶  /admin  (Identity-Aware Proxy, @snappy.com)  users · orders · support · integrations · settings · audit

Everything runs as one Cloud Run service per environment (sandbox, prod) in its own GCP project, with Cloud SQL (Postgres, private IP only) inside a VPC, Cloud Tasks for durable background work and Secret Manager for credentials. Provider credentials (Snappy, Stripe, SendGrid, Twilio) are entered once in the admin portal's Integrations page and stored in Secret Manager; nothing is baked into a deploy. See Architecture.

Start here

Design principles

1. The agent never touches money or cards. Payment is a hosted Stripe link; the platform only learns the outcome via signed webhooks.
2. Every write is idempotent. Quotes lock prices, each cart item keys its Snappy order by checkout id + item index, webhooks dedupe by provider event id, tasks dedupe by name.
3. Read vs act is enforced at the token. orders:write is a separate scope; users can choose read-only on the consent screen (a Meta Muse requirement).
4. Errors are a contract. Stable code values and machine-usable extra fields (allowedCountries, suggestions, supportUrl) so the agent can recover gracefully.
5. Nothing silent. Every transition is an event (timeline, SSE, admin), every message is recorded, every admin action is audited.