{"id":42606589,"url":"https://github.com/bemod/homeassistant-hyperliquid","last_synced_at":"2026-05-31T12:00:56.964Z","repository":{"id":335163070,"uuid":"1144574803","full_name":"beMoD/homeassistant-hyperliquid","owner":"beMoD","description":"Home Assistant custom integration for monitoring Hyperliquid trading accounts, positions, and vault deposits","archived":false,"fork":false,"pushed_at":"2026-05-13T14:03:45.000Z","size":189,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-13T16:10:02.590Z","etag":null,"topics":["cryptocurrency","hacs","home-assistant","home-assistant-integration","hyperliquid"],"latest_commit_sha":null,"homepage":null,"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/beMoD.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"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-01-28T20:14:32.000Z","updated_at":"2026-05-13T14:40:23.000Z","dependencies_parsed_at":"2026-02-09T23:00:36.826Z","dependency_job_id":null,"html_url":"https://github.com/beMoD/homeassistant-hyperliquid","commit_stats":null,"previous_names":["bemod/homeassistant-hyperliquid"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/beMoD/homeassistant-hyperliquid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beMoD%2Fhomeassistant-hyperliquid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beMoD%2Fhomeassistant-hyperliquid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beMoD%2Fhomeassistant-hyperliquid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beMoD%2Fhomeassistant-hyperliquid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beMoD","download_url":"https://codeload.github.com/beMoD/homeassistant-hyperliquid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beMoD%2Fhomeassistant-hyperliquid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33730241,"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-05-31T02:00:06.040Z","response_time":95,"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":["cryptocurrency","hacs","home-assistant","home-assistant-integration","hyperliquid"],"created_at":"2026-01-29T02:02:01.637Z","updated_at":"2026-05-31T12:00:56.951Z","avatar_url":"https://github.com/beMoD.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyperliquid Integration for Home Assistant\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs)\n[![GitHub Release](https://img.shields.io/github/release/beMoD/homeassistant-hyperliquid.svg)](https://github.com/beMoD/homeassistant-hyperliquid/releases)\n[![License](https://img.shields.io/github/license/beMoD/homeassistant-hyperliquid.svg)](https://github.com/beMoD/homeassistant-hyperliquid/blob/master/LICENSE)\n\nA Home Assistant custom integration for monitoring [Hyperliquid](https://hyperliquid.xyz) perpetual trading accounts, positions, and vault deposits in real-time.\n\n## Features\n\n### Account Monitoring\n- **Account Value** - Total portfolio value\n- **Unrealized PnL** - Sum of all open position P\u0026L\n- **Margin Used** - Currently used margin across all positions\n- **Withdrawable** - Available balance for withdrawal\n- **Total Vault Equity** - Combined equity across all vault deposits\n\n### Position Tracking (Dynamic)\nEach open perpetual position gets its own sensor showing unrealized PnL with attributes:\n- Coin/Trading Pair\n- Position Size\n- Side (Long/Short)\n- Entry Price \u0026 Mark Price\n- Liquidation Price\n- Leverage\n- Margin Used\n- Return on Equity (ROE)\n- Position Value\n\nSensors automatically appear when positions are opened and disappear when closed.\n\n### Vault Deposits (Dynamic)\nEach vault deposit gets its own sensor showing current equity with attributes:\n- Vault Name \u0026 Address\n- Profit \u0026 Loss (PnL)\n- Return on Investment (ROI)\n- Annual Percentage Rate (APR)\n- Deposit Value\n- **Leader Monitoring:**\n  - Leader Address\n  - Leader Equity (absolute USD value)\n  - Leader Fraction (% of vault TVL)\n  - Leader Commission Rate\n  - Vault Total Value (TVL)\n  - Vault Status (open/closed)\n\nThe leader monitoring attributes allow you to track if vault managers are withdrawing capital by monitoring `leader_equity` and `vault_total_value`.\n\n## Installation\n\n### HACS (Recommended)\n\n1. Open HACS in Home Assistant\n2. Go to \"Integrations\"\n3. Click the three dots in the top right corner\n4. Select \"Custom repositories\"\n5. Add this repository URL: `https://github.com/beMoD/homeassistant-hyperliquid`\n6. Select category: \"Integration\"\n7. Click \"Add\"\n8. Find \"Hyperliquid\" in the integration list and click \"Download\"\n9. Restart Home Assistant\n\n### Manual Installation\n\n1. Copy the `custom_components/hyperliquid` folder to your Home Assistant `custom_components` directory\n2. Restart Home Assistant\n\n## Configuration\n\n1. Go to **Settings → Devices \u0026 Services**\n2. Click **\"+ Add Integration\"**\n3. Search for **\"Hyperliquid\"**\n4. Enter your Ethereum wallet address (0x...)\n   - Only read-only access is used\n   - No API key or private key required\n5. Click **Submit**\n\n### Options\n\nAfter adding the integration, you can configure:\n- **Update Interval** (10-300 seconds, default: 30s) - How often to poll the Hyperliquid API\n\nTo change options:\n1. Go to **Settings → Devices \u0026 Services**\n2. Find the Hyperliquid integration\n3. Click **\"Configure\"**\n\n## Sensors\n\nAll sensors are grouped under a single device per wallet address.\n\n### Static Sensors\n\n| Sensor | Description | Unit |\n|--------|-------------|------|\n| `sensor.hyperliquid_*_account_value` | Total portfolio value | USD |\n| `sensor.hyperliquid_*_unrealized_pnl` | Sum of all position P\u0026L | USD |\n| `sensor.hyperliquid_*_margin_used` | Used margin | USD |\n| `sensor.hyperliquid_*_withdrawable` | Available balance | USD |\n| `sensor.hyperliquid_*_total_vault_equity` | Total vault equity | USD |\n\n### Dynamic Sensors (Per Position)\n\n| Sensor | Description | Unit |\n|--------|-------------|------|\n| `sensor.hyperliquid_*_position_*` | Position unrealized PnL | USD |\n\nAttributes: `coin`, `size`, `side`, `entry_price`, `mark_price`, `liquidation_price`, `leverage`, `margin_used`, `return_on_equity`, `position_value`\n\n### Dynamic Sensors (Per Vault)\n\n| Sensor | Description | Unit |\n|--------|-------------|------|\n| `sensor.hyperliquid_*_vault_*` | Vault equity value | USD |\n\nAttributes: `vault_name`, `vault_address`, `pnl`, `roi`, `deposit_value`, `apr`, `leader_address`, `leader_fraction`, `leader_equity`, `leader_commission`, `vault_total_value`, `is_closed`\n\n## Example Dashboard Card\n\n```yaml\ntype: entities\ntitle: Hyperliquid Account\nentities:\n  - entity: sensor.hyperliquid_0x1234_account_value\n    name: Portfolio Value\n  - entity: sensor.hyperliquid_0x1234_unrealized_pnl\n    name: Unrealized PnL\n  - entity: sensor.hyperliquid_0x1234_margin_used\n    name: Margin Used\n  - entity: sensor.hyperliquid_0x1234_withdrawable\n    name: Available\n  - type: divider\n  - entity: sensor.hyperliquid_0x1234_position_btc\n    name: BTC Position\n  - entity: sensor.hyperliquid_0x1234_position_eth\n    name: ETH Position\n```\n\n## Example Automation: Liquidation Alert\n\n```yaml\nalias: Hyperliquid Liquidation Alert\ndescription: Alert when position is close to liquidation\ntrigger:\n  - platform: template\n    value_template: \u003e\n      {% set position = state_attr('sensor.hyperliquid_0x1234_position_btc', 'mark_price') %}\n      {% set liq = state_attr('sensor.hyperliquid_0x1234_position_btc', 'liquidation_price') %}\n      {% set side = state_attr('sensor.hyperliquid_0x1234_position_btc', 'side') %}\n      {% if position and liq %}\n        {% if side == 'long' %}\n          {{ (position - liq) / position \u003c 0.05 }}\n        {% else %}\n          {{ (liq - position) / position \u003c 0.05 }}\n        {% endif %}\n      {% else %}\n        false\n      {% endif %}\naction:\n  - service: notify.notify\n    data:\n      title: \"⚠️ Hyperliquid Liquidation Warning\"\n      message: \"BTC position is within 5% of liquidation price!\"\n```\n\n## Example Automation: Vault Leader Withdrawal Alert\n\n```yaml\nalias: Vault Leader Withdrawal Alert\ndescription: Alert when vault leader withdraws significant capital\ntrigger:\n  - platform: numeric_state\n    entity_id: sensor.hyperliquid_0x1234_vault_myvault\n    attribute: leader_equity\n    below: 50000  # Alert if leader equity drops below $50k\naction:\n  - service: notify.notify\n    data:\n      title: \"⚠️ Vault Leader Capital Alert\"\n      message: \u003e\n        Vault leader equity has dropped to ${{ state_attr('sensor.hyperliquid_0x1234_vault_myvault', 'leader_equity') | round(2) }}\n```\n\n## Troubleshooting\n\n### Integration fails to load\n- Check Home Assistant logs: **Settings → System → Logs**\n- Ensure `hyperliquid-python-sdk` is installed correctly\n- Verify your wallet address format (must start with 0x followed by 40 hex characters)\n\n### API connection errors\n- Verify the wallet address is correct and active on Hyperliquid\n- Check if Hyperliquid API is accessible: https://api.hyperliquid.xyz/info\n- Increase the update interval if rate-limited\n\n### Sensors not updating\n- Check the last update time in the device info\n- Verify you have active positions/vault deposits (dynamic sensors only appear when data exists)\n- Check Home Assistant logs for errors\n\n## Technical Details\n\n- **API**: Hyperliquid REST API (https://api.hyperliquid.xyz)\n- **SDK**: Official `hyperliquid-python-sdk` (v0.21.0)\n- **Update Method**: Polling via `DataUpdateCoordinator`\n- **Authentication**: Read-only (wallet address only, no private key)\n- **Minimum HA Version**: 2024.1.0\n\n## Data Privacy\n\nThis integration:\n- Only uses your wallet address for read-only API access\n- Does not require or store private keys or API keys\n- All data fetching happens locally on your Home Assistant instance\n- No data is sent to third parties\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details\n\n## Disclaimer\n\nThis is an unofficial integration and is not affiliated with or endorsed by Hyperliquid. Use at your own risk. This integration is for monitoring purposes only and cannot execute trades.\n\n## Support the Project\n\nIf you find this integration useful, consider signing up on Hyperliquid using my referral link — it costs you nothing and helps support development:\nAlready have an account? Enter code **BEMOD** at [app.hyperliquid.xyz/referrals](https://app.hyperliquid.xyz/referrals) to claim the discount.\n\n**[Sign up with referral link](https://app.hyperliquid.xyz/join/BEMOD)**\n\nYou'll receive a **4% fee discount** on your first $25M in trading volume.\n\n## Support\n\n- [Report Issues](https://github.com/beMoD/homeassistant-hyperliquid/issues)\n- [Hyperliquid Documentation](https://hyperliquid.gitbook.io/hyperliquid-docs)\n- [Home Assistant Community](https://community.home-assistant.io/)\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbemod%2Fhomeassistant-hyperliquid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbemod%2Fhomeassistant-hyperliquid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbemod%2Fhomeassistant-hyperliquid/lists"}