Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/alfwro13/ghostfolio_ha_integration

Home Assistant custom integration for monitoring Ghostfolio portfolio performance.
https://github.com/alfwro13/ghostfolio_ha_integration

ghostfolio ghostfolio-plugin hacs hacs-integration home-assistant home-assistant-integration

Last synced: about 1 month ago
JSON representation

Home Assistant custom integration for monitoring Ghostfolio portfolio performance.

Awesome Lists containing this project

README 

          


   Ghostfolio Logo




# Ghostfolio Home Assistant Integration



A 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).



## Features



This integration automatically detects your portfolio's base currency and offers granular tracking options:

- **Global Totals:** Track overall portfolio value and performance.

- **Account Breakdowns:** Individual sensors for each investment account.

- **Asset Tracking:** Dedicated sensors for every holding and watchlist item.

- **Price Alerts:** Configurable High/Low limit numbers for every asset to trigger automations.

- **Diagnostic Sensors:** Monitor the connection status of your Ghostfolio server and its data providers.

- **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.

- **Entity Cleanup:** Built-in tool to remove old or sold assets from Home Assistant.



### 1. Global Portfolio Sensors

- **Portfolio Value**: The current total market value of your portfolio.

- **Portfolio Cost**: The total amount of money you have invested.

- **Portfolio Gain**: The absolute net performance (Value - Cost).

- **Portfolio Gain FX**: The absolute net performance including currency effects.

- **Simple Gain %**: The simple percentage return, calculated as `(Value - Cost) / Cost`.

- **Time-Weighted Return %**: The Time-Weighted Rate of Return (TWR) of your portfolio (measures strategy performance, ignoring deposits/withdrawals).

- **Time-Weighted Return FX %**: The TWR percentage including currency effects.



*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.*



### 2. Per-Account Sensors

Sensors are created for each of your Ghostfolio accounts (excluding hidden ones):

- **[Account Name] Value**: Current market value of the specific account.

- **[Account Name] Cost**: Total investment in the specific account.

- **[Account Name] Gain**: Absolute gain/loss for the specific account.

- **[Account Name] Simple Gain %**: Simple percentage gain/loss for the specific account.

- **[Account Name] Time-Weighted Return %**: Time-Weighted Return percentage for the specific account.



### 2. Per-Account Sensors

Sensors are created for each of your Ghostfolio accounts (excluding hidden ones):

- **[Account Name] Value**: Current market value of the specific account.

- **[Account Name] Cost**: Total investment in the specific account.

- **[Account Name] Gain**: Absolute gain/loss for the specific account.

- **[Account Name] Simple Gain %**: Simple percentage gain/loss for the specific account.

- **[Account Name] Time-Weighted Return %**: Time-Weighted Return percentage for the specific account.



### 3. Per-Holding Sensors (Assets)

Track every individual asset in your portfolio with a dedicated sensor:

- **Sensor State**: Total market value of the holding in your base currency.

- **Friendly Name**: The ticker symbol (e.g., "AAPL", "VWRL.AS").

- **Attributes**: 

  - `market_price`, `average_buy_price`, `number_of_shares`

  - `gain_value`, `gain_pct`, `trend_vs_buy`

  - `low_limit_set`, `low_limit_reached`

  - `high_limit_set`, `high_limit_reached`



*Note: If the data provider for a specific holding is down, its sensor will report `Unknown`.*



### 4. Watchlist Sensors

Track items from your Ghostfolio Watchlist even if you don't own them yet.

- **Sensor State**: Current market price.

- **Friendly Name**: The ticker symbol (e.g., "TSLA").

- **Attributes**: 

  - `market_change_24h`, `market_change_pct_24h`

  - `trend_50d`, `trend_200d`

  - `low_limit_set`, `low_limit_reached`

  - `high_limit_set`, `high_limit_reached`

*(Requires "Show Watchlist Items" to be enabled in configuration)*



### 5. Price Limit Configuration (Inputs)

For every Holding and Watchlist item, the integration creates two **Number** entities that allow you to set price targets directly from Home Assistant.



- **[Ticker] - Low Limit**

- **[Ticker] - High Limit**



When you set a value in these number entities, the corresponding main Sensor (Holding or Watchlist) immediately updates its attributes:

- **`low_limit_set` / `high_limit_set`**: Displays the limit value you set (or `false` if not set).

