A TypeScript monorepo implementing the x402 payment protocol for VeChain blockchain. This project enables seamless cryptocurrency payment facilitation using VeChain's native tokens (VET, VTHO, VEUSD, B3TR) with support for testnet and mainnet environments.
This monorepo consists of:
- apps/api - Hono-based REST API implementing the x402 protocol facilitator endpoints
- apps/dashboard - React Router admin dashboard for managing payments
- apps/web - Astro marketing website
- examples/ - Practical integration examples and templates
- Minimal Server - Simple paid API
- Minimal Client - Browser wallet integration
- AI Agent - Autonomous payment bot
- Content Paywall - Full-stack paywall
- Node.js 20 or higher
- pnpm 10.12.4 (install with
npm install -g [email protected]) - PostgreSQL database (for API)
- VeChain RPC access (testnet/mainnet)
- Clone the repository:
git clone https://github.com/ashutoshpw/x402-vechain.git
cd x402-vechain- Install dependencies:
pnpm install- Configure environment variables:
cp .env.example .env
# Edit .env with your configuration- Start development servers:
pnpm devThis will start all applications concurrently:
- API: http://localhost:3000
- Dashboard: http://localhost:5173 (default React Router dev port)
- Web: http://localhost:4321 (default Astro dev port)
pnpm dev # Run all apps in development mode
pnpm build # Build all apps for production# API
pnpm --filter api dev # Start API dev server
pnpm --filter api build # Build API for production
pnpm --filter api db:generate # Generate database migrations
pnpm --filter api db:migrate # Run database migrations
pnpm --filter api db:push # Push schema changes to database
pnpm --filter api db:studio # Open Drizzle Studio
# Dashboard
pnpm --filter dashboard dev # Start dashboard dev server
pnpm --filter dashboard build # Build dashboard for production
# Web
pnpm --filter web dev # Start web dev server
pnpm --filter web build # Build web for production- Turbo - Monorepo build orchestration with intelligent caching
- pnpm - Fast, disk space efficient package manager
- Hono - Lightweight, fast web framework
- Drizzle ORM - TypeScript-first ORM for PostgreSQL
- Zod - TypeScript-first schema validation
- @vechain/sdk - VeChain blockchain integration
- React Router 7 (Dashboard) - Full-stack React framework
- Astro 5 (Web) - Modern static site generator
- Tailwind CSS - Utility-first CSS framework
- PostgreSQL - Relational database
- VeChain - Layer-1 blockchain platform
The API implements the x402 facilitator specification with the following endpoints:
Returns supported VeChain networks and assets.
Response:
{
"networks": [{
"network": "eip155:100009",
"assets": ["VET", "VTHO", "VEUSD", "B3TR"]
}],
"schemes": ["x402"]
}Validates payment payloads without settling on-chain.
Submits payment to VeChain and waits for confirmation.
For detailed API documentation, see apps/api/README.md.
Key environment variables (see .env.example for complete list):
# VeChain Network
VECHAIN_NETWORK=testnet # or 'mainnet'
VECHAIN_TESTNET_RPC=https://testnet.vechain.org
VECHAIN_MAINNET_RPC=https://mainnet.vechain.org
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/x402_testnet
# Fee Delegation (optional)
FEE_DELEGATION_ENABLED=false
FEE_DELEGATION_PRIVATE_KEY= # Required if enabled
# Security
JWT_SECRET= # Generate: openssl rand -base64 32
# Rate Limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=100
# Application
NODE_ENV=development
PORT=3000.env files containing secrets to version control.
The API uses PostgreSQL with Drizzle ORM. Database operations:
# Generate migration files from schema changes
pnpm --filter api db:generate
# Apply migrations to database
pnpm --filter api db:migrate
# Push schema changes directly (dev only)
pnpm --filter api db:push
# Open Drizzle Studio (database GUI)
pnpm --filter api db:studioDatabase schema is defined in apps/api/src/db/schema.ts.
Each application has its own detailed README:
- API Documentation - Complete API reference, authentication, rate limiting
- Dashboard Documentation - Dashboard features and usage
- Web Documentation - Marketing site information
Learn by example! Check out our practical integration examples:
- Minimal Server - Simple paid API endpoint (~50 lines)
- Minimal Client - Browser wallet payment integration
- AI Agent - Autonomous payment bot with retry logic
- Content Paywall - Full-stack payment-gated content platform
┌─────────────────┐
│ Marketing │
│ Website │ Astro 5
│ (apps/web) │
└─────────────────┘
┌─────────────────┐
│ Dashboard │
│ Admin Panel │ React Router 7
│ (apps/dashboard)│
└────────┬────────┘
│
│ API Calls
│
▼
┌─────────────────┐
│ x402 API │
│ Facilitator │ Hono + PostgreSQL
│ (apps/api) │
└────────┬────────┘
│
│ VeChain SDK
│
▼
┌─────────────────┐
│ VeChain │
│ Blockchain │ Testnet / Mainnet
└─────────────────┘
- Request Validation - Zod schema validation on all API inputs
- Rate Limiting - IP-based rate limiting (configurable)
- CORS - Configurable cross-origin resource sharing
- Environment Validation - Startup validation of all required environment variables
- Fee Delegation - Optional gas fee sponsorship for users
- JWT Authentication - Token-based authentication support
# Install Vercel CLI
npm install -g vercel
# Deploy
pnpm --filter api install
vc deployConfigure environment variables in the Vercel dashboard.
- x402 Protocol Specification
- VeChain Documentation
- CAIP-2 Chain Identifiers
- Hono Framework
- Drizzle ORM
- Turbo Documentation
ISC
This is a monorepo managed with pnpm and Turbo. When contributing:
- Use
pnpm installto install dependencies - Run
pnpm devto start all apps in development mode - Ensure TypeScript types are correct
- Build successfully with
pnpm build - Follow existing code style and conventions
- See .github/copilot-instructions.md for detailed development guidelines
- VET (VeChain Token)
- VTHO (VeThor Token)
- VEUSD (VeChain USD Stablecoin)
- B3TR (Better Token)
- VET (VeChain Token)
- VTHO (VeThor Token)
- VEUSD (VeChain USD Stablecoin)
- B3TR (Better Token)