Suren.Trade

Suren.Trade is a full-stack Web3 trading project that combines:

• a real-time trading terminal (React + TypeScript),
• a latency-focused execution backend (FastAPI + Hyperliquid Python SDK),
• and audited-style smart-contract reward infrastructure (Solidity + Foundry).

This repository is structured as a monorepo with frontend, backend, and contracts.

Suren.Trade - Full-Stack Web3 Trading Platform (React, FastAPI, Hyperliquid, Solidity, Foundry)

• Live market streaming from Hyperliquid WebSocket:
  • l2Book
  • trades
  • candle
  • activeAssetCtx
• Two main product pages:
  • Trade terminal (/)
  • Portfolio dashboard (/portfolio)
• Orderbook processing moved to a Web Worker for smoother UI under high update rates.
• Advanced charting:
  • TradingView charting library (self-hosted in frontend/public/tvcl)
  • Lightweight charts for additional analytics components.

• Core order actions:
  • Market and limit orders
  • TP/SL trigger orders
  • Pro trigger orders (stopLimit, stopMarket, takeLimit, takeMarket)
  • TWAP start/cancel
  • Modify / replace / cancel / close-all flows
• Margin controls:
  • Cross/isolated switching
  • Dynamic leverage handling
  • Local slippage and size validation before submission.

• Wallet connect/disconnect (Wagmi + injected wallets).
• EIP-712 approveAgent flow integrated into the UI.
• Deposit flow:
  • Arbitrum USDC transfer to Hyperliquid Bridge2 contract
  • Ledger polling for credit confirmation.
• Withdraw flow (withdraw3) with typed-data signing and settlement polling.
• Internal account operations:
  • Spot <-> Perps USD transfer
  • USD send to another address.

• Account value / PnL visualization.
• Balances, positions, open orders, TWAP view.
• Trade history, order history, funding history.
• Deposit/withdraw ledger history.
• User WebSocket feed (userFills, userFundings, orderUpdates) automatically invalidates/refetches account queries.

• FastAPI API with routers for:
  • /api/orders/*
  • /api/market/*
  • /api/simulate
  • /api/agent/get-or-create
  • /ws/desk
• Hyperliquid integration optimizations:
  • Monotonic nonce patch to prevent duplicate-nonce failures under concurrency
  • TTL caching for metadata and oracle contexts
  • Leverage cache per user+coin+margin-mode
  • Friendly normalization of raw Hyperliquid error codes/messages.
• Serverless entrypoint available for Vercel deployment (backend/api/index.py).

• RebateVault.sol
  • Accrue/claim reward balances
  • Owner-configurable fee/rebate parameters
  • Pausing, min-claim threshold, revenue withdrawal, emergency withdrawal.
• MultiSourceVault.sol
  • Multi-source reward accounting (Hyperliquid, Ostium, Lighter, dYdX pattern)
  • Role-based access (ADMIN_ROLE, OPERATOR_ROLE)
  • Source configs, epoch records, volume tracking, distribution, claiming.

• React 19
• TypeScript 5
• Vite 7
• TailwindCSS
• Zustand
• TanStack Query
• Wagmi + Viem
• TradingView Charting Library (self-hosted)
• lightweight-charts
• Vitest + Testing Library

• Python
• FastAPI + Uvicorn
• Pydantic v2
• hyperliquid-python-sdk
• eth-account / web3
• pytest

• Solidity 0.8.24
• Foundry (Forge/Cast)
• OpenZeppelin Contracts
• Fuzz + fork testing profiles (Arbitrum + HyperEVM)

• Monorepo setup
• Concurrent dev runner from root package.json
• Vercel config for frontend SPA rewrites and backend Python serverless routing.

flowchart LR
  U[Trader Wallet] --> F[Frontend: React Trading UI]
  F --> B[Backend: FastAPI Execution API]
  F --> HI[Hyperliquid Info API]
  F --> HE[Hyperliquid Exchange API]
  B --> HI
  B --> HE
  B --> C[Smart Contracts: RebateVault / MultiSourceVault]
  U --> C

SurenTrade/
  backend/      # FastAPI execution + market/simulate/agent/ws routes
  frontend/     # React terminal + portfolio + wallet/account flows
  contracts/    # Solidity vaults + Foundry tests + deployment scripts
  docs/         # Design/plan docs

• Node.js 20+
• Python 3.11+
• Foundry (forge, cast)

git clone https://github.com/0xsuren/Suren.Trade.git
cd Suren.Trade

# Root tools
npm install

# Frontend deps
cd frontend && npm install && cd ..

# Backend deps
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
# source .venv/bin/activate
pip install -r backend/requirements.txt

# Contracts libs (if submodules are not initialized yet)
git submodule update --init --recursive

Create backend/.env:

ENV=development
HOST=0.0.0.0
PORT=8000
USE_TESTNET=true

AGENT_PRIVATE_KEY=0x...
AGENT_ADDRESS=0x...
BUILDER_ADDRESS=0x...

# optional (defaults are 0)
BUILDER_FEE_PERP=0
BUILDER_FEE_SPOT=0

Create frontend/.env:

VITE_HL_NETWORK=testnet
VITE_BACKEND_URL=http://localhost:8000

# from repo root (runs backend + frontend together)
npm run dev

Default local ports:

• Backend: http://localhost:8000
• Frontend: http://localhost:5173

# Frontend type check
npm run test:frontend

# Contracts (Forge)
npm run test:contracts

# Backend
cd backend
pytest

# Frontend unit tests
cd ../frontend
npm test

Current test surface in repository:

• Backend: 155 pytest test functions
• Frontend: 62 test cases (Vitest)
• Contracts: 282 Solidity test functions (unit/rewards/security/fuzz/fork)

• POST /api/orders/place
• POST /api/orders/trigger
• POST /api/orders/trigger-pro
• POST /api/orders/twap
• POST /api/orders/twap-cancel
• POST /api/orders/modify
• POST /api/orders/replace
• POST /api/orders/cancel
• POST /api/orders/close-all
• GET /api/market/meta
• GET /api/market/spot-meta
• GET /api/market/all-mids
• GET /api/market/user/{address}
• POST /api/agent/get-or-create
• POST /api/simulate
• WS /ws/desk

• Built a full-stack Web3 trading platform integrating React, FastAPI, and Hyperliquid APIs for real-time trading and account operations.
• Implemented advanced execution features including market/limit orders, trigger-pro logic, TWAP execution, and full order lifecycle management.
• Improved reliability under concurrency with a monotonic nonce strategy, TTL caching, leverage-state caching, and normalized exchange error handling.
• Designed and tested Solidity reward vaults (RebateVault, MultiSourceVault) with extensive unit, fuzz, fork, and security test coverage.

UNLICENSED