Development

make dev          # Build and start all services (backend, frontend, mythos)
make dev-clean    # Full rebuild — removes all dev compose volumes and rebuilds from scratch

make down         # Stop all services

Requires Docker. Services: backend on :8080, frontend on :3000, mythos (admin) on :3001.

Local Stripe webhooks: any flow touching top-ups (e.g. the agent dashboard's "Top Up" button) also needs the Stripe CLI forwarding events to localhost — without it, payments succeed on Stripe but the dashboard balance silently stays at $0. See backend/README.md § Local development with Stripe for the full setup (test-mode keys, CLI install, the stripe listen command, whsec rotation).

---

Quick Start

TypeScript (Express)

pnpm add @sangria-sdk/core express

import express from "express";
import { Sangria } from "@sangria-sdk/core";
import { fixedPrice } from "@sangria-sdk/core/express";

const app = express();
const sangria = new Sangria({ apiKey: process.env.SANGRIA_API_KEY! });

app.get(
  "/premium",
  fixedPrice(sangria, { price: 0.01, description: "Premium content" }),
  (req, res) => {
    res.json({ data: "premium content", tx: req.sangria?.transaction });
  }
);

app.listen(3000);

Python (FastAPI)

pip install sangria-merchant-sdk[fastapi]

from fastapi import FastAPI, Request
from sangria_sdk import SangriaMerchantClient
from sangria_sdk.adapters.fastapi import require_sangria_payment

app = FastAPI()
client = SangriaMerchantClient(api_key=os.environ["SANGRIA_API_KEY"])

@app.get("/premium")
@require_sangria_payment(client, amount=0.01, description="Premium content")
async def premium(request: Request):
    return {"data": "premium content"}

That's it. Your endpoint now charges $0.01 per request. AI agents pay automatically via the x402 protocol.

---

Supported Frameworks

Language	Framework	Adapter Import
TypeScript	Express >= 4	@sangria-sdk/core/express
TypeScript	Fastify >= 4	@sangria-sdk/core/fastify
TypeScript	Hono >= 4	@sangria-sdk/core/hono
Python	FastAPI >= 0.135	sangria_sdk.adapters.fastapi

---

How It Works

sequenceDiagram
    participant Agent as AI Agent
    participant Merchant as Your Server (SDK)
    participant Sangria as Sangria Backend
    participant Facilitator as Coinbase Facilitator

    Agent->>Merchant: GET /premium
    Merchant->>Sangria: Generate payment terms
    Sangria-->>Merchant: Payment requirements
    Merchant-->>Agent: 402 Payment Required
    Agent->>Agent: Sign EIP-712 authorization
    Agent->>Merchant: GET /premium + PAYMENT-SIGNATURE
    Merchant->>Sangria: Settle payment
    Sangria->>Facilitator: Verify & settle on Base
    Facilitator-->>Sangria: Settlement confirmed
    Sangria-->>Merchant: Success + tx hash
    Merchant-->>Agent: 200 + content

Loading

---

Features

• Zero gas fees — Coinbase Facilitator sponsors gas on Base
• Framework agnostic — Express, Fastify, Hono, and FastAPI with more coming
• Fixed & variable pricing — exact and upto payment schemes
• Double-entry ledger — internal credit system with idempotent transactions
• Standards-compliant — EIP-712 typed signing, ERC-3009 USDC transfers, x402 v2

---

Project Structure

Directory	What	Stack
backend/	Orchestration API — accounts, payments, settlement	Go, Fiber, pgx
dbSchema/	Database schema (single source of truth)	Drizzle ORM
frontend/	Documentation site	Next.js, Tailwind
sdk/merchants/sdk-typescript/	TypeScript merchant SDK (@sangria-sdk/core)	TypeScript
sdk/merchants/python/	Python merchant SDK (sangria-merchant-sdk)	Python, httpx
playground/	Example merchants + buyer client	Express, Fastify, Hono, FastAPI

---

Documentation

• TypeScript SDK — full API, all framework adapters, bypass config
• Python SDK — FastAPI adapter, API contract
• Playground — run example merchants and test payments locally
• Backend API — API reference, self-hosting guide
• Architecture — layered architecture deep-dive
• Protocol Overview — x402 operations and settlement flow