Ghostfolio Home Assistant Integration

A Home Assistant Custom Component (HACS integration) for monitoring your 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.

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.

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

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. It has since been significantly expanded to include granular per-holding tracking, per-account sensors, dynamic configuration options, diagnostic tools, and improved currency handling.