Ghostfolio Python Client

0.8.0 verified Sat May 09 auth: no python

Python API client for Ghostfolio, an open-source personal finance dashboard. Current version 0.8.0 enables portfolio management, holdings, activities, and admin operations. Release cadence is irregular.

pip install ghostfolio

Common errors

error ModuleNotFoundError: No module named 'ghostfolio' ↓

cause Package not installed or required Python >=3.10 not met.

fix

Install with pip install ghostfolio and check Python version (>=3.10).

error AttributeError: 'GhostfolioClient' object has no attribute 'get_positions' ↓

cause Method renamed in 0.4.0.

fix

Use client.get_holdings() instead.

error ghostfolio.exceptions.UnauthorizedException: ... ↓

cause Invalid or missing access token.

fix

Set the environment variable GHOSTFOLIO_ACCESS_TOKEN or pass a valid token to GhostfolioClient.

Warnings

breaking In version 0.4.0, the method `get_positions` was renamed to `get_holdings`. Old code will fail. ↓

fix Use `get_holdings()` instead of `get_positions()`.

deprecated Authentication via `access_token` query parameter is deprecated; use header-based authentication (Authorization: Bearer <token>) which is the only supported method as of 0.8.0. ↓

fix Ensure token is passed as header (handled by library). If passing token in URL, update by removing that pattern.

gotcha Client does not validate credentials on initialization; invalid tokens or URLs raise exceptions only on first API call. This can mask configuration errors. ↓

fix Perform a dummy API call (e.g., `client.get_health()`) immediately after init to check connectivity and authentication.

Imports

GhostfolioClient

wrong

from ghostfolio.client import GhostfolioClient

correct

from ghostfolio import GhostfolioClient

Public API is at top-level; internal module path may change.

Quickstart

Initialize client with base URL and access token, then fetch holdings.

from ghostfolio import GhostfolioClient

client = GhostfolioClient(
    base_url=os.environ.get('GHOSTFOLIO_URL', 'http://localhost:3000'),
    access_token=os.environ.get('GHOSTFOLIO_ACCESS_TOKEN', '')
)
# Fetch all holdings
holdings = client.get_holdings()
print(holdings)