- **`low_limit_reached`**: Becomes `true` if the value drops to or below your limit.

- **`high_limit_reached`**: Becomes `true` if the value rises to or above your limit.



### 6. Automations & Alerts (Recommended)

This 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.



**Event Name:** `ghostfolio_limit_alert`



**Example Automation:**

This single automation will notify you about **ANY** asset (Holding or Watchlist) that crosses a High or Low limit.



```yaml

alias: "Ghostfolio - Limit Notification"

description: "Sends a notification when any Ghostfolio asset crosses a limit."

trigger:

  - platform: event

    event_type: ghostfolio_limit_alert

action:

  - service: notify.mobile_app

    data:

      title: "Price Alert: {{ trigger.event.data.ticker }}"

      message: >-

        {{ trigger.event.data.ticker }} has hit the {{ trigger.event.data.limit_type }} limit of 

        {{ trigger.event.data.limit_value }} {{ trigger.event.data.currency }}.

        

        Current Price: {{ "%.2f" | format(trigger.event.data.current_value) }} {{ trigger.event.data.currency }}

mode: parallel

```

**Event Data Payload**: The event provides the following data variables you can use in your templates:

- ticker: The symbol (e.g., "AAPL")

- account: The account name or "Watchlist"

- limit_type: "low" or "high"

- limit_value: The threshold value that was set

- current_value: The price that triggered the alert

- currency: The currency code (e.g., "USD", "GBP")



### 7. Diagnostic Sensors & Tools

To 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.



- **Ghostfolio Server**: Indicates if your Ghostfolio instance is reachable (`Connected` / `Disconnected`).

- **Data Provider Status**: Individual sensors for each data provider (e.g., `Yahoo Status`, `Coingecko Status`) showing if they are `Available` or `Unavailable`.

- **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.



## Installation



### HACS (Recommended)



1. Make sure you have [HACS](https://hacs.xyz/) installed.

2. Add this repository as a custom repository in HACS:

   - Go to HACS → Integrations.

   - Click the three dots in the top right corner.

   - Select "Custom repositories".

   - Add this repository URL and select "Integration" as the category.

3. Install the integration from HACS.

4. Restart Home Assistant.



### Manual Installation



1. Download the latest release.

2. Copy the `custom_components/ghostfolio` folder to your Home Assistant `custom_components` directory.

3. Restart Home Assistant.



## Configuration



1. Go to **Settings → Devices & Services**.

2. Click **Add Integration** and search for **"Ghostfolio"**.

3. Enter your details and choose which sensors to create:

   - **Base URL**: The URL of your Ghostfolio instance (e.g., `https://your-ghostfolio.com`).

   - **Access Token**: Your Ghostfolio access token.

   - **Show Portfolio Totals**: (Optional) Check to create global portfolio sensors.

   - **Show Individual Accounts**: (Optional) Check to create sensors for each account.

   - **Show Holdings**: (Optional) Check to create sensors and limit numbers for individual assets.

   - **Show Watchlist Items**: (Optional) Check to create sensors and limit numbers for watchlist items.



### Getting Your Access Token



1. Log in to your Ghostfolio instance.

2. Go to **Settings > Security**.

3. Scroll to **Security Token**.

4. Generate or copy your access token (Anonymous Access).



## API Endpoints Used



This integration uses the following Ghostfolio API endpoints:



- `POST /api/v1/auth/anonymous`: For authentication.

- `GET /api/v1/account`: For retrieving the account list and base currency settings.

- `GET /api/v2/portfolio/performance`: For retrieving global and per-account performance data.

- `GET /api/v1/portfolio/holdings`: For retrieving individual asset details.

- `GET /api/v1/watchlist`: For retrieving watchlist items.

- `GET /api/v1/market-data`: For fetching real-time price and history for watchlist items.

- `GET /api/v1/health/data-provider/{provider}`: For checking the status of data providers.



## Data Update Frequency



The integration updates portfolio data every **15 minutes** by default. This can be customized in the configuration options.



## Support



For issues with this integration, please open an issue on the GitHub repository.



For issues with Ghostfolio itself, please refer to the [Ghostfolio GitHub repository](https://github.com/ghostfolio/ghostfolio).



## License



This project is licensed under the MIT License - see the LICENSE file for details.



## Acknowledgments

This integration is maintained by @alfwro13.

Originally 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.