# Solana Swap Flow

Real-time Solana DEX swap flow visualization dashboard. Displays a force-directed network graph showing where volume is moving, what tokens are gaining traction, and swap density across Solana DEXes.

- **Green** = net inflow (more buys)
- **Red** = net outflow (more sells)
- **Line weight** = swap density
- **Bubble size** = trading volume

Powered by [Helius](https://helius.dev) WebSocket + Enhanced Transactions API.

## Features

- Real-time force-directed graph with SOL as center hub
- Top 100 tokens by trading volume displayed
- Top 30 trading pairs sorted by volume
- Multi-timeframe: 5 min / 30 min / 1 hour / 12 hours / 24 hours
- AMM filter: Pump / Raydium / Meteora / Orca / Jupiter
- SQLite persistence with 24-hour data retention
- Token metadata resolution via Helius DAS API
- Click token for details (price, supply, market cap, inflow/outflow)
- Drag, zoom, pan interactions
- Auto-reconnect WebSocket with heartbeat monitoring

## Prerequisites

- Node.js 18+
- [Helius API Key](https://dev.helius.xyz) (free tier works)

## Quick Start

```bash
# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local and set your HELIUS_API_KEY

# Start development server
npm run dev
```

Open [http://localhost:3000](http://localhost:3000).

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `HELIUS_API_KEY` | Yes | Helius API key for Solana RPC, WebSocket, and token metadata |

Create a `.env.local` file:

```
HELIUS_API_KEY=your_helius_api_key_here
```

## Docker

```bash
# Build and run
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down
```

The SQLite database is persisted in a Docker volume (`solana-flow-data`).

## Tech Stack

| Technology | Purpose |
|---|---|
| Next.js 16 (App Router) | Framework |
| D3.js + Canvas | Force-directed graph rendering |
| Tailwind CSS v4 | Styling |
| Zustand | Client state |
| better-sqlite3 | Persistent storage (24h) |
| ws | WebSocket client |

## Architecture

```
Helius WebSocket (logsSubscribe x 9 DEX programs)
  -> Batch parse signatures (3x100 every 1.5s)
  -> SwapEvent extraction
  -> SSE stream to browser + SQLite persistence
  -> Zustand store -> D3 force graph (Canvas)
```

## Data Sources

- **Real-time swaps**: Standard Solana WebSocket `logsSubscribe` with DEX program mentions, parsed via Helius Enhanced Transactions API
- **Token metadata**: Helius DAS API `getAsset` with LRU cache
- **No Enhanced WebSocket required** (works on Helius free/developer plan)

## License

MIT