Matrix Crypto

A Matrix-style cryptocurrency ticker for your terminal. It displays live USD prices from CoinGecko's public API, or tickers only in offline mode. No API key or .env file is needed.

Requirements

• Python 3.12 or newer
• A terminal with color support. On Windows, windows-curses is installed automatically.
• Network access for live prices. Offline mode does not make API requests.

Install

After the first PyPI release, install into a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install matrixcrypto
matrixcrypto

On Windows, create a virtual environment with py -3.12 -m venv .venv, activate it with .venv\Scripts\activate, then run python -m pip install matrixcrypto and matrixcrypto.

With uv, create a virtual environment and install the same package:

uv venv --python 3.12
uv pip install matrixcrypto
source .venv/bin/activate
matrixcrypto

The installed commands are matrixcrypto, matrixcrypto-offline, and matrixcrypto-update-list. Press any key, including Ctrl+C, to exit the display.

Run from a source checkout

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
matrixcrypto

The included run_linux.sh and run_windows.bat scripts also create a local virtual environment and install the checkout. The install.sh script remains available for Linux users who prefer the repository installer and its matrixc command.

Options

matrixcrypto --bg-color red --crypto-color yellow --eth
matrixcrypto --solana
matrixcrypto --offline
matrixcrypto-offline
matrixcrypto --config ./my-cryptos.json

--bg-color and --crypto-color accept red, green, blue, yellow, cyan, magenta, or white. The --solana and --eth options select bundled ecosystem lists. The display requests fresh prices about every 75 seconds; a coin without a current price shows N/A.

CoinGecko may rate-limit public requests. If a price request fails, the display shows N/A until a later request succeeds.

The offline default is a curated set of 12 active tickers from the refreshed overall list. Older entries from the previous offline snapshot, including MATIC, have been removed. You can use --config to show any other coins.

For a custom list, save a JSON file like this and pass its path with --config:

{
  "cryptos": [
    {"id": "bitcoin", "ticker": "BTC", "name": "Bitcoin"},
    {"id": "ethereum", "ticker": "ETH", "name": "Ethereum"}
  ]
}

The id values are CoinGecko coin IDs. Run matrixcrypto --help for all display options.

Refresh a list

The bundled lists are release snapshots. To generate a current list in the working directory, run:

matrixcrypto-update-list --ecosystem all --output crypto_list.json
matrixcrypto-update-list --ecosystem solana --output solana.json
matrixcrypto-update-list --ecosystem ethereum --output ethereum.json
matrixcrypto --config ./crypto_list.json

The list updater only writes a file after CoinGecko returns a valid, nonempty result. Use --limit to change the default of 20 coins. To update a future release's bundled defaults, write the new files under src/matrixcrypto/data/ in a source checkout and rebuild the package.

Publishing

See RELEASING.md for the first release checklist and token-safe upload commands.

Licensed under MIT. See LICENSE.md.