{"id":51433535,"url":"https://github.com/exchanges-lab/tradesync","last_synced_at":"2026-07-05T05:30:31.624Z","repository":{"id":361764220,"uuid":"1254231858","full_name":"exchanges-lab/tradesync","owner":"exchanges-lab","description":"A real-time monitor for Hyperliquid wallet position openings that aggregates multi-tick order fills and automatically records trades to a Notion database.","archived":false,"fork":false,"pushed_at":"2026-06-10T06:57:47.000Z","size":78,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T08:22:45.977Z","etag":null,"topics":["hyperliquid","notion","notion-database","notion-sync","rust","sync-bot"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exchanges-lab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T09:58:51.000Z","updated_at":"2026-06-10T06:57:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/exchanges-lab/tradesync","commit_stats":null,"previous_names":["exchanges-lab/nosync"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/exchanges-lab/tradesync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exchanges-lab%2Ftradesync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exchanges-lab%2Ftradesync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exchanges-lab%2Ftradesync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exchanges-lab%2Ftradesync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exchanges-lab","download_url":"https://codeload.github.com/exchanges-lab/tradesync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exchanges-lab%2Ftradesync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35144844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hyperliquid","notion","notion-database","notion-sync","rust","sync-bot"],"created_at":"2026-07-05T05:30:31.000Z","updated_at":"2026-07-05T05:30:31.615Z","avatar_url":"https://github.com/exchanges-lab.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tradesync\n\nAn efficient, decoupled Hyperliquid wallet position monitor and Notion database logger.\n\n\u003e 中文版：[README_CN.md](./README_CN.md)\n\n## 1. Introduction\n`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.\n\n## 2. Key Features\n* **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.\n* **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.\n* **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).\n* **Order Type Detection**: Auto-detects order execution types (`MARKET` for taker fills with `crossed == true`, `LIMIT` for maker fills with `crossed == false`).\n* **Robust Reconnection**: Implements a robust connection loop that automatically reconnects after network glitches or WebSocket drops.\n* **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.\n\n## 3. Notion Template \u0026 Preview\nThis 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):\n\n\u003e 📋 **Notion database template**: \u003chttps://annafish.notion.site/2026-2e08f81ac37080c6a474f00373d13287\u003e\n\nAfter duplicating, put the database ID into `NOTION_DATABASE_ID` in your `.env`, and connect your Notion integration to that page.\n\n\u003cdetails\u003e\n\u003csummary\u003e🗂️ Notion database example (click to expand)\u003c/summary\u003e\n\n\u003cimg src=\"https://img.cathiefish.art/github/tradesync/tradesync1.png\" width=\"720\" alt=\"tradesync database example\" /\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e📜 Full long screenshot of a single record page (click to expand)\u003c/summary\u003e\n\n\u003cimg src=\"https://img.cathiefish.art/github/tradesync/tradesync2.png\" width=\"420\" alt=\"tradesync record page example\" /\u003e\n\n\u003c/details\u003e\n\n\n\u003e 🖼️ **About the real-time TradingView screenshots on the record page**\n\u003e 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: \u003chttps://github.com/exchanges-lab/tradesnap\u003e). After writing to Notion, `tradesync` calls TradeSnap via `TRADESNAP_URL` to fetch the screenshots and appends them to the corresponding page.\n\u003e This is optional and controlled by `ENABLE_SCREENSHOT`; when disabled, `tradesync` only writes trade data rows and does not depend on TradeSnap.\n\n## 4. Architecture \u0026 Modules\nThe directory structure and modules are as follows:\n\n```\ntradesync/\n├── src/\n│   ├── lib.rs          # Unified module exports\n│   ├── structs.rs      # Data models and event definitions (e.g., NotionRowData)\n│   ├── hyperliquid.rs  # Hyperliquid WebSocket monitor implementation\n│   └── notion.rs       # Notion Database writer implementation\n├── examples/           # Development examples\n│   ├── demo.rs         # Real-time wallet monitoring demo\n│   └── fetch_notion_db.rs # Dev script to fetch Notion Database schema properties\n├── tests/              # Integration and unit tests\n│   └── monitor_test.rs # Monitor connectivity and reconnection loop tests\n├── references/         # Local reference submodules\n├── docker-compose.yml  # Docker Compose deployment orchestration\n├── Dockerfile          # Container image build file\n├── .env                # Local environment variables configuration (ignored by git)\n├── .env.example        # Environment configuration template\n├── Cargo.toml          # Cargo package file with remote Git dependencies\n└── CHANGELOG.md        # Change log\n```\n\n* **HyperliquidMonitor** (`src/hyperliquid.rs`): Long-running service maintaining the WebSocket connection to the Hyperliquid API and emitting aggregated trade events.\n* **NotionWriter** (`src/notion.rs`): Formats and writes the captured row data to the Notion database.\n* **structs** (`src/structs.rs`): Defines data models like `PositionTradeEvent` and `NotionRowData`.\n\n## 5. Deployment\n\n### Option 1: Docker Compose (Recommended)\nThe 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.\n\n```bash\n# Clone the repository\ngit clone https://github.com/cathiefish/tradesync.git\ncd tradesync\n\n# Copy and configure environment variables\ncp .env.example .env\n# Edit .env with your WALLET_ADDRESS, NOTION_API_KEY, NOTION_DATABASE_ID, etc.\n\n# The compose file uses an external network named \"cycle\"; create it on first deploy\ndocker network create cycle\n\n# Pull the latest image and start in the background\ndocker compose pull\ndocker compose up -d\n\n# Follow live logs\ndocker compose logs -f\n\n# Stop and remove the container\ndocker compose down\n```\n\n\u003e **Notes**\n\u003e - 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`).\n\u003e - The container is configured with `restart: unless-stopped`, so it comes back up automatically after a host reboot.\n\n### Option 2: Local Build \u0026 Run\nSuitable for development, debugging, or building your own binary:\n\n```bash\n# Clone the repository\ngit clone https://github.com/cathiefish/tradesync.git\ncd tradesync\n\n# Copy and configure environment variables\ncp .env.example .env\n# Edit the .env file with your WALLET_ADDRESS, Notion integration token, and database ID\n\n# Build the project\ncargo build --release\n\n# Run the monitoring sync service\ncargo run\n\n# Run the local monitor demo\ncargo run --example demo\n```\n\n## 6. Environment Variables\n| Variable | Description | Required | Default / Example Value |\n| :--- | :--- | :--- | :--- |\n| `WALLET_ADDRESS` | The Ethereum/Hyperliquid wallet address to monitor | **Yes** | `0xc64cc00b46101bd40aa1c3121195e85c0b0918d8` |\n| `IS_TESTNET` | Connect to Hyperliquid Testnet (`true`/`false`) | No | `true` |\n| `NOTION_API_KEY` | Notion integration token (internal secret) | **Yes** | `secret_xxxxxx...` |\n| `NOTION_DATABASE_ID` | Notion Database ID | **Yes** | `2b08f81ac37083389c5c01242f3c1557` |\n| `RUST_LOG` | Logging verbosity level (error, warn, info, debug) | No | `info` |\n| `ENABLE_SCREENSHOT` | Enable TradingView chart screenshots in Notion pages (`true`/`false`) | No | `false` |\n| `TRADESNAP_URL` | The API endpoint URL of the TradeSnap service | No | `http://tradesnap:8003` |\n| `BTCUSDT_SNAPSHOT` | Use Binance USDT perps (`true`) instead of USDC perps (`false`) for screenshots | No | `false` |\n| `SYMBOL_15M_SNAPSHOT` | Capture and insert 15m interval screenshot (`true`/`false`) | No | `false` |\n| `SYMBOL_1H_SNAPSHOT` | Capture and insert 1h interval screenshot (`true`/`false`) | No | `false` |\n| `SYMBOL_4H_SNAPSHOT` | Capture and insert 4h interval screenshot (`true`/`false`) | No | `false` |\n| `SYMBOL_1D_SNAPSHOT` | Capture and insert 1D interval screenshot (`true`/`false`) | No | `false` |\n\n\n## 7. Development \u0026 Testing\n### Git Branching Strategy\n* `dev`: Active development branch. New features and fixes are merged here first.\n* `main`: Stable production-ready branch.\n\n### Local Quality Checks\nBefore submitting pull requests, you **must** run:\n```bash\n# Auto-format codebase\ncargo fmt --all\n\n# Run lint checks\ncargo clippy --all-targets --all-features -- -D warnings\n\n# Execute test suite\ncargo test\n```\n\n## 8. Changelog\nFor a detailed log of project updates, please refer to [CHANGELOG.md](./CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexchanges-lab%2Ftradesync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexchanges-lab%2Ftradesync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexchanges-lab%2Ftradesync/lists"}