Metadata-Version: 2.4
Name: matrixcrypto
Version: 0.1.0
Summary: A Matrix-style terminal display for cryptocurrency tickers and prices
Author: bigsk1
License-Expression: MIT
Project-URL: Homepage, https://github.com/bigsk1/matrix-crypto
Project-URL: Issues, https://github.com/bigsk1/matrix-crypto/issues
Keywords: cryptocurrency,terminal,curses,matrix
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: requests<3,>=2.31
Requires-Dist: windows-curses<3,>=2.4.2; platform_system == "Windows"
Dynamic: license-file

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

![Matrix Crypto terminal display](https://raw.githubusercontent.com/bigsk1/matrix-crypto/main/img/matrix.png)

## 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:

```bash
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:

```bash
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

```bash
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

```bash
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`:

```json
{
  "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:

```bash
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](https://github.com/bigsk1/matrix-crypto/blob/main/RELEASING.md) for the first release checklist and token-safe upload commands.

Licensed under MIT. See [LICENSE.md](https://github.com/bigsk1/matrix-crypto/blob/main/LICENSE.md).
