Local Development

Run Crossmint Agentic Finance demos locally and set up your development environment

Overview

All demos in Crossmint Agentic Finance can be run locally for development and testing. This guide covers setting up your local environment and running demos.

Prerequisites

Required Tools

• Node.js: 18.17.0 or higher
• npm: 9.0.0 or higher
• Git: For cloning the repository

Required API Keys

1. Get Crossmint API Key

   1. Visit Crossmint Console
   2. Create a new Smart Wallet project
   3. Navigate to API Keys section
   4. Create an API key with scopes: wallets.create, wallets.read, wallets:messages.sign
   5. Copy the key (starts with sk_)
2. Get OpenAI API Key (for AI agents)

   Visit OpenAI Platform and create an API key

3. Get Testnet USDC

   For blockchain interactions, get test USDC from Circle Faucet

   • Select Base Sepolia network
   • Paste your wallet address
   • Mint 1-10 USDC for testing

Quick Start: Simplest Demo

The ping demo is the simplest way to understand the x402 payment flow:

# Clone repository
git clone https://github.com/crossmint/crossmint-agentic-finance.git
cd crossmint-agentic-finance

# Run basic x402 paywall
cd ping
cp .env.example .env
# Edit .env: Set PAY_TO to your address
npm install
npm run dev

# Test in another terminal
curl -i -H "Accept: application/json" http://localhost:3000/ping
# Returns 402 Payment Required with payment details

Running Events Concierge Demo

The events concierge is the most complete demo with MCP, autonomous payments, and Cloudflare Durable Objects.

Step 1: Install Dependencies

cd events-concierge
npm install

Step 2: Configure Environment

Create .dev.vars file with your API keys:

.dev.vars

CROSSMINT_API_KEY=sk_your_api_key_here
OPENAI_API_KEY=sk-your_openai_key_here

Step 3: Run Development Server

npm run dev

This starts:

• React UI at http://localhost:5173
• Cloudflare Worker with Durable Objects
• WebSocket server for agent communication

Step 4: Test the Payment Flow

1. Connect the agents

   • Open http://localhost:5173
   • Click “Connect to Events” in the chat
   • Guest agent establishes MCP connection to Host
2. Create an event (as host)

   • Go to http://localhost:5173/?view=my-mcp
   • Sign in with email OTP
   • Create an event with a price (e.g., $0.05)
3. Fund the guest wallet

   • Copy the Guest wallet address from chat
   • Visit Circle Faucet
   • Select “Base Sepolia” and paste address
   • Mint 1 USDC
4. Watch autonomous payment

   Say: rsvp to event <event-id>

   The guest agent will:

   1. Detect 402 response
   2. Confirm payment with user
   3. Sign and submit USDC transfer
   4. Retry MCP call with payment proof
   5. Display TX hash and confirmation

Running Other Demos

HTTP Paywalls

Ping (Express + x402)

cd ping
cp .env.example .env
npm install
npm run dev
# Test: curl -i http://localhost:3000/ping

Weather API

cd weather
cp .env.example .env
npm install
npm run dev
# Test: curl http://localhost:3000/weather?city=London

Ping with Crossmint UI

cd ping-crossmint/server
cp .env.example .env
npm install
npm run dev

# In another terminal
cd ping-crossmint/client
npm install
npm run dev
# Open http://localhost:5173

Agent-to-Agent Demos

Basic A2A with EOA Wallets

cd hello-eoa-a2a
cp .env.example .env
# Edit .env with private keys
npm install
npm run dev

Crossmint Wallets A2A

cd hello-crossmint-wallets-a2a
cp .env.example .env
# Edit .env with CROSSMINT_API_KEY
npm install
npm run dev

Development Workflow

File Structure (events-concierge)

events-concierge/
├── src/
│   ├── agents/
│   │   ├── host.ts          # MCP server with paid tools
│   │   └── guest.ts         # MCP client with auto-payment
│   ├── shared/
│   │   └── eventService.ts  # KV operations for events
│   ├── utils/
│   │   ├── cors.ts          # CORS headers for MCP
│   │   └── hashing.ts       # User ID hashing
│   ├── server.ts            # Cloudflare Worker entry
│   ├── constants.ts         # Chain config, addresses
│   └── x402Adapter.ts       # Crossmint → viem adapter
├── wrangler.toml            # Durable Object bindings
├── .dev.vars                # Local secrets (gitignored)
└── package.json

Testing Payment Verification

# Check wallet balances (Base Sepolia)
cast balance <WALLET_ADDRESS> --rpc-url https://sepolia.base.org

# Check USDC balance
cast call 0x036CbD53842c5426634e7929541eC2318f3dCF7e \
  "balanceOf(address)(uint256)" \
  <WALLET_ADDRESS> \
  --rpc-url https://sepolia.base.org

# Get transaction details
cast tx <TX_HASH> --rpc-url https://sepolia.base.org

# Verify transaction receipt
cast receipt <TX_HASH> --rpc-url https://sepolia.base.org

Browser Console Testing

// Connect to guest agent via WebSocket
ws = new WebSocket("ws://localhost:5173/agent");
ws.onmessage = (e) => console.log("Received:", JSON.parse(e.data));

// Connect to host MCP server
ws.send(JSON.stringify({
  type: "connect",
  hostUrl: "http://localhost:5173/mcp/users/<userId>"
}));

// Call free tool
ws.send(JSON.stringify({
  type: "call_tool",
  tool: "listEvents",
  args: {}
}));

// Call paid tool (triggers 402 flow)
ws.send(JSON.stringify({
  type: "call_tool",
  tool: "rsvpToEvent",
  args: { eventId: "<event-id>" }
}));

Network Configuration

Base Sepolia (Testnet - Default)

// src/constants.ts
export const USDC_BASE_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
export const NETWORK = "base-sepolia";
export const CHAIN_ID = 84532;

Faucets:

• USDC: Circle Faucet
• ETH: Base Sepolia Faucet

Explorer:

• Base Sepolia Explorer

Troubleshooting

”Cannot find module” Errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Port Already in Use

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or change port in .env
PORT=3001

Wrangler Dev Issues

# Clear Wrangler cache
rm -rf ~/.wrangler

# Update Wrangler
npm install -g wrangler@latest

Payment Verification Failed

Check wallet has USDC

# Check USDC balance on Base Sepolia
cast call 0x036CbD53842c5426634e7929541eC2318f3dCF7e \
  "balanceOf(address)(uint256)" \
  <WALLET_ADDRESS> \
  --rpc-url https://sepolia.base.org

Verify network consistency

Ensure all components use the same network:

• Guest agent: base-sepolia
• Host agent: base-sepolia
• USDC contract: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
• Chain ID: 84532

Check facilitator is accessible

curl https://x402.org/facilitator/health

Durable Objects State Issues

# Wrangler doesn't persist DO state in dev mode
# Restart the dev server to reset state
Ctrl+C
npm run dev

Development Tips

Use wrangler tail to stream logs from your Worker in real-time:

npx wrangler tail

.dev.vars contains secrets and is gitignored. Never commit API keys to version control.

For Cloudflare Workers, local development uses wrangler dev which simulates the Cloudflare runtime. Some features may behave differently than in production.

Next Steps

Deploy to Cloudflare

Deploy your agent to Cloudflare Workers and Durable Objects

Production Checklist

Prepare your app for mainnet deployment