https://github.com/exchanges-lab/tradesync

A real-time monitor for Hyperliquid wallet position openings that aggregates multi-tick order fills and automatically records trades to a Notion database.
https://github.com/exchanges-lab/tradesync

hyperliquid notion notion-database notion-sync rust sync-bot

Last synced: 18 days ago
JSON representation

A real-time monitor for Hyperliquid wallet position openings that aggregates multi-tick order fills and automatically records trades to a Notion database.

Host: GitHub
URL: https://github.com/exchanges-lab/tradesync
Owner: exchanges-lab
Created: 2026-05-30T09:58:51.000Z (about 2 months ago)
Default Branch: main
Last Pushed: 2026-06-10T06:57:47.000Z (about 1 month ago)
Last Synced: 2026-06-10T08:22:45.977Z (about 1 month ago)
Topics: hyperliquid, notion, notion-database, notion-sync, rust, sync-bot
Language: Rust
Homepage:
Size: 76.2 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md

Awesome Lists containing this project

README

# tradesync

An efficient, decoupled Hyperliquid wallet position monitor and Notion database logger.

> 中文版：[README_CN.md](./README_CN.md)

## 1. Introduction
`tradesync` is a real-time wallet position monitoring and analysis tool built with Rust. It subscribes to a specified Hyperliquid wallet address via WebSockets, captures position-opening trades in real-time, aggregates multi-tick partial fills of a single order (using a 500ms debounce aggregation mechanism), and automatically synchronizes the formatted trade data to a Notion database.

## 2. Key Features
* **Real-time Wallet Subscription**: Uses `hyperliquid-rust-sdk` to establish a persistent WebSocket connection to the wallet's `UserEvents`, sensing position changes at millisecond latency.
* **Aggregated Fills via `oid`**: Aggregates multi-tick partial fills belonging to the same order (`oid`) within a 500ms window into a single unified row, preventing split trades from generating duplicate database entries.
* **Opening Event Capture**: Identifies position opening actions by validating if the starting position (`start_position`) is zero. Currently captures only opening positions (ignores closes to prevent tick-splitting complexity).
* **Order Type Detection**: Auto-detects order execution types (`MARKET` for taker fills with `crossed == true`, `LIMIT` for maker fills with `crossed == false`).
* **Robust Reconnection**: Implements a robust connection loop that automatically reconnects after network glitches or WebSocket drops.
* **Notion Integration**: Integrates `notion-client` API to write structured rows (`Symbol`, `Quantity`, `Filled Price`, `Direction`, `Exchange`, `DataTime`, `Order ID`, `Order Type`, `Check`) directly to a target Notion database.

## 3. Notion Template & Preview
This project writes data into a Notion database, so you first need a database whose schema matches the expected fields. You can duplicate the official template directly (click **Duplicate** in the top-right corner to copy it into your own workspace):

> 📋 **Notion database template**:

After duplicating, put the database ID into `NOTION_DATABASE_ID` in your `.env`, and connect your Notion integration to that page.

🗂️ Notion database example (click to expand)

tradesync database example

📜 Full long screenshot of a single record page (click to expand)

tradesync record page example

> 🖼️ **About the real-time TradingView screenshots on the record page**
> The multi-timeframe (15m / 1h / 4h / 1D) real-time TradingView screenshots on each record page are **not** generated by `tradesync` itself, but by a companion service called **TradeSnap** (separate repo: ). After writing to Notion, `tradesync` calls TradeSnap via `TRADESNAP_URL` to fetch the screenshots and appends them to the corresponding page.
> This is optional and controlled by `ENABLE_SCREENSHOT`; when disabled, `tradesync` only writes trade data rows and does not depend on TradeSnap.

## 4. Architecture & Modules
The directory structure and modules are as follows:

```
tradesync/
├── src/
│ ├── lib.rs # Unified module exports
│ ├── structs.rs # Data models and event definitions (e.g., NotionRowData)
│ ├── hyperliquid.rs # Hyperliquid WebSocket monitor implementation
│ └── notion.rs # Notion Database writer implementation
├── examples/ # Development examples
│ ├── demo.rs # Real-time wallet monitoring demo
│ └── fetch_notion_db.rs # Dev script to fetch Notion Database schema properties
├── tests/ # Integration and unit tests
│ └── monitor_test.rs # Monitor connectivity and reconnection loop tests
├── references/ # Local reference submodules
├── docker-compose.yml # Docker Compose deployment orchestration
├── Dockerfile # Container image build file
├── .env # Local environment variables configuration (ignored by git)
├── .env.example # Environment configuration template
├── Cargo.toml # Cargo package file with remote Git dependencies
└── CHANGELOG.md # Change log
```

* **HyperliquidMonitor** (`src/hyperliquid.rs`): Long-running service maintaining the WebSocket connection to the Hyperliquid API and emitting aggregated trade events.
* **NotionWriter** (`src/notion.rs`): Formats and writes the captured row data to the Notion database.
* **structs** (`src/structs.rs`): Defines data models like `PositionTradeEvent` and `NotionRowData`.

## 5. Deployment

### Option 1: Docker Compose (Recommended)
The project ships a `docker-compose.yml` that pulls the prebuilt image `ghcr.io/exchanges-lab/tradesync:latest` and runs it directly — no local Rust toolchain required.

```bash
# Clone the repository
git clone https://github.com/cathiefish/tradesync.git
cd tradesync

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your WALLET_ADDRESS, NOTION_API_KEY, NOTION_DATABASE_ID, etc.

# The compose file uses an external network named "cycle"; create it on first deploy
docker network create cycle

# Pull the latest image and start in the background
docker compose pull
docker compose up -d

# Follow live logs
docker compose logs -f

# Stop and remove the container
docker compose down
```

> **Notes**
> - The service in `docker-compose.yml` joins the external network `cycle` so it can communicate with other services on the same network (e.g., the screenshot service `tradesnap`). If you enable screenshots, set `TRADESNAP_URL` to an address reachable within that network (default `http://tradesnap:8003`).
> - The container is configured with `restart: unless-stopped`, so it comes back up automatically after a host reboot.

### Option 2: Local Build & Run
Suitable for development, debugging, or building your own binary:

```bash
# Clone the repository
git clone https://github.com/cathiefish/tradesync.git
cd tradesync

# Copy and configure environment variables
cp .env.example .env
# Edit the .env file with your WALLET_ADDRESS, Notion integration token, and database ID

# Build the project
cargo build --release

# Run the monitoring sync service
cargo run

# Run the local monitor demo
cargo run --example demo
```

## 7. Development & Testing
### Git Branching Strategy
* `dev`: Active development branch. New features and fixes are merged here first.
* `main`: Stable production-ready branch.

### Local Quality Checks
Before submitting pull requests, you **must** run:
```bash
# Auto-format codebase
cargo fmt --all

# Run lint checks
cargo clippy --all-targets --all-features -- -D warnings

# Execute test suite
cargo test
```

## 8. Changelog
For a detailed log of project updates, please refer to [CHANGELOG.md](./CHANGELOG.md).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/exchanges-lab/tradesync

Awesome Lists containing this project

README