0xbennie/binance-smart-money-tracker

Binance, a cryptocurrency exchange, runs a feature called Smart Signal on its Futures trading section. This feature shows data about what large traders (called whales in the README) are doing: how many are holding long or short positions, their average entry prices, and how many of them are currently profitable. That data lives behind an internal endpoint that Binance does not expose through its official public API. This project pulls from that internal endpoint and stores the results for analysis. The tool collects 17 data fields per trading symbol, including fields unavailable through the public API: the average price at which large long and short traders entered their positions, and how many of those traders are currently in profit. The README describes these as the metrics that reveal not just which side has more open positions, but which side is actually winning at the current price. Additional data about open interest velocity and top-account ratios is collected as supplementary context. Built-in protections guard against triggering Binance rate limits. The tool reads the exact retry delay Binance sends in response headers, tracks how much of the per-minute request budget has been used, adds randomized delays between calls, applies escalating backoff after soft blocks, and maintains a process-wide circuit breaker that stops all requests when a block is detected. The README explains that retrying a blocked request immediately is the fastest way to turn a short soft block into a multi-hour ban. Data is stored in a local SQLite database with two tables and 30-day retention, and displayed in a small web dashboard. Two background jobs collect data at different intervals: the Smart Signal fields every 60 minutes, and supplementary top-trader data every 30 minutes. The project also exports functions for use as a TypeScript library in other codebases.