AgentMart 🤖🛒

Decentralized AI Agent Marketplace - A full-stack Web3 application for buying, selling, and executing AI agents on the blockchain.

🏗️ Architecture

                      ┌──────────────────────────┐
                      │        React UI          │
                      │   wagmi + ethers.js      │
                      └────────────┬─────────────┘
                                   │
                          Wallet Connect / Buy
                                   │
                      ┌────────────▼─────────────┐
                      │       Smart Contract      │
                      │     AgentMarket.sol       │
                      └────────────┬─────────────┘
                                   │ Events
                    ┌──────────────▼───────────────┐
                    │          The Graph            │
                    │ (Indexes AgentPurchased evt)  │
                    └──────────────┬───────────────┘
                                   │ GraphQL
                      ┌────────────▼──────────────┐
                      │      React Analytics       │
                      │ (Purchases, revenue etc.)  │
                      └────────────────────────────┘


                      ┌────────────────────────────┐
                      │       Node.js Backend       │
                      │ Express + Postgres + JWT    │
                      │ Server-side TX (optional)   │
                      └────────────────────────────┘

📦 Tech Stack

Frontend

• React + TypeScript + Vite - Fast, modern development
• wagmi + ethers.js - Ethereum wallet integration
• Zustand - State management
• Tailwind CSS - Styling
• React Query - Data fetching

Backend

• Node.js + Express + TypeScript
• PostgreSQL (pg) - Database
• JWT - Authentication (wallet sign-in)
• Socket.io - Real-time updates
• ethers.js - Event listening & server-side transactions

Blockchain

• Solidity - Smart contracts
• Hardhat - Development environment
• Alchemy - RPC provider & WebSocket
• The Graph - Event indexing

🚀 Quick Start

Prerequisites

• Node.js >= 18
• PostgreSQL >= 14
• MetaMask or compatible wallet
• Alchemy account (free tier works)

1. Clone & Install

git clone <your-repo>
cd AgentMart
npm run install:all

2. Configure Environment

cp .env.example .env
# Edit .env with your values

Required variables:

• ALCHEMY_API_KEY - Get from Alchemy
• DATABASE_URL - PostgreSQL connection string
• JWT_SECRET - Random secret for JWT signing
• RELAY_PRIVATE_KEY - Private key for server-side transactions (optional)

3. Set Up Database

# Create database
createdb agentmart

# Run migrations
npm run migrate:db

# Seed with sample agents
npm run seed:db

4. Deploy Smart Contract

# Option A: Local Hardhat network (for development)
cd contracts
npx hardhat node  # Keep running in separate terminal
npx hardhat run scripts/deploy.ts --network localhost

# Option B: Testnet (Sepolia)
npx hardhat run scripts/deploy.ts --network sepolia

Copy the deployed contract address to .env as CONTRACT_ADDRESS.

5. Start Development Servers

# Start all services (frontend, backend, listener)
npm run dev:start

# Or start individually:
npm run dev:frontend   # http://localhost:5173
npm run dev:backend    # http://localhost:3001
npm run dev:listener   # Event listener

🎬 2-Minute Demo Script

Setup (30 seconds)

1. Ensure all services are running (npm run dev:start)
2. Open http://localhost:5173 in browser
3. Have MetaMask installed and connected to Sepolia testnet

Demo Flow (90 seconds)

Step 1: Connect Wallet

• Click "Connect Wallet" button
• Approve MetaMask connection
• Click "Sign In" to authenticate with backend
• See your address displayed

Step 2: Browse Agents

• View list of AI agents with descriptions and prices
• Click on an agent card to see details
• Example: "Code Review Agent" - 0.001 ETH

Step 3: Purchase Agent

• Click "Buy Agent" button
• Choose purchase method:
  • Client-side: You pay gas (MetaMask popup)
  • Server-relay: Server pays gas (faster, sponsored)
• Confirm transaction

Step 4: Watch Transaction

• See transaction hash and Etherscan link
• Backend listener detects AgentPurchased event
• Order status updates: Pending → Confirmed
• Real-time toast notification via Socket.io

Step 5: View Result

• Order marked as "Confirmed" in your purchases
• Agent execution result displayed (or mock data)
• Transaction visible on Etherscan

Optional: The Graph Query

• View analytics dashboard
• GraphQL query shows all purchases, total revenue
• Indexed from blockchain events

📁 Project Structure

AgentMart/
├── frontend/                 # React + Vite app
│   ├── src/
│   │   ├── components/      # UI components
│   │   │   ├── WalletConnect.tsx
│   │   │   ├── AgentList.tsx
│   │   │   ├── AgentDetail.tsx
│   │   │   └── BuyButton.tsx
│   │   ├── state/          # Zustand store
│   │   ├── utils/          # ethers.js helpers
│   │   ├── api.ts          # API client
│   │   └── App.tsx
│   ├── package.json
│   └── vite.config.ts
│
├── backend/                 # Express API
│   ├── src/
│   │   ├── routes/         # API endpoints
│   │   │   ├── auth.ts     # Wallet sign-in
│   │   │   ├── agents.ts   # Agent CRUD
│   │   │   └── purchase.ts # Order management
│   │   ├── db/             # PostgreSQL client
│   │   ├── listener.ts     # Event listener (Alchemy WS)
│   │   ├── relayer.ts      # Server-side signer
│   │   └── index.ts        # Express app
│   └── package.json
│
├── contracts/               # Solidity + Hardhat
│   ├── contracts/
│   │   └── AgentMarket.sol
│   ├── scripts/
│   │   └── deploy.ts
│   ├── test/
│   │   ├── AgentMarket.test.ts
│   │   └── gas-usage.test.ts
│   ├── abi/
│   │   └── AgentMarket.json
│   └── hardhat.config.ts
│
├── subgraph/               # The Graph indexing
│   ├── schema.graphql
│   ├── subgraph.yaml
│   └── mappings/
│       └── mapping.ts
│
├── scripts/                # Database & deployment
│   ├── migrate.sql
│   ├── seed_agents.sql
│   └── deploy_contract.sh
│
├── .env.example
├── package.json
└── README.md

