matrixcrypto 0.1.0__tar.gz

matrixcrypto-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 bigsk1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matrixcrypto-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+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).

matrixcrypto-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 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).

matrixcrypto-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matrixcrypto"
+version = "0.1.0"
+description = "A Matrix-style terminal display for cryptocurrency tickers and prices"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [{name = "bigsk1"}]
+keywords = ["cryptocurrency", "terminal", "curses", "matrix"]
+classifiers = [
+    "Environment :: Console :: Curses",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Terminals",
+]
+dependencies = [
+    "requests>=2.31,<3",
+    "windows-curses>=2.4.2,<3; platform_system == 'Windows'",
+]
+
+[project.urls]
+Homepage = "https://github.com/bigsk1/matrix-crypto"
+Issues = "https://github.com/bigsk1/matrix-crypto/issues"
+
+[project.scripts]
+matrixcrypto = "matrixcrypto.app:main"
+matrixcrypto-offline = "matrixcrypto.app:offline_main"
+matrixcrypto-update-list = "matrixcrypto.lists:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+matrixcrypto = ["data/*.json"]

matrixcrypto-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matrixcrypto-0.1.0/src/matrixcrypto/__init__.py

@@ -0,0 +1,3 @@
+"""Matrix-style cryptocurrency terminal display."""
+
+__version__ = "0.1.0"

matrixcrypto-0.1.0/src/matrixcrypto/__main__.py

@@ -0,0 +1,3 @@
+from .app import main
+
+raise SystemExit(main())

matrixcrypto-0.1.0/src/matrixcrypto/app.py

@@ -0,0 +1,329 @@
+"""Terminal animation and optional CoinGecko price updates."""
+
+from __future__ import annotations
+
+import argparse
+import curses
+import json
+import math
+import random
+import sys
+import threading
+import time
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import requests
+
+SETTINGS = {
+    "ANIMATION_SPEED": 0.01,
+    "BACKGROUND_PATTERN": (1, 2, 3, 1),
+    "BACKGROUND_CHARS": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()_+-=[]{}|;:,.<>?/",
+    "CRYPTO_DISPLAY_COUNT": 3,
+    "CRYPTO_DISPLAY_CHANCE": 0.13,
+    "BACKGROUND_COLUMN_LENGTH_RANGE": (0.3, 0.6),
+    "CRYPTO_FALL_SPEED_RANGE": (0.12, 0.16),
+    "BACKGROUND_CHANGE_CHANCE": 0.5,
+    "BACKGROUND_FALL_SPEED_RANGE": (0.06, 0.1),
+}
+
+COLOR_MAP = {
+    "red": curses.COLOR_RED,
+    "green": curses.COLOR_GREEN,
+    "blue": curses.COLOR_BLUE,
+    "yellow": curses.COLOR_YELLOW,
+    "cyan": curses.COLOR_CYAN,
+    "magenta": curses.COLOR_MAGENTA,
+    "white": curses.COLOR_WHITE,
+}
+
+PRICE_URL = "https://api.coingecko.com/api/v3/simple/price"
+PRICE_UPDATE_SECONDS = 75
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Matrix-style cryptocurrency terminal display"
+    )
+    parser.add_argument("--bg-color", choices=COLOR_MAP, default="green")
+    parser.add_argument("--crypto-color", choices=COLOR_MAP, default="white")
+    parser.add_argument(
+        "--config", type=Path, help="Path to a custom cryptocurrency JSON list"
+    )
+    parser.add_argument(
+        "--offline", action="store_true", help="Show tickers without fetching prices"
+    )
+    ecosystem = parser.add_mutually_exclusive_group()
+    ecosystem.add_argument(
+        "--solana", action="store_true", help="Use the Solana ecosystem list"
+    )
+    ecosystem.add_argument(
+        "--eth", action="store_true", help="Use the Ethereum ecosystem list"
+    )
+    return parser.parse_args(argv)
+
+
+def default_config_name(args: argparse.Namespace, offline: bool) -> str:
+    if args.solana:
+        return "solana_ecosystem_crypto_list.json"
+    if args.eth:
+        return "ethereum_ecosystem_crypto_list.json"
+    if offline:
+        return "offline_crypto_list.json"
+    return "crypto_list.json"
+
+
+def load_cryptos(config: Path | str) -> list[dict[str, Any]]:
+    if isinstance(config, Path):
+        with config.open(encoding="utf-8") as file:
+            data = json.load(file)
+    else:
+        resource = resources.files("matrixcrypto").joinpath("data", config)
+        with resource.open("r", encoding="utf-8") as file:
+            data = json.load(file)
+
+    if not isinstance(data, dict) or not isinstance(data.get("cryptos"), list):
+        raise TypeError("Configuration must contain a 'cryptos' list")
+    cryptos = data["cryptos"]
+    if not cryptos or any(
+        not isinstance(crypto, dict)
+        or not isinstance(crypto.get("id"), str)
+        or not isinstance(crypto.get("ticker"), str)
+        for crypto in cryptos
+    ):
+        raise ValueError(
+            "Configuration needs at least one crypto with string 'id' and 'ticker'"
+        )
+    return cryptos
+
+
+def fetch_current_prices(cryptos: list[dict[str, Any]]) -> bool:
+    ids = ",".join(crypto["id"] for crypto in cryptos)
+    for crypto in cryptos:
+        crypto.pop("price", None)
+    try:
+        response = requests.get(
+            PRICE_URL,
+            params={"ids": ids, "vs_currencies": "usd"},
+            timeout=20,
+        )
+        response.raise_for_status()
+        prices = response.json()
+        if not isinstance(prices, dict):
+            return False
+        for crypto in cryptos:
+            price_data = prices.get(crypto["id"])
+            if not isinstance(price_data, dict):
+                continue
+            price = price_data.get("usd")
+            if (
+                isinstance(price, (int, float))
+                and not isinstance(price, bool)
+                and math.isfinite(price)
+            ):
+                crypto["price"] = f"{price:.2f}" if price < 1000 else f"{price:,.0f}"
+        return True
+    except (requests.RequestException, ValueError):
+        return False
+
+
+def update_prices_periodically(
+    cryptos: list[dict[str, Any]], stop_event: threading.Event
+) -> None:
+    while not stop_event.is_set():
+        fetch_current_prices(cryptos)
+        stop_event.wait(PRICE_UPDATE_SECONDS)
+
+
+def init_color_pairs(bg_color: str, crypto_color: str) -> None:
+    curses.start_color()
+    try:
+        curses.use_default_colors()
+        background = -1
+    except curses.error:
+        background = curses.COLOR_BLACK
+    curses.init_pair(1, COLOR_MAP[bg_color], background)
+    curses.init_pair(2, curses.COLOR_WHITE, background)
+    curses.init_pair(3, COLOR_MAP[crypto_color], background)
+
+
+class MatrixColumn:
+    def __init__(self, height: int) -> None:
+        self.height = height
+        self.length = max(
+            1, int(random.uniform(*SETTINGS["BACKGROUND_COLUMN_LENGTH_RANGE"]) * height)
+        )
+        self.chars = [
+            random.choice(SETTINGS["BACKGROUND_CHARS"]) for _ in range(self.length)
+        ]
+        self.speed = random.uniform(*SETTINGS["BACKGROUND_FALL_SPEED_RANGE"])
+        self.counter = 0.0
+        self.top = -self.length
+
+    def update(self, dt: float) -> None:
+        self.counter += dt
+        if self.counter < self.speed:
+            return
+        self.counter = 0.0
+        self.top += 1
+        if self.top >= self.height:
+            self.top = -self.length
+        if random.random() < SETTINGS["BACKGROUND_CHANGE_CHANCE"]:
+            self.chars[random.randrange(self.length)] = random.choice(
+                SETTINGS["BACKGROUND_CHARS"]
+            )
+
+    def draw(self, stdscr: Any, x: int) -> None:
+        for index, char in enumerate(self.chars):
+            y = self.top + index
+            if 0 <= y < self.height:
+                attr = (
+                    curses.color_pair(2) | curses.A_BOLD
+                    if index == self.length - 1
+                    else curses.color_pair(1) | curses.A_DIM
+                )
+                safe_addstr(stdscr, y, x, char, attr)
+
+
+class CryptoDisplay:
+    def __init__(
+        self, crypto: dict[str, Any], x: int, max_y: int, offline: bool
+    ) -> None:
+        self.crypto = crypto
+        self.x = x
+        self.y = 0
+        self.max_y = max_y
+        self.offline = offline
+        self.speed = random.uniform(*SETTINGS["CRYPTO_FALL_SPEED_RANGE"])
+        self.counter = 0.0
+
+    def update(self, dt: float) -> None:
+        self.counter += dt
+        if self.counter >= self.speed:
+            self.counter = 0.0
+            self.y += 1
+
+    def get_display_text(self) -> str:
+        ticker = self.crypto["ticker"].upper()
+        return (
+            ticker if self.offline else f"{ticker} $ {self.crypto.get('price', 'N/A')}"
+        )
+
+    def is_offscreen(self) -> bool:
+        return self.y >= self.max_y
+
+
+def safe_addstr(stdscr: Any, y: int, x: int, text: str, attr: int) -> None:
+    try:
+        stdscr.addstr(y, x, text, attr)
+    except curses.error:
+        pass
+
+
+def build_columns(height: int, width: int) -> list[tuple[int, MatrixColumn]]:
+    columns: list[tuple[int, MatrixColumn]] = []
+    x = 0
+    for index in range(width):
+        if x >= width:
+            break
+        columns.append((x, MatrixColumn(height)))
+        x += (
+            1
+            + SETTINGS["BACKGROUND_PATTERN"][
+                index % len(SETTINGS["BACKGROUND_PATTERN"])
+            ]
+        )
+    return columns
+
+
+def run_screen(
+    stdscr: Any, cryptos: list[dict[str, Any]], args: argparse.Namespace, offline: bool
+) -> None:
+    init_color_pairs(args.bg_color, args.crypto_color)
+    try:
+        curses.curs_set(0)
+    except curses.error:
+        pass
+    stdscr.nodelay(True)
+
+    stop_event = threading.Event()
+    if not offline:
+        threading.Thread(
+            target=update_prices_periodically, args=(cryptos, stop_event), daemon=True
+        ).start()
+
+    height, width = stdscr.getmaxyx()
+    columns = build_columns(height, width)
+    displays: list[CryptoDisplay] = []
+    last_time = time.monotonic()
+
+    try:
+        while True:
+            now = time.monotonic()
+            dt = now - last_time
+            last_time = now
+
+            current_size = stdscr.getmaxyx()
+            if current_size != (height, width):
+                height, width = current_size
+                columns = build_columns(height, width)
+                displays.clear()
+
+            stdscr.erase()
+            for x, column in columns:
+                column.update(dt)
+                column.draw(stdscr, x)
+
+            for display in displays[:]:
+                display.update(dt)
+                if display.is_offscreen():
+                    displays.remove(display)
+                    continue
+                for index, char in enumerate(display.get_display_text()):
+                    y = display.y + index
+                    if y < height:
+                        safe_addstr(
+                            stdscr,
+                            y,
+                            display.x,
+                            char,
+                            curses.color_pair(3) | curses.A_BOLD,
+                        )
+
+            if (
+                width
+                and len(displays) < SETTINGS["CRYPTO_DISPLAY_COUNT"]
+                and random.random() < SETTINGS["CRYPTO_DISPLAY_CHANCE"]
+            ):
+                displays.append(
+                    CryptoDisplay(
+                        random.choice(cryptos), random.randrange(width), height, offline
+                    )
+                )
+
+            stdscr.refresh()
+            if stdscr.getch() != -1:
+                break
+            time.sleep(SETTINGS["ANIMATION_SPEED"])
+    finally:
+        stop_event.set()
+
+
+def main(argv: list[str] | None = None, *, offline: bool = False) -> int:
+    args = parse_args(argv)
+    offline = offline or args.offline
+    try:
+        cryptos = load_cryptos(args.config or default_config_name(args, offline))
+    except (OSError, TypeError, ValueError) as exc:
+        print(f"matrixcrypto: cannot load cryptocurrency list: {exc}", file=sys.stderr)
+        return 1
+    try:
+        curses.wrapper(run_screen, cryptos, args, offline)
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def offline_main() -> int:
+    return main(offline=True)

matrixcrypto-0.1.0/src/matrixcrypto/data/crypto_list.json

@@ -0,0 +1,104 @@
+{
+  "cryptos": [
+    {
+      "id": "bitcoin",
+      "ticker": "BTC",
+      "name": "Bitcoin"
+    },
+    {
+      "id": "ethereum",
+      "ticker": "ETH",
+      "name": "Ethereum"
+    },
+    {
+      "id": "tether",
+      "ticker": "USDT",
+      "name": "Tether"
+    },
+    {
+      "id": "binancecoin",
+      "ticker": "BNB",
+      "name": "BNB"
+    },
+    {
+      "id": "ripple",
+      "ticker": "XRP",
+      "name": "XRP"
+    },
+    {
+      "id": "usd-coin",
+      "ticker": "USDC",
+      "name": "USDC"
+    },
+    {
+      "id": "solana",
+      "ticker": "SOL",
+      "name": "Solana"
+    },
+    {
+      "id": "tron",
+      "ticker": "TRX",
+      "name": "TRON"
+    },
+    {
+      "id": "zcash",
+      "ticker": "ZEC",
+      "name": "Zcash"
+    },
+    {
+      "id": "figure-heloc",
+      "ticker": "FIGR_HELOC",
+      "name": "Figure Heloc"
+    },
+    {
+      "id": "hyperliquid",
+      "ticker": "HYPE",
+      "name": "Hyperliquid"
+    },
+    {
+      "id": "dogecoin",
+      "ticker": "DOGE",
+      "name": "Dogecoin"
+    },
+    {
+      "id": "monero",
+      "ticker": "XMR",
+      "name": "Monero"
+    },
+    {
+      "id": "rain",
+      "ticker": "RAIN",
+      "name": "Rain"
+    },
+    {
+      "id": "whitebit",
+      "ticker": "WBT",
+      "name": "WhiteBIT Coin"
+    },
+    {
+      "id": "usds",
+      "ticker": "USDS",
+      "name": "USDS"
+    },
+    {
+      "id": "chainlink",
+      "ticker": "LINK",
+      "name": "Chainlink"
+    },
+    {
+      "id": "cardano",
+      "ticker": "ADA",
+      "name": "Cardano"
+    },
+    {
+      "id": "leo-token",
+      "ticker": "LEO",
+      "name": "LEO Token"
+    },
+    {
+      "id": "stellar",
+      "ticker": "XLM",
+      "name": "Stellar"
+    }
+  ]
+}

matrixcrypto-0.1.0/src/matrixcrypto/data/ethereum_ecosystem_crypto_list.json

@@ -0,0 +1,104 @@
+{
+  "cryptos": [
+    {
+      "id": "ethereum",
+      "ticker": "ETH",
+      "name": "Ethereum"
+    },
+    {
+      "id": "tether",
+      "ticker": "USDT",
+      "name": "Tether"
+    },
+    {
+      "id": "binancecoin",
+      "ticker": "BNB",
+      "name": "BNB"
+    },
+    {
+      "id": "usd-coin",
+      "ticker": "USDC",
+      "name": "USDC"
+    },
+    {
+      "id": "staked-ether",
+      "ticker": "STETH",
+      "name": "Lido Staked Ether"
+    },
+    {
+      "id": "wrapped-steth",
+      "ticker": "WSTETH",
+      "name": "Wrapped stETH"
+    },
+    {
+      "id": "whitebit",
+      "ticker": "WBT",
+      "name": "WhiteBIT Coin"
+    },
+    {
+      "id": "wrapped-beacon-eth",
+      "ticker": "WBETH",
+      "name": "Wrapped Beacon ETH"
+    },
+    {
+      "id": "usds",
+      "ticker": "USDS",
+      "name": "USDS"
+    },
+    {
+      "id": "wrapped-bitcoin",
+      "ticker": "WBTC",
+      "name": "Wrapped Bitcoin"
+    },
+    {
+      "id": "chainlink",
+      "ticker": "LINK",
+      "name": "Chainlink"
+    },
+    {
+      "id": "leo-token",
+      "ticker": "LEO",
+      "name": "LEO Token"
+    },
+    {
+      "id": "coinbase-wrapped-btc",
+      "ticker": "CBBTC",
+      "name": "Coinbase Wrapped BTC"
+    },
+    {
+      "id": "aave-v3-weth",
+      "ticker": "AWETH",
+      "name": "Aave v3 WETH"
+    },
+    {
+      "id": "wrapped-eeth",
+      "ticker": "WEETH",
+      "name": "Wrapped eETH"
+    },
+    {
+      "id": "weth",
+      "ticker": "WETH",
+      "name": "WETH"
+    },
+    {
+      "id": "uniswap",
+      "ticker": "UNI",
+      "name": "Uniswap"
+    },
+    {
+      "id": "ethena-usde",
+      "ticker": "USDE",
+      "name": "Ethena USDe"
+    },
+    {
+      "id": "dai",
+      "ticker": "DAI",
+      "name": "Dai"
+    },
+    {
+      "id": "susds",
+      "ticker": "SUSDS",
+      "name": "sUSDS"
+    }
+  ]
+}

matrixcrypto-0.1.0/src/matrixcrypto/data/offline_crypto_list.json

@@ -0,0 +1,64 @@
+{
+  "cryptos": [
+    {
+      "id": "bitcoin",
+      "ticker": "BTC",
+      "name": "Bitcoin"
+    },
+    {
+      "id": "ethereum",
+      "ticker": "ETH",
+      "name": "Ethereum"
+    },
+    {
+      "id": "binancecoin",
+      "ticker": "BNB",
+      "name": "BNB"
+    },
+    {
+      "id": "ripple",
+      "ticker": "XRP",
+      "name": "XRP"
+    },
+    {
+      "id": "solana",
+      "ticker": "SOL",
+      "name": "Solana"
+    },
+    {
+      "id": "tron",
+      "ticker": "TRX",
+      "name": "TRON"
+    },
+    {
+      "id": "zcash",
+      "ticker": "ZEC",
+      "name": "Zcash"
+    },
+    {
+      "id": "hyperliquid",
+      "ticker": "HYPE",
+      "name": "Hyperliquid"
+    },
+    {
+      "id": "dogecoin",
+      "ticker": "DOGE",
+      "name": "Dogecoin"
+    },
+    {
+      "id": "monero",
+      "ticker": "XMR",
+      "name": "Monero"
+    },
+    {
+      "id": "chainlink",
+      "ticker": "LINK",
+      "name": "Chainlink"
+    },
+    {
+      "id": "cardano",
+      "ticker": "ADA",
+      "name": "Cardano"
+    }
+  ]
+}

matrixcrypto-0.1.0/src/matrixcrypto/data/solana_ecosystem_crypto_list.json

@@ -0,0 +1,104 @@
+{
+  "cryptos": [
+    {
+      "id": "tether",
+      "ticker": "USDT",
+      "name": "Tether"
+    },
+    {
+      "id": "usd-coin",
+      "ticker": "USDC",
+      "name": "USDC"
+    },
+    {
+      "id": "solana",
+      "ticker": "SOL",
+      "name": "Solana"
+    },
+    {
+      "id": "usds",
+      "ticker": "USDS",
+      "name": "USDS"
+    },
+    {
+      "id": "wrapped-bitcoin",
+      "ticker": "WBTC",
+      "name": "Wrapped Bitcoin"
+    },
+    {
+      "id": "chainlink",
+      "ticker": "LINK",
+      "name": "Chainlink"
+    },
+    {
+      "id": "coinbase-wrapped-btc",
+      "ticker": "CBBTC",
+      "name": "Coinbase Wrapped BTC"
+    },
+    {
+      "id": "ethena-usde",
+      "ticker": "USDE",
+      "name": "Ethena USDe"
+    },
+    {
+      "id": "usd1-wlfi",
+      "ticker": "USD1",
+      "name": "USD1"
+    },
+    {
+      "id": "global-dollar",
+      "ticker": "USDG",
+      "name": "Global Dollar"
+    },
+    {
+      "id": "paypal-usd",
+      "ticker": "PYUSD",
+      "name": "PayPal USD"
+    },
+    {
+      "id": "hashnote-usyc",
+      "ticker": "USYC",
+      "name": "Circle USYC"
+    },
+    {
+      "id": "blackrock-usd-institutional-digital-liquidity-fund",
+      "ticker": "BUIDL",
+      "name": "BlackRock USD Institutional Digital Liquidity Fund"
+    },
+    {
+      "id": "ondo-us-dollar-yield",
+      "ticker": "USDY",
+      "name": "Ondo US Dollar Yield"
+    },
+    {
+      "id": "ethena",
+      "ticker": "ENA",
+      "name": "Ethena"
+    },
+    {
+      "id": "aave",
+      "ticker": "AAVE",
+      "name": "Aave"
+    },
+    {
+      "id": "pump-fun",
+      "ticker": "PUMP",
+      "name": "Pump.fun"
+    },
+    {
+      "id": "world-liberty-financial",
+      "ticker": "WLFI",
+      "name": "World Liberty Financial"
+    },
+    {
+      "id": "wrapped-solana",
+      "ticker": "WSOL",
+      "name": "Wrapped SOL"
+    },
+    {
+      "id": "usdgo",
+      "ticker": "USDGO",
+      "name": "USDGO"
+    }
+  ]
+}

matrixcrypto-0.1.0/src/matrixcrypto/lists.py

@@ -0,0 +1,62 @@
+"""Refresh cryptocurrency lists from the public CoinGecko API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import requests
+
+MARKETS_URL = "https://api.coingecko.com/api/v3/coins/markets"
+DEFAULT_FILES = {
+    "all": "crypto_list.json",
+    "solana": "solana_ecosystem_crypto_list.json",
+    "ethereum": "ethereum_ecosystem_crypto_list.json",
+}
+
+
+def fetch_list(ecosystem: str, limit: int) -> list[dict[str, str]]:
+    params: dict[str, Any] = {
+        "vs_currency": "usd",
+        "order": "market_cap_desc",
+        "per_page": limit,
+        "page": 1,
+        "sparkline": "false",
+    }
+    if ecosystem != "all":
+        params["category"] = f"{ecosystem}-ecosystem"
+    response = requests.get(MARKETS_URL, params=params, timeout=20)
+    response.raise_for_status()
+    data = response.json()
+    if not isinstance(data, list) or not data:
+        raise ValueError("CoinGecko returned no coins")
+    return [
+        {"id": coin["id"], "ticker": coin["symbol"].upper(), "name": coin["name"]}
+        for coin in data
+    ]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Fetch a cryptocurrency list from CoinGecko"
+    )
+    parser.add_argument("--ecosystem", choices=DEFAULT_FILES, default="all")
+    parser.add_argument("--limit", type=int, default=20)
+    parser.add_argument("--output", type=Path, help="Destination JSON file")
+    args = parser.parse_args(argv)
+    if not 1 <= args.limit <= 250:
+        parser.error("--limit must be between 1 and 250")
+    output = args.output or Path(DEFAULT_FILES[args.ecosystem])
+    try:
+        cryptos = fetch_list(args.ecosystem, args.limit)
+        output.write_text(
+            json.dumps({"cryptos": cryptos}, indent=2) + "\n", encoding="utf-8"
+        )
+    except (requests.RequestException, OSError, ValueError, KeyError, TypeError) as exc:
+        print(f"matrixcrypto-update-list: {exc}", file=sys.stderr)
+        return 1
+    print(f"Saved {len(cryptos)} cryptocurrencies to {output}")
+    return 0

matrixcrypto-0.1.0/src/matrixcrypto.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+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).

matrixcrypto-0.1.0/src/matrixcrypto.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE.md
+README.md
+pyproject.toml
+src/matrixcrypto/__init__.py
+src/matrixcrypto/__main__.py
+src/matrixcrypto/app.py
+src/matrixcrypto/lists.py
+src/matrixcrypto.egg-info/PKG-INFO
+src/matrixcrypto.egg-info/SOURCES.txt
+src/matrixcrypto.egg-info/dependency_links.txt
+src/matrixcrypto.egg-info/entry_points.txt
+src/matrixcrypto.egg-info/requires.txt
+src/matrixcrypto.egg-info/top_level.txt
+src/matrixcrypto/data/crypto_list.json
+src/matrixcrypto/data/ethereum_ecosystem_crypto_list.json
+src/matrixcrypto/data/offline_crypto_list.json
+src/matrixcrypto/data/solana_ecosystem_crypto_list.json
+tests/test_app.py

matrixcrypto-0.1.0/src/matrixcrypto.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

matrixcrypto-0.1.0/src/matrixcrypto.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+matrixcrypto = matrixcrypto.app:main
+matrixcrypto-offline = matrixcrypto.app:offline_main
+matrixcrypto-update-list = matrixcrypto.lists:main

matrixcrypto-0.1.0/src/matrixcrypto.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests<3,>=2.31
+
+[:platform_system == "Windows"]
+windows-curses<3,>=2.4.2

matrixcrypto-0.1.0/src/matrixcrypto.egg-info/top_level.txt

@@ -0,0 +1 @@
+matrixcrypto

matrixcrypto-0.1.0/tests/test_app.py

@@ -0,0 +1,99 @@
+import contextlib
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import requests
+
+from matrixcrypto import app, lists
+
+
+class ConfigTests(unittest.TestCase):
+    def test_all_bundled_lists_are_available(self):
+        for filename in (
+            "crypto_list.json",
+            "solana_ecosystem_crypto_list.json",
+            "ethereum_ecosystem_crypto_list.json",
+            "offline_crypto_list.json",
+        ):
+            with self.subTest(filename=filename):
+                self.assertTrue(app.load_cryptos(filename))
+
+    def test_custom_list_rejects_empty_list(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "empty.json"
+            path.write_text('{"cryptos": []}', encoding="utf-8")
+            with self.assertRaisesRegex(ValueError, "at least one crypto"):
+                app.load_cryptos(path)
+
+    def test_main_uses_packaged_list_from_any_directory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            with (
+                patch("matrixcrypto.app.curses.wrapper") as wrapper,
+                contextlib.chdir(directory),
+            ):
+                self.assertEqual(app.main(["--offline"]), 0)
+            self.assertTrue(wrapper.called)
+            self.assertTrue(wrapper.call_args.args[1])
+            self.assertTrue(wrapper.call_args.args[3])
+
+
+class PriceTests(unittest.TestCase):
+    def test_prices_are_formatted_and_missing_ids_remain_unavailable(self):
+        cryptos = [
+            {"id": "bitcoin", "ticker": "BTC"},
+            {"id": "ethereum", "ticker": "ETH"},
+            {"id": "missing", "ticker": "MISSING"},
+        ]
+        response = Mock()
+        response.json.return_value = {
+            "bitcoin": {"usd": 1234.56},
+            "ethereum": {"usd": 12.345},
+        }
+        with patch("matrixcrypto.app.requests.get", return_value=response) as get:
+            self.assertTrue(app.fetch_current_prices(cryptos))
+        self.assertEqual(get.call_args.kwargs["timeout"], 20)
+        self.assertEqual(cryptos[0]["price"], "1,235")
+        self.assertEqual(cryptos[1]["price"], "12.35")
+        self.assertNotIn("price", cryptos[2])
+
+    def test_api_error_clears_stale_price(self):
+        cryptos = [{"id": "bitcoin", "ticker": "BTC", "price": "10.00"}]
+        with patch("matrixcrypto.app.requests.get", side_effect=requests.Timeout):
+            self.assertFalse(app.fetch_current_prices(cryptos))
+        self.assertNotIn("price", cryptos[0])
+
+
+class ListUpdaterTests(unittest.TestCase):
+    def test_failed_request_does_not_overwrite_list(self):
+        with tempfile.TemporaryDirectory() as directory:
+            output = Path(directory) / "coins.json"
+            output.write_text("existing", encoding="utf-8")
+            with patch("matrixcrypto.lists.requests.get", side_effect=requests.Timeout):
+                self.assertEqual(lists.main(["--output", str(output)]), 1)
+            self.assertEqual(output.read_text(encoding="utf-8"), "existing")
+
+    def test_successful_request_writes_selected_ecosystem(self):
+        response = Mock()
+        response.json.return_value = [
+            {"id": "solana", "symbol": "sol", "name": "Solana"}
+        ]
+        with tempfile.TemporaryDirectory() as directory:
+            output = Path(directory) / "coins.json"
+            with patch("matrixcrypto.lists.requests.get", return_value=response) as get:
+                self.assertEqual(
+                    lists.main(["--ecosystem", "solana", "--output", str(output)]),
+                    0,
+                )
+            self.assertEqual(
+                get.call_args.kwargs["params"]["category"], "solana-ecosystem"
+            )
+            self.assertEqual(
+                json.loads(output.read_text())["cryptos"][0]["ticker"], "SOL"
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()