Getting Started

Prerequisites

• Node.js >= 18
• pnpm (recommended) or npm
• A private key with USDC on Arc Testnet (for testing)

Installation

Install the SDK in your project:

pnpm add crumb-alpha-sdk

Or install the CLI globally:

pnpm add -g crumb-alpha-cli

Development Setup (Monorepo)

If you're working on Crumb itself:

git clone https://github.com/crumb-sdk/crumb-sdk.git
cd crumb-sdk
pnpm install
pnpm build

Running Tests

pnpm test

Running Examples

Create a .env file in the project root:

TEST_PRIVATE_KEY=0x...your_private_key...
CRUMB_WALLET_ADDRESS=0x...your_wallet_address...

Then run any example:

# Self-contained demo (provider + agent in one script)
npx tsx --env-file=.env examples/agent-to-provider/index.ts

# Or run provider and agent separately:
# Terminal 1
npx tsx --env-file=.env examples/provider-express/index.ts
# Terminal 2
npx tsx --env-file=.env examples/agent-basic/index.ts

Concepts

Agent (Buyer)

An agent is any program that needs to pay for API resources. The Crumb class wraps Circle's GatewayClient and handles the full x402 payment flow automatically:

1. Probe the URL to check if it requires payment
2. Validate the price against maxPayment
3. Sign and submit payment via Circle Gateway
4. Return the API response with payment metadata

Provider (Seller)

A provider is an Express server with paywalled endpoints. Circle's createGatewayMiddleware handles payment verification and settlement. You just set a price per endpoint.

Circle Gateway

Circle Gateway is the settlement layer. Agents deposit USDC into the Gateway, and payments are signed off-chain using EIP-712 signatures. The Gateway batches and settles transactions periodically, eliminating per-call gas fees.

Supported Chains

Chain	Description
arcTestnet	Circle's Arc testnet

Crumb uses arcTestnet for development. Mainnet chains will be supported in a future release.

Funding Your Wallet

To test payments, your wallet needs USDC deposited into the Gateway on Arc Testnet. You can get testnet USDC from Circle's faucet and then deposit it:

const crumb = new Crumb({
  privateKey: process.env.TEST_PRIVATE_KEY!,
  chain: 'arcTestnet',
})

// Check current balance
console.log(await crumb.balance()) // "0"

// Deposit USDC into Gateway (requires USDC in wallet first)
await crumb.deposit('10.0')

// Now you can make payments
console.log(await crumb.balance()) // "10.0"