Linux Stock Board for Any TV, Written in C

Hobby project, not financial advice. See the Disclaimer at the end.

What it is

A small program that turns any Linux computer and a screen into a stock board. It shows every holding in one table: the current price, today's move, and how much you are up or down against what you paid. Gains are green and losses are red, and the table refreshes on its own.

I run it on a Raspberry Pi Zero W connected to a TV, or the same Pi connected to a portable desktop monitor. It runs on the plain text console, so no graphical desktop is needed.

Why I made it

I wanted to keep track of my portfolio without logging into my trading accounts every time. A broker's app shows one account at a time, behind a login. This board shows every holding in one table, on a screen that is always on, and it only needs a market-data API key from finnhub, not account credentials.

What it shows

• Change is how much the price has moved today.
• Gain/Loss is your total profit or loss on that holding: the difference between today's price and your purchase price, times the number of shares.

The purchase prices and share counts above are example values, not real holdings.

Where the data comes from: Finnhub

Finnhub provides stock market data over a simple web API. A free account gives you an API key, and that key is all the program needs. It never sees your broker logins.

The program uses two Finnhub endpoints for each stock:

Quote gives the latest price:

https://finnhub.io/api/v1/quote?symbol=MU&token=YOUR_KEY
{"c":1088,"d":42.44,"dp":4.0591,"h":1089.22,"l":1011.42,"o":1017.37,"pc":1045.56,"t":1791403200}

c is the current price, d the change today, and dp the change in percent. The program uses these three. The others are the day's high (h), low (l), open (o), the previous close (pc) and a timestamp (t).

Company profile gives the name and currency:

https://finnhub.io/api/v1/stock/profile2?symbol=MU&token=YOUR_KEY
{"ticker":"MU","name":"Micron Technology Inc","currency":"USD","exchange":"NASDAQ NMS - GLOBAL MARKET", ...}

The program takes name and currency from this response.

Points to know about the free tier:

• It covers US-listed stocks. Other exchanges may not be available.
• It has a rate limit. Every stock costs two requests per refresh, so a short list refreshed every minute stays well inside it.
• It has no currency exchange rates. If you bought a US stock in pounds, the program can't convert, so it shows ? rather than a wrong number. You can record the currency you paid in as an optional fourth field in your list.

How the code is organised

Everything is in one C file, monitor.c, of about 450 lines. In the order it runs:

• Read settings. read_api_key() reads your Finnhub key from api.txt. load_tickers()reads your holdings from tickers.txt, one per line: TICKER,PURCHASE_PRICE,SHARES.
• Fetch data. fetch_all() sends the quote and profile requests for every stock at the same time instead of one after another, so a long list doesn't take longer to refresh. It uses libcurl for the web requests.
• Read the replies. parse_quote_response() and parse_profile_response() pick out the fields above from Finnhub's JSON, using the cJSON library.
• Print the table. print_stock() works out the gain or loss and prints one coloured row per stock.
• Repeat. With --watch 60, main() redraws the table every 60 seconds.

libcurl and cJSON are included in the repository as git submodules and built with the program, so you don't need to install them.

Try it

On any Debian based Linux machine (e.g. Raspberry Pi OS):

sudo apt install build-essential cmake libssl-dev git
git clone --recursive https://github.com/renovatio-systems/finnhub-stock-tracker.git
cd finnhub-stock-tracker
cmake -S . -B build
cmake --build build

Then:

• Get a free API key from finnhub.io and save it as build/api.txt.
• Put your holdings in a text file such as ~/holdings.txt, one per line, for example MU,80.00,5.
• From the build folder, run ./stock_monitor ~/holdings.txt --watch 60.

To use a TV as a permanent display, the Pi also needs a few settings. Choose a console font that fits the 125-character table, using sudo dpkg-reconfigure console-setup (Terminus 14x28 on a 1080p screen). Turn off screen blanking by adding consoleblank=0 to /boot/firmware/cmdline.txt. Then set the Pi to log in automatically and start the program on boot.

Limitations

• US stocks only, on Finnhub's free tier.
• No currency conversion.
• If a stock's price can't be fetched, it is left out of the table until the next refresh.
• ETFs such as SPY show "Unknown" as the company name, because Finnhub has no company profile for them.
• The table flickers briefly when it refreshes.

Disclaimer

This is a hobby project, built for personal use and shared for educational purposes only. It is not financial advice and not a trading tool.

• Prices, changes and gain/loss figures may be delayed, incomplete or wrong. They depend on a third-party data provider (Finnhub) and on the limitations listed above. Do not rely on them for investment or trading decisions. Check figures with your broker or another authoritative source.
• The software is provided "as is", without warranty of any kind, under the MIT License. The author accepts no liability for any loss, damage or cost arising from its use, including financial loss, missed trades, data errors or hardware damage.
• You are responsible for complying with Finnhub's terms of service and for keeping your API key secure.

Code

GitHub repository: https://github.com/renovatio-systems/finnhub-stock-tracker

Schematics/Hardware

None. The only connections are HDMI and power.

Credits

Uses cJSON (MIT) by Dave Gamble and libcurl (curl license) by Daniel Stenberg and contributors.

Market data from Finnhub, using their free API tier.