Skip to main content

​
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: 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 USDC balance on Base Sepolia
cast call 0x036CbD53842c5426634e7929541eC2318f3dCF7e \
  "balanceOf(address)(uint256)" \
  <WALLET_ADDRESS> \
  --rpc-url https://sepolia.base.org
Ensure all components use the same network:
  • Guest agent: base-sepolia
  • Host agent: base-sepolia
  • USDC contract: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
  • Chain ID: 84532
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

Build docs developers (and LLMs) love

Get started for freeTalk to us