# 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