mirror of
https://github.com/exchanges-lab/tradesync.git
synced 2026-08-05 05:06:07 +08:00
0xcathiefish
bba06206ab
- Add README_CN.md as a full Chinese translation of README.md - Add a Notion Template & Preview section with the database template link, collapsible preview screenshots, and a note on the companion TradeSnap service that provides the TradingView screenshots - Add a Deployment section documenting Docker Compose (recommended) and local build - Use relative links so they resolve on GitHub - Drop the Code Example and Requirements sections and renumber Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
163 lines
8.3 KiB
Markdown
163 lines
8.3 KiB
Markdown
# 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**: <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.
|
|
|
|
<details>
|
|
<summary>🗂️ Notion database example (click to expand)</summary>
|
|
|
|
<img src="https://img.cathiefish.art/github/tradesync/tradesync1.png" width="720" alt="tradesync database example" />
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>📜 Full long screenshot of a single record page (click to expand)</summary>
|
|
|
|
<img src="https://img.cathiefish.art/github/tradesync/tradesync2.png" width="420" alt="tradesync record page example" />
|
|
|
|
</details>
|
|
|
|
|
|
> 🖼️ **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.
|
|
|
|
```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).
|