{"id":38440612,"url":"https://github.com/aoki-h-jp/py-liquidation-map","last_synced_at":"2026-01-17T04:34:43.181Z","repository":{"id":191617913,"uuid":"682916777","full_name":"aoki-h-jp/py-liquidation-map","owner":"aoki-h-jp","description":"Visualize Liquidation Map from actual execution data.","archived":false,"fork":false,"pushed_at":"2023-09-13T16:16:04.000Z","size":401,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2023-09-14T06:45:16.150Z","etag":null,"topics":["cryptocurrency","liquidation","liquidation-map"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aoki-h-jp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-25T06:57:54.000Z","updated_at":"2023-09-14T06:45:16.150Z","dependencies_parsed_at":"2023-08-30T18:36:59.671Z","dependency_job_id":null,"html_url":"https://github.com/aoki-h-jp/py-liquidation-map","commit_stats":null,"previous_names":["aoki-h-jp/py-liquidation-map"],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/aoki-h-jp/py-liquidation-map","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoki-h-jp%2Fpy-liquidation-map","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoki-h-jp%2Fpy-liquidation-map/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoki-h-jp%2Fpy-liquidation-map/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoki-h-jp%2Fpy-liquidation-map/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aoki-h-jp","download_url":"https://codeload.github.com/aoki-h-jp/py-liquidation-map/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoki-h-jp%2Fpy-liquidation-map/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28495200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cryptocurrency","liquidation","liquidation-map"],"created_at":"2026-01-17T04:34:43.099Z","updated_at":"2026-01-17T04:34:43.167Z","avatar_url":"https://github.com/aoki-h-jp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110//)\n[![Format code](https://github.com/aoki-h-jp/py-liquidation-map/actions/workflows/Formatter.yml/badge.svg)](https://github.com/aoki-h-jp/py-liquidation-map/actions/workflows/Formatter.yml)\n\n# py-liquidation-map\nVisualize Liquidation Map from actual execution data. Supports for all historical data from binance and bybit. Receiving orders in real-time via websocket and drawing liquidation maps is being implemented.\n\n## How to Understand a Liquidation Map\nA liquidation map, also known as a \"liq map,\" provides a visual chart of liquidations or liquidation risk in the futures cryptocurrency trading market. It displays liquidations that are predicted based on previous price trends.\n\nWhen traders engage in trading on unregulated cryptocurrency derivative exchanges, they are constantly exposed to additional risks, namely liquidation risks. When the liquidation price of a trader's position is triggered, their position is forcibly closed by the exchange's risk engine.\n\nThe impact on the market is relatively small when a small number of positions are liquidated. However, if thousands of positions with similar liquidation prices are liquidated, the effect on the market price can be significant. Moreover, market buy and sell orders triggered by liquidations can cause rapid price movements, leading to a \"cascading effect\" where more nearby positions get liquidated. This phenomenon creates substantial price fluctuations (which institutional players often take advantage of as an entry strategy since the rapid injection of liquidity within a short period can meet the demand for institutional large orders).\n\nDifferent combinations of leverage and time frames depict various clusters of liquidations. The denser and higher the liquidation clusters, the greater their impact on price behavior when reached.\n\n## Installation\n\n```bash\npip install git+https://github.com/aoki-h-jp/py-liquidation-map\n```\n\n## Usage\n### Visualize liquidation map from historical data\nDownload binance BTCUSDT data from start_datetime to end_datetime and draw a liquidation map calculated from orders above threshold=100000 [USDT].\n```python\nfrom liqmap.mapping import HistoricalMapping\n\nmapping = HistoricalMapping(\n    start_datetime='2023-08-01 00:00:00',\n    end_datetime='2023-08-01 06:00:00',\n    symbol='BTCUSDT',\n    exchange='binance',\n)\n\nmapping.liquidation_map_from_historical(\n    mode=\"gross_value\",\n    threshold_gross_value=100000\n)\n```\n### Output\n![BTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_gross_value_100000.png](img%2FBTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_gross_value_100000.png)\n\n### Visualize liquidation map depth\n```python\nfrom liqmap.mapping import HistoricalMapping\n\nmapping = HistoricalMapping(\n    start_datetime='2023-08-01 00:00:00',\n    end_datetime='2023-08-01 06:00:00',\n    symbol='BTCUSDT',\n    exchange='binance',\n)\n\nmapping.liquidation_map_depth_from_historical(\n    mode=\"gross_value\",\n    threshold_gross_value=100000\n)\n```\n\n### Output\n![BTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_gross_value_100000_depth.png](img%2FBTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_gross_value_100000_depth.png)\n\n## Examples\n### top_n mode\nmode=\"top_n\": draw liquidation map from top n trades.\n\nthreshold_top_n=100 means draw liquidation map from top 100 large trades.\n\n```python\nfrom liqmap.mapping import HistoricalMapping\n\nmapping = HistoricalMapping(\n    start_datetime='2023-08-01 00:00:00',\n    end_datetime='2023-08-01 06:00:00',\n    symbol='BTCUSDT',\n    exchange='binance',\n)\n\nmapping.liquidation_map_from_historical(\n    mode=\"top_n\",\n    threshold_top_n=100\n)\n\nmapping.liquidation_map_depth_from_historical(\n    mode=\"top_n\",\n    threshold_top_n=100\n)\n```\n![BTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_top_n_100.png](img%2FBTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_top_n_100.png)\n![BTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_top_n_100_depth.png](img%2FBTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_top_n_100_depth.png)\n\n### portion mode\nmode=\"portion\": draw liquidation map from top n% trades.\n\nthreshold_portion=0.01 means draw liquidation map from top 1% large trades.\n\n```python\nfrom liqmap.mapping import HistoricalMapping\n\nmapping = HistoricalMapping(\n    start_datetime='2023-08-01 00:00:00',\n    end_datetime='2023-08-01 06:00:00',\n    symbol='BTCUSDT',\n    exchange='binance',\n)\n\nmapping.liquidation_map_from_historical(\n    mode=\"portion\",\n    threshold_portion=0.01\n)\n\nmapping.liquidation_map_depth_from_historical(\n    mode=\"portion\",\n    threshold_portion=0.01\n)\n```\n![BTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_portion_0.01.png](img%2FBTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_portion_0.01.png)\n![BTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_portion_0.01_depth.png](img%2FBTCUSDT_2023-08-01_00-00-00-2023-08-01_06-00-00_portion_0.01_depth.png)\n\n## If you want to report a bug or request a feature\nPlease create an issue on this repository!\n\n## Disclaimer\nThis project is for educational purposes only. You should not construe any such information or other material as legal, tax, investment, financial, or other advice. Nothing contained here constitutes a solicitation, recommendation, endorsement, or offer by me or any third party service provider to buy or sell any securities or other financial instruments in this or in any other jurisdiction in which such solicitation or offer would be unlawful under the securities laws of such jurisdiction.\n\nUnder no circumstances will I be held responsible or liable in any way for any claims, damages, losses, expenses, costs, or liabilities whatsoever, including, without limitation, any direct or indirect damages for loss of profits.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faoki-h-jp%2Fpy-liquidation-map","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faoki-h-jp%2Fpy-liquidation-map","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faoki-h-jp%2Fpy-liquidation-map/lists"}