tradesync

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

中文版：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: https://annafish.notion.site/2026-2e08f81ac37080c6a474f00373d13287

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)

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

🖼️ 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: https://github.com/exchanges-lab/tradesnap). 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.

# 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:

# 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

6. Environment Variables

Variable	Description	Required	Default / Example Value
WALLET_ADDRESS	The Ethereum/Hyperliquid wallet address to monitor	Yes	0xc64cc00b46101bd40aa1c3121195e85c0b0918d8
IS_TESTNET	Connect to Hyperliquid Testnet (true/false)	No	true
NOTION_API_KEY	Notion integration token (internal secret)	Yes	secret_xxxxxx...
NOTION_DATABASE_ID	Notion Database ID	Yes	2b08f81ac37083389c5c01242f3c1557
RUST_LOG	Logging verbosity level (error, warn, info, debug)	No	info
ENABLE_SCREENSHOT	Enable TradingView chart screenshots in Notion pages (true/false)	No	false
TRADESNAP_URL	The API endpoint URL of the TradeSnap service	No	http://tradesnap:8003
BTCUSDT_SNAPSHOT	Use Binance USDT perps (true) instead of USDC perps (false) for screenshots	No	false
SYMBOL_15M_SNAPSHOT	Capture and insert 15m interval screenshot (true/false)	No	false
SYMBOL_1H_SNAPSHOT	Capture and insert 1h interval screenshot (true/false)	No	false
SYMBOL_4H_SNAPSHOT	Capture and insert 4h interval screenshot (true/false)	No	false
SYMBOL_1D_SNAPSHOT	Capture and insert 1D interval screenshot (true/false)	No	false

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:

# 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.