🔑 Key Features

Dual Purchase Modes

1. Client-Side Purchase (User pays gas)

// Frontend signs transaction
const tx = await contract.purchase(agentId, { value: price });
// Backend records order with txHash
await fetch('/api/purchase', { 
  method: 'POST', 
  body: { agentId, txHash: tx.hash } 
});

2. Server-Relay Purchase (Server pays gas - sponsored experience)

// Frontend requests purchase
const { txHash } = await fetch('/api/purchase', {
  method: 'POST',
  body: { agentId, amount }
});
// Backend signs & sends transaction with RELAY_PRIVATE_KEY

Event-Driven Architecture

1. Smart Contract emits AgentPurchased event
2. Listener Service (Alchemy WebSocket) catches event
3. Database updated with confirmation
4. Socket.io pushes update to frontend
5. The Graph indexes for analytics

🧪 Testing

Smart Contract Tests

cd contracts

# Run all tests
npm test

# Gas usage analysis
npm run test:gas

# Coverage
npm run coverage

Backend Tests

cd backend
npm test

🚢 Deployment

Smart Contract

# Deploy to Sepolia testnet
cd contracts
npm run deploy:sepolia

# Verify on Etherscan
npx hardhat verify --network sepolia <CONTRACT_ADDRESS>

Backend API

cd backend
npm run build

# Deploy to your preferred platform:
# - Railway, Render, Fly.io for Node.js
# - Configure DATABASE_URL for production PostgreSQL

Frontend

cd frontend
npm run build

# Deploy to Vercel, Netlify, or Cloudflare Pages
# Set environment variables in hosting platform

The Graph Subgraph

# Authenticate with The Graph Studio
graph auth --studio <DEPLOY_KEY>

# Deploy subgraph
npm run subgraph:codegen
npm run subgraph:build
npm run subgraph:deploy

🔐 Security Notes

⚠️ Important for Production:

1. Never commit private keys - Use environment variables
2. Rotate JWT secrets - Use strong, random values
3. Limit relayer funds - Use dedicated wallet with minimal ETH
4. Validate inputs - Add rate limiting, input sanitization
5. Use HTTPS - Enable SSL/TLS in production
6. Database security - Use connection pooling, prepared statements
7. Audit contracts - Get professional audit before mainnet

📚 API Documentation

Authentication

POST /api/auth/sign-message

{ "address": "0x..." }
→ { "message": "Sign this message to authenticate: <nonce>" }

POST /api/auth/verify

{ "address": "0x...", "signature": "0x..." }
→ { "token": "jwt_token_here" }

Agents

GET /api/agents

→ [{ "id": 1, "name": "Code Review Agent", "price": "0.001", ... }]

GET /api/agents/:id

→ { "id": 1, "name": "Code Review Agent", "description": "...", "price": "0.001" }

Purchases

POST /api/purchase (Authenticated)

// Client-side purchase
{ "agentId": 1, "txHash": "0x..." }

// Server-relay purchase  
{ "agentId": 1, "amount": "0.001" }

→ { "orderId": 123, "txHash": "0x...", "status": "pending" }

GET /api/orders/:id (Authenticated)

→ { "id": 123, "status": "confirmed", "txHash": "0x...", "agent": {...} }

🎨 Frontend Components

• WalletConnect: Wallet connection, sign-in flow
• AgentList: Browse available AI agents
• AgentDetail: View agent details, purchase
• BuyButton: Purchase flow (client or relay)
• ToastNotification: Real-time transaction updates

🔧 Troubleshooting

Database connection failed

# Check PostgreSQL is running
pg_ctl status

# Verify connection string
psql $DATABASE_URL

Contract deployment fails

# Check network configuration in hardhat.config.ts
# Verify ALCHEMY_API_KEY is set
# Ensure deployer wallet has ETH for gas

Frontend can't connect to wallet

# Install MetaMask extension
# Switch to correct network (Sepolia)
# Check VITE_CONTRACT_ADDRESS in frontend/.env

Listener not receiving events

# Verify ALCHEMY_API_KEY supports WebSockets
# Check CONTRACT_ADDRESS is correct
# Ensure contract has Purchase events emitted

🛠️ Development Tips

Add a new agent

INSERT INTO agents (name, description, price, category)
VALUES ('New Agent', 'Description', 0.001, 'Development');

Test contract locally

# Terminal 1: Start local node
npx hardhat node

# Terminal 2: Deploy & test
npx hardhat run scripts/deploy.ts --network localhost
npx hardhat test --network localhost

Monitor events in real-time

# Backend listener logs all events
npm run dev:listener

# Or manually test with ethers.js
node scripts/test-listener.js

📈 TODO / Future Enhancements

• Implement actual OpenAI agent execution
• Add agent rating/review system
• Support multiple payment tokens (ERC-20)
• Gas optimization in smart contract
• Add agent marketplace curation
• Implement dispute resolution
• Mobile responsive UI improvements
• Add agent execution history dashboard
• Support batch purchases
• Implement agent versioning