{"id":36939813,"url":"https://github.com/alfwro13/ghostfolio_ha_integration","last_synced_at":"2026-05-01T08:06:49.976Z","repository":{"id":326517140,"uuid":"1105987003","full_name":"alfwro13/ghostfolio_ha_integration","owner":"alfwro13","description":"Home Assistant custom integration for monitoring Ghostfolio portfolio performance.","archived":false,"fork":false,"pushed_at":"2026-04-26T09:28:45.000Z","size":305,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-26T09:28:49.246Z","etag":null,"topics":["ghostfolio","ghostfolio-plugin","hacs","hacs-integration","home-assistant","home-assistant-integration"],"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/alfwro13.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,"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":"2025-11-28T12:58:36.000Z","updated_at":"2026-04-24T10:14:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alfwro13/ghostfolio_ha_integration","commit_stats":null,"previous_names":["alfwro13/ghostfolio-ha-integration"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/alfwro13/ghostfolio_ha_integration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfwro13%2Fghostfolio_ha_integration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfwro13%2Fghostfolio_ha_integration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfwro13%2Fghostfolio_ha_integration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfwro13%2Fghostfolio_ha_integration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alfwro13","download_url":"https://codeload.github.com/alfwro13/ghostfolio_ha_integration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfwro13%2Fghostfolio_ha_integration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32292958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: 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":["ghostfolio","ghostfolio-plugin","hacs","hacs-integration","home-assistant","home-assistant-integration"],"created_at":"2026-01-13T10:32:22.494Z","updated_at":"2026-04-26T10:01:10.110Z","avatar_url":"https://github.com/alfwro13.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n   \u003cimg src=\"https://brands.home-assistant.io/ghostfolio/icon.png\" alt=\"Ghostfolio Logo\" width=\"120\" height=\"120\"\u003e\n\u003c/div\u003e\n\n# Ghostfolio Home Assistant Integration\n\nA Home Assistant Custom Component (HACS integration) for monitoring your [Ghostfolio](https://github.com/ghostfolio/ghostfolio) portfolio performance. This integration works with any Ghostfolio instance, but if you prefer an all-in-one solution, you can run Ghostfolio directly on your server using the [Home Assistant Add-on](https://github.com/alfwro13/ha-addon-ghostfolio).\n\n## Features\n\nThis integration automatically detects your portfolio's base currency and offers granular tracking options:\n- **Global Totals:** Track overall portfolio value and performance.\n- **Account Breakdowns:** Individual sensors for each investment account.\n- **Asset Tracking:** Dedicated sensors for every holding and watchlist item.\n- **Price Alerts:** Configurable High/Low limit numbers for every asset to trigger automations.\n- **Diagnostic Sensors:** Monitor the connection status of your Ghostfolio server and its data providers.\n- **Smart Health Checks:** Automatically detects if a data provider (e.g., Yahoo Finance) is down and marks affected sensors as `Unknown` instead of reporting erroneous zero values.\n- **Entity Cleanup:** Built-in tool to remove old or sold assets from Home Assistant.\n\n### 1. Global Portfolio Sensors\n- **Portfolio Value**: The current total market value of your portfolio.\n- **Portfolio Cost**: The total amount of money you have invested.\n- **Portfolio Gain**: The absolute net performance (Value - Cost).\n- **Portfolio Gain FX**: The absolute net performance including currency effects.\n- **Simple Gain %**: The simple percentage return, calculated as `(Value - Cost) / Cost`.\n- **Time-Weighted Return %**: The Time-Weighted Rate of Return (TWR) of your portfolio (measures strategy performance, ignoring deposits/withdrawals).\n- **Time-Weighted Return FX %**: The TWR percentage including currency effects.\n\n*Note: If any active holding in your portfolio relies on a data provider that is currently down, these global summary sensors will report `Unknown` to prevent misleading data.*\n\n### 2. Per-Account Sensors\nSensors are created for each of your Ghostfolio accounts (excluding hidden ones):\n- **[Account Name] Value**: Current market value of the specific account.\n- **[Account Name] Cost**: Total investment in the specific account.\n- **[Account Name] Gain**: Absolute gain/loss for the specific account.\n- **[Account Name] Simple Gain %**: Simple percentage gain/loss for the specific account.\n- **[Account Name] Time-Weighted Return %**: Time-Weighted Return percentage for the specific account.\n\n### 2. Per-Account Sensors\nSensors are created for each of your Ghostfolio accounts (excluding hidden ones):\n- **[Account Name] Value**: Current market value of the specific account.\n- **[Account Name] Cost**: Total investment in the specific account.\n- **[Account Name] Gain**: Absolute gain/loss for the specific account.\n- **[Account Name] Simple Gain %**: Simple percentage gain/loss for the specific account.\n- **[Account Name] Time-Weighted Return %**: Time-Weighted Return percentage for the specific account.\n\n### 3. Per-Holding Sensors (Assets)\nTrack every individual asset in your portfolio with a dedicated sensor:\n- **Sensor State**: Total market value of the holding in your base currency.\n- **Friendly Name**: The ticker symbol (e.g., \"AAPL\", \"VWRL.AS\").\n- **Attributes**: \n  - `market_price`, `average_buy_price`, `number_of_shares`\n  - `gain_value`, `gain_pct`, `trend_vs_buy`\n  - `low_limit_set`, `low_limit_reached`\n  - `high_limit_set`, `high_limit_reached`\n\n*Note: If the data provider for a specific holding is down, its sensor will report `Unknown`.*\n\n### 4. Watchlist Sensors\nTrack items from your Ghostfolio Watchlist even if you don't own them yet.\n- **Sensor State**: Current market price.\n- **Friendly Name**: The ticker symbol (e.g., \"TSLA\").\n- **Attributes**: \n  - `market_change_24h`, `market_change_pct_24h`\n  - `trend_50d`, `trend_200d`\n  - `low_limit_set`, `low_limit_reached`\n  - `high_limit_set`, `high_limit_reached`\n*(Requires \"Show Watchlist Items\" to be enabled in configuration)*\n\n### 5. Price Limit Configuration (Inputs)\nFor every Holding and Watchlist item, the integration creates two **Number** entities that allow you to set price targets directly from Home Assistant.\n\n- **[Ticker] - Low Limit**\n- **[Ticker] - High Limit**\n\nWhen you set a value in these number entities, the corresponding main Sensor (Holding or Watchlist) immediately updates its attributes:\n- **`low_limit_set` / `high_limit_set`**: Displays the limit value you set (or `false` if not set).\n- **`low_limit_reached`**: Becomes `true` if the value drops to or below your limit.\n- **`high_limit_reached`**: Becomes `true` if the value rises to or above your limit.\n\n### 6. Automations \u0026 Alerts (Recommended)\nThis integration features a built-in event system to handle price alerts efficiently. Instead of creating complex automations that watch every single sensor state, the integration fires a **single event** whenever a limit is crossed.\n\n**Event Name:** `ghostfolio_limit_alert`\n\n**Example Automation:**\nThis single automation will notify you about **ANY** asset (Holding or Watchlist) that crosses a High or Low limit.\n\n```yaml\nalias: \"Ghostfolio - Limit Notification\"\ndescription: \"Sends a notification when any Ghostfolio asset crosses a limit.\"\ntrigger:\n  - platform: event\n    event_type: ghostfolio_limit_alert\naction:\n  - service: notify.mobile_app\n    data:\n      title: \"Price Alert: {{ trigger.event.data.ticker }}\"\n      message: \u003e-\n        {{ trigger.event.data.ticker }} has hit the {{ trigger.event.data.limit_type }} limit of \n        {{ trigger.event.data.limit_value }} {{ trigger.event.data.currency }}.\n        \n        Current Price: {{ \"%.2f\" | format(trigger.event.data.current_value) }} {{ trigger.event.data.currency }}\nmode: parallel\n```\n**Event Data Payload**: The event provides the following data variables you can use in your templates:\n- ticker: The symbol (e.g., \"AAPL\")\n- account: The account name or \"Watchlist\"\n- limit_type: \"low\" or \"high\"\n- limit_value: The threshold value that was set\n- current_value: The price that triggered the alert\n- currency: The currency code (e.g., \"USD\", \"GBP\")\n\n### 7. Diagnostic Sensors \u0026 Tools\nTo help you troubleshoot issues and maintain your setup, the integration provides diagnostic entities. You can find these on the main Portfolio Device page in Home Assistant.\n\n- **Ghostfolio Server**: Indicates if your Ghostfolio instance is reachable (`Connected` / `Disconnected`).\n- **Data Provider Status**: Individual sensors for each data provider (e.g., `Yahoo Status`, `Coingecko Status`) showing if they are `Available` or `Unavailable`.\n- **Prune Orphaned Entities**: A button that, when pressed, scans your Home Assistant registry and removes any Ghostfolio entities (such as sold assets or removed watchlist items) that are no longer returned by the API.\n\n## Installation\n\n### HACS (Recommended)\n\n1. Make sure you have [HACS](https://hacs.xyz/) installed.\n2. Add this repository as a custom repository in HACS:\n   - Go to HACS → Integrations.\n   - Click the three dots in the top right corner.\n   - Select \"Custom repositories\".\n   - Add this repository URL and select \"Integration\" as the category.\n3. Install the integration from HACS.\n4. Restart Home Assistant.\n\n### Manual Installation\n\n1. Download the latest release.\n2. Copy the `custom_components/ghostfolio` folder to your Home Assistant `custom_components` directory.\n3. Restart Home Assistant.\n\n## Configuration\n\n1. Go to **Settings → Devices \u0026 Services**.\n2. Click **Add Integration** and search for **\"Ghostfolio\"**.\n3. Enter your details and choose which sensors to create:\n   - **Base URL**: The URL of your Ghostfolio instance (e.g., `https://your-ghostfolio.com`).\n   - **Access Token**: Your Ghostfolio access token.\n   - **Show Portfolio Totals**: (Optional) Check to create global portfolio sensors.\n   - **Show Individual Accounts**: (Optional) Check to create sensors for each account.\n   - **Show Holdings**: (Optional) Check to create sensors and limit numbers for individual assets.\n   - **Show Watchlist Items**: (Optional) Check to create sensors and limit numbers for watchlist items.\n\n### Getting Your Access Token\n\n1. Log in to your Ghostfolio instance.\n2. Go to **Settings \u003e Security**.\n3. Scroll to **Security Token**.\n4. Generate or copy your access token (Anonymous Access).\n\n## API Endpoints Used\n\nThis integration uses the following Ghostfolio API endpoints:\n\n- `POST /api/v1/auth/anonymous`: For authentication.\n- `GET /api/v1/account`: For retrieving the account list and base currency settings.\n- `GET /api/v2/portfolio/performance`: For retrieving global and per-account performance data.\n- `GET /api/v1/portfolio/holdings`: For retrieving individual asset details.\n- `GET /api/v1/watchlist`: For retrieving watchlist items.\n- `GET /api/v1/market-data`: For fetching real-time price and history for watchlist items.\n- `GET /api/v1/health/data-provider/{provider}`: For checking the status of data providers.\n\n## Data Update Frequency\n\nThe integration updates portfolio data every **15 minutes** by default. This can be customized in the configuration options.\n\n## Support\n\nFor issues with this integration, please open an issue on the GitHub repository.\n\nFor issues with Ghostfolio itself, please refer to the [Ghostfolio GitHub repository](https://github.com/ghostfolio/ghostfolio).\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\nThis integration is maintained by @alfwro13.\nOriginally based on the [ha_ghostfolio repository by MichelFR](https://github.com/MichelFR/ha_ghostfolio). It has since been significantly expanded to include granular per-holding tracking, per-account sensors, dynamic configuration options, diagnostic tools, and improved currency handling.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfwro13%2Fghostfolio_ha_integration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falfwro13%2Fghostfolio_ha_integration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfwro13%2Fghostfolio_ha_integration/lists"}