Architecture Overview
High-level system design and core components.
System Architecture
Atract is built on Hyperliquid with:
Hyperliquid L1 - Trading execution and smart contract risk management
Next.js Backend - API and oracle services
PostgreSQL - Off-chain data indexing
Architecture Diagram
┌─────────────────────────────────────────────────────────┐
│ Frontend (Next.js 15) │
│ - Trading Terminal │
│ - Vault Management │
│ - Analytics Dashboard │
└────────────────────┬────────────────────────────────────┘
│
│ API Calls
↓
┌─────────────────────────────────────────────────────────┐
│ Backend API (Next.js App Router) │
│ - /api/trade - Trade execution │
│ - /api/account - Account data │
│ - /api/vaults - Vault operations │
│ - /api/proposals - Proposal CRUD │
└──────┬──────────────────────────┬───────────────────────┘
│ │
│ Agent Signs │ Database Queries
↓ ↓
┌──────────────┐ ┌────────────────┐
│ Agent Wallet │ │ PostgreSQL │
│ (Server) │ │ (Prisma) │
└──────┬───────┘ └────────┬───────┘
│ │
│ Submit Orders │ Store Trades/Vaults
↓ │
┌─────────────────────────────────┴───────────────────────┐
│ Hyperliquid L1 │
│ - Order execution │
│ - Position management │
│ - Balance tracking │
└────────────────────┬────────────────────────────────────┘
│
│ Balance Queries (every 60s)
↓
┌─────────────────────────────────────────────────────────┐
│ Oracle Service │
│ - Poll Hyperliquid for balances │
│ - Update on-chain vaults │
│ - Trigger auto-pause if limits breached │
└────────────────────┬────────────────────────────────────┘
│
│ Update Smart Contracts
↓
┌─────────────────────────────────────────────────────────┐
│ Hyperliquid Smart Contracts (On-Chain) │
│ - VaultFactory - Deploy vaults │
│ - TraderVault - Enforce risk limits │
│ - ProposalEscrow - Manage capital (deprecated) │
└─────────────────────────────────────────────────────────┘Core Components
1. Frontend (Next.js 15 + React 19)
Pages:
/trade- Trading terminal with chart/funding- Proposal management/analytics- Performance dashboard/vaults- Vault management
Features:
Real-time price updates (WebSocket)
Agent wallet integration
Responsive design (mobile/desktop)
2. Backend API
Technology:
Next.js 15 App Router
API routes in
app/api/Server-side rendering (SSR)
Key Routes:
POST /api/trade- Execute ordersGET /api/account- Fetch account dataGET /api/vaults- List user's vaultsPOST /api/proposals- Create funding proposals
3. Database (PostgreSQL + Prisma)
Models:
Proposal- Funding offersVault- Active/closed vaultsVaultTrade- Trade audit trailVaultEvent- Critical events
Purpose:
Index on-chain data
Fast queries for UI
Audit trail storage
4. Smart Contracts (Hyperliquid)
VaultFactory:
Deploys new vaults
Tracks all vaults
Emits creation events
TraderVault:
Stores vault parameters
Enforces risk limits
Manages profit distribution
Auto-pauses on breach
5. Oracle Service
Function:
Polls Hyperliquid every 60 seconds
Fetches vault balances
Updates on-chain contracts
Triggers pause if limits breached
Implementation:
Node.js service
Runs continuously
Monitored for uptime
6. Hyperliquid Integration
Trading:
Agent wallet signs orders
Orders execute on HL L1
Fast execution (~100ms)
Low fees (~0.025%)
Balance Tracking:
Read-only API calls
No withdrawals via API
Non-custodial
Data Flow
Order Execution Flow
1. User clicks "Buy BTC" in UI
↓
2. Frontend: POST /api/trade { symbol, size, price }
↓
3. Backend:
- Authenticate user
- Verify vault status (if vault trade)
- Check balance freshness
- Validate order parameters
↓
4. Agent Wallet: Sign order action
↓
5. Hyperliquid: Execute order
↓
6. Database: Log trade in VaultTrade table
↓
7. Response: { ok: true, orderId }
↓
8. Frontend: Show confirmationOracle Update Flow
1. Oracle: Poll Hyperliquid API every 60s
↓
2. For each vault:
- Get account state (balance, positions)
- Calculate current balance
↓
3. Update Smart Contract:
- Call vault.updateBalance(newBalance)
↓
4. Smart Contract:
- Check max drawdown
- Check daily drawdown
- Auto-pause if breached
↓
5. Database: Update vault record
↓
6. Emit event: BalanceUpdatedSecurity Architecture
Key Separation:
Agent key: Server-only, signs orders
Oracle key: Server-only, updates balances
Master key: User-controlled, never shared
Non-Custodial:
Funds always on Hyperliquid (user's account)
Agent can only trade, not withdraw
Master wallet retains control
Smart Contract Safety:
Risk limits enforced on-chain
Immutable vault logic
Audited contracts
Network Configuration
Testnet:
Hyperliquid Testnet (trading + smart contracts)
PostgreSQL (local/cloud)
Mainnet: (Future)
Hyperliquid Mainnet (trading + smart contracts)
PostgreSQL (production)
Env-Based Switching:
# All networks controlled by env vars
NEXT_PUBLIC_HL_API_BASE_URL=https://api.hyperliquid-testnet.xyz
HL_RPC_URL=https://rpc.hyperliquid-testnet.xyz/evmScalability
Current Capacity:
Supports 1000+ concurrent users
Oracle handles 100+ vaults
Database can scale horizontally
Future Enhancements:
Multiple oracle instances (load balancing)
Redis caching layer
GraphQL API
Monitoring
Metrics:
API response times
Oracle update frequency
Smart contract event logs
Error rates
Alerts:
Oracle failure
Smart contract errors
API downtime
Database issues
Related Pages
Last updated