init

README.md

@@ -0,0 +1,126 @@
+# Hyperliquid Wallet PnL Tracker
+
+Automatically track wallet addresses from Hyperliquid trades and sort them by highest PnL.
+
+## Features
+
+- 🔄 **Automatic Trade Tracking**: Real-time monitoring of trades on Hyperliquid
+- 💾 **MySQL Database Storage**: Persistent storage of tracked wallets
+- 📊 **PnL Sorting**: Automatically sorts wallets by highest profit/loss
+- 🚀 **REST API**: Query tracked wallets and their PnL data
+- 📈 **Historical Tracking**: Optional PnL snapshot history
+
+## Prerequisites
+
+- Node.js >= 20.16.0
+- MySQL 5.7+ or MariaDB 10.3+
+- npm or yarn
+
+## Installation
+
+1. Clone the repository and install dependencies:
+```bash
+npm install
+```
+
+2. Set up MySQL database:
+```bash
+# Create database
+mysql -u root -p < database/schema.sql
+
+# Or manually:
+# CREATE DATABASE hyperliquid_tracker;
+# USE hyperliquid_tracker;
+# source database/schema.sql;
+```
+
+3. Configure environment variables:
+```bash
+cp .env.example .env
+# Edit .env with your database credentials
+```
+
+## Environment Variables
+
+Create a `.env` file in the root directory:
+
+```env
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=your_password
+DB_NAME=hyperliquid_tracker
+PORT=3000
+```
+
+## Usage
+
+### Development
+```bash
+npm run dev
+```
+
+### Production
+```bash
+npm run build
+npm start
+```
+
+## API Endpoints
+
+### Get Tracked Wallets Sorted by PnL
+```bash
+GET /api/wallets/tracked
+```
+
+Returns all automatically tracked wallets sorted by PnL (highest first).
+
+### Get List of Tracked Wallets
+```bash
+GET /api/wallets/list
+```
+
+Returns list of all tracked wallet addresses.
+
+### Manually Add Wallets
+```bash
+POST /api/wallets/track
+Content-Type: application/json
+
+{
+  "wallets": ["0x123...", "0x456..."]
+}
+```
+
+### Query Specific Wallets PnL
+```bash
+GET /api/wallets/pnl?wallets=0x123...,0x456...
+```
+
+Or POST:
+```bash
+POST /api/wallets/pnl
+Content-Type: application/json
+
+{
+  "wallets": ["0x123...", "0x456..."]
+}
+```
+
+## Database Schema
+
+The application creates two main tables:
+
+- **wallets**: Stores tracked wallet addresses with metadata
+- **wallet_pnl_snapshots**: Optional historical PnL snapshots
+
+See `database/schema.sql` for full schema details.
+
+## Migration from JSON
+
+If you have an existing `wallets.json` file, the application will automatically migrate wallets to the database on first run. The original file will be backed up to `wallets.json.backup`.
+
+## License
+
+ISC
+