# 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 ``` ## 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: ```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).