GhostCompanion

Transfer transactions from numerous sources to Ghostfolio.

Currently implemented for Coinbase, Interactive Brokers (IBKR) and Tastytrade.

Getting Started • Report Bug • Request Feature • Roadmap

Table of Contents

• Getting Started
  • Environment Variables
  • Docker
  • Docker Compose
  • Kubernetes
• Interactive Brokers Flex Queries and Caveats
• Roadmap
• Contributing
  • Top contributors
• Acknowledgments
• License

Getting Started

GhostCompanion plugin works best when doing account management all by itself. In other words, manually creating activities in your Ghostfolio account is not only not needed, but it's also discouraged. That's because some operations (like symbol change, or stock splits) need to understand the complete picture of the account, and change its state totally (see Interactive Brokers Flex Queries and Caveats for the only exception).

It'll start by getting (or creating) accounts for each source (Coinbase, Interactive Brokers or Tastytrade) from Ghostfolio, and from that it'll start adding trading transactions and/or dividends.

This plugin runs completely in the background, and is provided as container images hosted on Docker Hub for linux/amd64.

Environment Variables

Start by setting up the appropriate environment variables, listed below.

Name	Type	Default Value	Description
COINBASE_API_KEY_ID	string		The Coinbase API Key.
COINBASE_SECRET	string		The Coinbase Secret. It must be generated according to the Coinbase API official documentation.
GHOSTFOLIO_ACCOUNT_TOKEN	string		The Ghostfolio Account Token.
GHOSTFOLIO_BASE_URL	string (optional)	"https://ghostfol.io"	The Ghostfolio URL. If you're self hosting you should change it for your particular instance URL, otherwise all data will be exported to Ghostfolio cloud offering.
IBKR_QUERY	string		The Interactive Brokers Flex Query ID.
IBKR_TOKEN	string		The Interactive Brokers Flex Query Token.
TASTYTRADE_CLIENT_SECRET	string		The Tastytrade Client Secret.
TASTYTRADE_REFRESH_TOKEN	string		The Tastytrade Refresh Token.
LOG_LEVEL	string (optional)	INFO	Logging verbosity: DEBUG, INFO, WARNING, ERROR, or CRITICAL.

For how to generate the TastyTrade variables, please refer to this documentation. For how to generate the Interactive Brokers variables, please refer to Interactive Brokers Flex Queries and Caveats.

If you don't wish to use all available providers when importing transactions, simply don't provide the environment variables related to it.

(back to top)

Docker

For evaluation, you can run it by:

docker run --rm --name ghostcompanion \
-e GHOSTFOLIO_ACCOUNT_TOKEN=<account_token> \
-e TASTYTRADE_CLIENT_SECRET=my_client_secret \
-e TASTYTRADE_REFRESH_TOKEN=super_secure_token \
olirafa/ghostcompanion

It'll spawn the container, ingest all data from Tastytrade, export it all to Ghostfolio, and then remove the container at the end.

To unleash the plugin's potential, you would want to deploy it scheduled to run from time to time (weekly, for example). For that, two approaches are presented, deploying using Docker Compose or in your Kubernetes cluster.

(back to top)

Docker Compose

The plugin was developed without a scheduler (like Cron) by design, so another tool is needed for that. We suggest using Ofelia, and that's what we have in the provided Docker Compose file.

First, clone the repo:

git clone https://github.com/OliRafa/ghostcompanion.git

Enter the repo folder:

cd ghostcompanion

Then, you'll need a .env file with the environment variables set. A example file can be found here.

With everything ready, run the following command:

docker compose up -d

It will deploy it in your Docker Compose infrastructure, running weekly by default.

(back to top)

Kubernetes

Start by deploying environment variables as ConfigMaps and/or Secrets.

Since Kubernetes has a build-in scheduler, you can create a CronJob following the official documentation.

For an example of such CronJob deployment, take a look below:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: ghostcompanion
  namespace: ghostfolio
spec:
  schedule: "@hourly"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: ghostcompanion
              image: olirafa/ghostcompanion
              imagePullPolicy: IfNotPresent
              env:
                - name: GHOSTFOLIO_ACCOUNT_TOKEN
                  valueFrom:
                    configMapKeyRef:
                      name: ghostcompanion-configs
                      key: GHOSTFOLIO_ACCOUNT_TOKEN
                - name: GHOSTFOLIO_BASE_URL
                  valueFrom:
                    configMapKeyRef:
                      name: ghostcompanion-configs
                      key: GHOSTFOLIO_BASE_URL
                - name: TASTYTRADE_CLIENT_SECRET
                  valueFrom:
                    secretKeyRef:
                      name: tastytrade-credentials
                      key: client_secret
                - name: TASTYTRADE_REFRESH_TOKEN 
                  valueFrom:
                    secretKeyRef:
                      name: tastytrade-credentials
                      key: refresh_token
          restartPolicy: OnFailure

(back to top)

Interactive Brokers Flex Queries and Caveats

Current implementation for getting Interactive Brokers transactions relies on Flex Queries.

To generate the Flex Query, please refer to the official documentation.

At minimum, you'll need the following configurations:

• Select Change in Dividend Accruals
  • Mark all checkboxes
• Select Trades
  • Select Execution
  • Mark all checkboxes
• Select Format XML
• Select Date Format yyyyMMdd
• Select Time Format HHmmss
• Select Date/Time Separator ; (semi-colon)
• Select Include Canceled Trades

On Period comes the caveat. Flex Queries only allows for a maximum period of Last 365 Calendar Days, which means that any transaction prior to that date won't be listed in the Flex Query, and hence it won't be automatically inserted into Ghostfolio.

This means that any transaction prior to that date should be added manually in Ghostfolio, and GhostCompanion won't change those when updating the account with new transactions.

(back to top)

Roadmap

• [-] Coinbase
  • Crypto buys and sells
  • Crypto transaction fees
  • Account balance
• [-] Interactive Brokers
  • Stock buys and sells
  • Forward share splits
  • Symbol changes
  • Dividends and dividend reinvestments
  • Account balance
• [-] TastyTrade
  • Stock buys and sells
  • Forward share splits
  • Symbol changes
  • Dividends and dividend reinvestments
  • Account balance

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors

Acknowledgments

• Ghostfolio for being an amazing tool!
• Interactive Brokers (IBKR) for the API and agusalex/ibflex for the API Python wrapper.
• Tastytrade for the API and tastyware/tastytrade for the API Python wrapper.
• Yahoo Finance for the API and ranaroussi/yfinance for the API Python wrapper.

(back to top)

License

Distributed under the Unlicense License. See [LICENSE.txt](https://github.com/OliRafa/ghostcompanion/blob/main/LICENSE) for more information.

(back to top)

---

Rafael Oliveira  ·  olirafa.github.io  ·  GitHub @OliRafa  ·  LinkedIn @OliRafa