Skip to main content

Architecture

Monorepo Structure​

crumb-sdk/
├── packages/
│   ├── core/          # crumb-alpha-core — low-level primitives
│   ├── sdk/           # crumb-alpha-sdk — high-level client + provider helpers
│   └── cli/           # crumb-alpha-cli — command-line tool
├── examples/
│   ├── agent-basic/       # Single paid API call
│   ├── agent-loop/        # Multiple sequential calls
│   ├── agent-to-provider/ # Self-contained demo
│   └── provider-express/  # Standalone Express provider
├── docs/              # Docusaurus documentation
└── package.json       # pnpm workspace root

Package Dependency Graph​

crumb-alpha-cli
  └── crumb-alpha-sdk
        └── crumb-alpha-core
              └── @circle-fin/x402-batching
                    ├── viem (signing, accounts)
                    └── Circle Gateway API

crumb-alpha-core is the foundation — it re-exports GatewayClient, wallet utilities, error types, and settlement helpers from @circle-fin/x402-batching.

crumb-alpha-sdk builds on core to provide the Crumb class (agent-side) and createProvider (seller-side).

crumb-alpha-cli uses both packages to provide a command-line interface for wallet management and payments.

Payment Flow​

┌─────────┐                    ┌──────────┐                  ┌─────────────────┐
│  Agent   │                    │ Provider │                  │ Circle Gateway  │
│ (Crumb)  │                    │ (Express)│                  │                 │
└────┬─────┘                    └────┬─────┘                  └────────┬────────┘
     │                               │                                 │
     │  1. POST /search              │                                 │
     │ ─────────────────────────────>│                                 │
     │                               │                                 │
     │  2. 402 Payment Required      │                                 │
     │     { price: "$0.001" }       │                                 │
     │ <─────────────────────────────│                                 │
     │                               │                                 │
     │  3. gateway.pay(url)          │                                 │
     │     Signs EIP-712 payment     │                                 │
     │ ──────────────────────────────────────────────────────────────> │
     │                               │                                 │
     │  4. Payment verified          │                                 │
     │ <──────────────────────────────────────────────────────────────│
     │                               │                                 │
     │  5. POST /search              │                                 │
     │     + X-PAYMENT header        │                                 │
     │ ─────────────────────────────>│                                 │
     │                               │  6. Verify payment              │
     │                               │ ──────────────────────────────> │
     │                               │                                 │
     │                               │  7. Payment valid               │
     │                               │ <──────────────────────────────│
     │                               │                                 │
     │  8. 200 OK + data             │                                 │
     │ <─────────────────────────────│                                 │
     │                               │                                 │

Key Design Decisions​

Wrapping @circle-fin/x402-batching — Rather than implementing x402 from scratch, Crumb wraps Circle's official SDK. This ensures protocol compatibility and means Crumb automatically benefits from upstream improvements.

Gasless payments — All payments go through Circle Gateway, which batches on-chain settlements. Agents never need ETH for gas — just USDC deposited in the Gateway.

Price ceiling (maxPayment) — Agents can set a maximum price they're willing to pay per request. The SDK probes the endpoint first and throws PRICE_EXCEEDED before any payment is signed if the price is too high.

Low balance hooks — The Crumb client can trigger callbacks when the Gateway balance drops below a threshold, allowing agents to autonomously top up or alert operators.

Tech Stack​

  • TypeScript — strict mode, ESM modules
  • viem — Ethereum account management and signing
  • Express — provider middleware (seller-side)
  • pnpm workspaces + Turborepo — monorepo management
  • Vitest — unit testing
  • Docusaurus — documentation