Getting Started
Prerequisites
- Node.js 18 or later
- pnpm 12 or later (recommended)
- Git
Installation
1. Clone the Repository
git clone https://github.com/Nurtoo/fact-web.git
cd fact-web2. Install Dependencies
pnpm install3. Environment Configuration
cp .env.local.example .env.localEdit .env.local and add your Privy App ID:
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here4. Start Development Server
pnpm devThe app will be available at http://localhost:3000.
Available Scripts
| Script | Description |
|---|---|
pnpm dev | Start development server on port 3000 |
pnpm build | Build for production |
pnpm start | Start production server on port 5001 |
pnpm lint | Run ESLint |
pnpm test | Run tests with Vitest |
Project Structure
fact/ ├── app/ # Next.js App Router pages │ ├── api/ # API routes │ ├── trade/ # Trading pages │ ├── sports/ # Sports betting pages │ └── page.tsx # Home page ├── components/ # React components │ ├── ui/ # shadcn/ui components │ ├── trading/ # Trading components │ └── layout/ # Layout components ├── lib/ # Libraries and utilities │ ├── hooks/ # Custom React hooks │ ├── store/ # Redux store │ └── api/ # API services └── types/ # TypeScript types
Features
Core Features
Real-time Trading
Live order books, trades, and price updates with WebSocket integration.
Interactive Charts
Professional K-line charts with multiple timeframes powered by Recharts.
Multi-Login Support
Email, Wallet, Google, Twitter authentication via Privy.
Dark/Light Mode
Seamless theme switching with system preference detection.
Internationalization
English and Chinese language support with easy extensibility.
Mobile Responsive
Optimized for all devices with touch-friendly interface.
Web3 Integration
Built with Wagmi and Viem for Ethereum interactions.
Sports Betting
Predict outcomes of live sports matches with real-time scores.
Trading Interface
- Market Orders - Execute trades at current market price
- Quick Amounts - Preset amounts for fast trading (10, 50, 100, Max)
- Position Management - Track and close your positions
- PnL Tracking - Real-time profit/loss calculations
Market Types
- Cryptocurrency - Price predictions for crypto assets
- Sports - Match outcomes and sports events
- Hot Markets - Trending and popular markets
Authentication
- Email Login - Passwordless email authentication
- Wallet Connection - MetaMask, WalletConnect, and more
- Social Login - Google, Twitter authentication
- Embedded Wallets - For non-crypto users
API Reference
Authentication API
Login
Exchange Privy token or use Email/Password for local JWT.
POST /api/v1/auth/login
Register
Register a new user (alternative to Privy flow).
POST /api/v1/auth/register
Market API
Get Active Markets
Retrieve list of active prediction markets.
GET /api/v1/markets/active
Get Market Details
Get detailed information about a specific market.
GET /api/v1/markets/:id
Order API
Create Order
Place a new order on a market.
POST /api/v1/orders
Get User Orders
Retrieve order history for the authenticated user.
GET /api/v1/orders
WebSocket API
Price Updates
Connect to real-time price updates.
wss://your-domain.com/ws/prices
Order Book Updates
Receive real-time order book updates.
wss://your-domain.com/ws/orderbook
Error Responses
All API errors follow a consistent format:
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient balance to place this order",
"details": {
"required": 100,
"available": 50
}
}
}Architecture
System Overview
Fact is built as a modern web application with the following key components:
┌────────────────────────────────────────────────────────────┐
│ Frontend (Next.js) │
├────────────────────────────────────────────────────────────┤
│ React 18 | TypeScript | Tailwind CSS | Redux Toolkit │
└────────────────────────────────────────────────────────────┘
|
v
┌────────────────────────────────────────────────────────────┐
│ API Layer (Next.js API Routes) │
├────────────────────────────────────────────────────────────┤
│ REST API | WebSocket | Authentication | Rate Limiting │
└────────────────────────────────────────────────────────────┘
|
v
┌────────────────────────────────────────────────────────────┐
│ Backend Services │
├────────────────────────────────────────────────────────────┤
│ User | Market | Order | Price | Sports │
└────────────────────────────────────────────────────────────┘
|
v
┌────────────────────────────────────────────────────────────┐
│ Data Layer │
├────────────────────────────────────────────────────────────┤
│ PostgreSQL | Redis | WebSocket (Centrifugo) │
└────────────────────────────────────────────────────────────┘Frontend Architecture
Component Structure
components/ ├── ui/ # Base UI components (shadcn/ui) ├── layout/ # Layout components (Navbar, Footer) ├── trading/ # Trading-specific components ├── market/ # Market display components ├── sports/ # Sports betting components └── web3/ # Web3 integration components
State Management
- Redux Toolkit - Global application state
- React Query - Server state management
- Local State - Component-specific state
Backend Services
| Service | Responsibility |
|---|---|
| User Service | Authentication, user management |
| Market Service | Market CRUD, resolution |
| Order Service | Order execution, position management |
| Price Service | Real-time price feeds |
| Sports Service | Sports data integration |
Authentication Flow
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ User │ │ Privy │ │ Backend │
└─────────────┘ └─────────────┘ └─────────────┘
| | |
| 1. Login Request | |
|------------------->| |
| | |
| 2. Privy Token | |
|<-------------------| |
| | |
| 3. Exchange Token | |
|--------------------------------------->|
| | |
| 4. JWT Token | |
|<--------------------------------------|
| | |
| 5. Authenticated | |
| Requests | |
|--------------------------------------->|Contributing
Development Setup
Prerequisites
- Node.js 18+
- pnpm 12+
- Git
Getting Started
- Fork the repository on GitHub
- Clone your fork:
git clone https://github.com/your-username/fact-web.git - Install dependencies:
pnpm install - Start development server:
pnpm dev
Code Style
TypeScript
- Use TypeScript for all new code
- Avoid
anytypes - Use interfaces for object shapes
React Components
- Use functional components with hooks
- Use
"use client"directive for client components - Use named exports for reusable components
Naming Conventions
| Type | Convention | Example |
|---|---|---|
| Components | PascalCase | MatchCard, TradingPanel |
| Hooks | camelCase + "use" | useSportsData, useDebounce |
| Constants | UPPER_SNAKE_CASE | PAGE_SIZE, CACHE_TIMEOUT |
Development Workflow
- Create a branch:
git checkout -b feature/your-feature-name - Make changes following code style guidelines
- Run tests:
pnpm test - Run linter:
pnpm lint - Commit changes:
git commit -m "feat: add new feature description" - Push and create PR
Commit Messages
Use Conventional Commits format:
feat:New featurefix:Bug fixdocs:Documentationstyle:Formattingrefactor:Code restructuringtest:Adding testschore:Maintenance