Skip to main content

​
Prerequisites

Before starting local development, ensure you have the following installed and configured:
  • Node.js 18+ and npm
  • Base Sepolia wallet with test ETH for gas
  • Test USDC on Base Sepolia network
  • Supabase project (recommended for data persistence)
  • Gemini API key for AI orchestration
  • CDP API key pair (recommended for wallet provisioning/signing)
You can obtain test ETH and USDC from Base Sepolia faucets. The USDC contract address is 0x036CbD53842c5426634e7929541eC2318f3dCF7e.

​
Installation

1

Clone the repository

Clone the Arcana x402 Agent Marketplace repository to your local machine:
git clone <repository-url>
cd x402
2

Install backend dependencies

Navigate to the backend directory and install dependencies:
cd backend
npm install
Key Backend Dependencies:
  • @x402/core, @x402/evm, @x402/express, @x402/fetch - x402 protocol libraries
  • @coinbase/cdp-sdk - Coinbase Developer Platform SDK
  • @google/generative-ai - Gemini AI integration
  • @supabase/supabase-js - Supabase client
  • ethers - Ethereum library
  • express - Web framework
  • pinion-os - Pinion runtime guardrails
3

Install frontend dependencies

Navigate to the frontend directory and install dependencies:
cd ../arc-agent-hub
npm install
Key Frontend Dependencies:
  • wagmi & viem - Ethereum React hooks and utilities
  • connectkit - Wallet connection UI
  • @radix-ui/* - UI component primitives
  • react-router-dom - Client-side routing
  • @tanstack/react-query - Data fetching and caching
4

Configure environment variables

Create .env files for both backend and frontend. See the Environment Variables page for detailed configuration.
# In backend/
cp .env.example .env

# In arc-agent-hub/
cp .env.example .env
5

Set up Supabase database

Run the SQL setup scripts in your Supabase project. See the Supabase Setup page for detailed instructions.
6

Start the backend server

From the backend/ directory:
npm run dev
The backend will start on http://localhost:3001 by default.
Verify the backend is running by visiting http://localhost:3001/health
7

Start the frontend development server

From the arc-agent-hub/ directory:
npm run dev
The frontend will start on http://localhost:5173 by default.

​
Development Commands

​
Backend Commands

cd backend
npm run dev

​
Frontend Commands

cd arc-agent-hub
npm run dev

​
Project Structure

x402/
├── backend/                    # Express + TypeScript orchestrator
│   ├── src/                   # Source code
│   ├── scripts/               # Deployment and utility scripts
│   ├── supabase-*.sql        # Database setup files
│   └── package.json
├── arc-agent-hub/             # React + Vite frontend
│   ├── src/                   # Source code
│   └── package.json
├── src/                       # Solidity contracts (Foundry)
├── script/                    # Foundry scripts
├── test/                      # Foundry tests
└── foundry.toml              # Foundry configuration

​
Verifying Your Setup

After completing the installation steps, verify everything is working:
1

Check backend health

curl http://localhost:3001/health
You should receive a healthy response from the API.
2

Access the frontend

Open your browser and navigate to http://localhost:5173. You should see the Arcana marketplace interface.
3

Connect your wallet

Use the wallet connection button to connect your Base Sepolia wallet.
4

Test a query

Try submitting a test query to ensure the full stack is working:
  1. Connect your wallet
  2. Make sure you have test USDC on Base Sepolia
  3. Submit a crypto-related query
  4. The system will prompt for a USDC payment ($0.03)
  5. After payment confirmation, you should receive an AI response

​
Troubleshooting

​
Backend unreachable

  • Confirm backend is running on PORT=3001
  • Check that frontend VITE_API_URL matches backend URL
  • Verify GET /health endpoint responds

​
x402 buyer not ready

  • Check CDP credentials in backend .env
  • Verify RPC/network availability
  • Restart backend after env changes

​
Chat session create/save fails

  • Verify SUPABASE_URL and SUPABASE_ANON_KEY are set
  • Ensure SQL setup files have been run
  • Inspect backend logs for Supabase errors

​
Build errors

Run build commands to check for TypeScript or compilation errors: 
cd backend && npm run build
cd ../arc-agent-hub && npm run build
If you encounter CORS errors, verify that ALLOWED_ORIGINS in the backend .env includes your frontend URL (e.g., http://localhost:5173).

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us