led-ticker-crypto 0.2.0__tar.gz

led_ticker_crypto-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.env

led_ticker_crypto-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright src
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]

led_ticker_crypto-0.2.0/CLAUDE.md

@@ -0,0 +1,185 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in **led-ticker-crypto**, an external plugin for
+[led-ticker](https://github.com/JamesAwesome/led-ticker).
+
+`README.md` is the source of truth for the user-facing surface (config options, install,
+coin-spec styles, rate limits). This file keeps the **load-bearing invariants** a contributor
+must respect, plus navigation aids. When a fact here and the README disagree about *how a
+feature works*, the README wins; this file is the source of truth for *how to keep it working*.
+
+## Overview
+
+This plugin contributes, via the `led_ticker.plugins` entry point, a single widget:
+
+- `crypto.coingecko` — live crypto price Container from the CoinGecko v3 API. Cycles one
+  `_CoinTicker` "story" per configured coin (the engine reads `feed_stories` via
+  `_expand_sources` on every pass). Shows symbol + price (adaptive precision) + 24h change,
+  trend-colored green/red/gray. One batched `/simple/price` fetch per update interval.
+
+The entry-point name `crypto` is the plugin namespace, so the config `type` is
+`crypto.coingecko` (see `register()` in `__init__.py`).
+
+## Commands
+
+led-ticker is **not on PyPI**; it resolves from a sibling checkout via
+`[tool.uv.sources] led-ticker = { path = "../led-ticker", editable = true }`. CI checks out
+`led-ticker` next to this repo using a read-only deploy key (`LED_TICKER_DEPLOY_KEY`). The
+rgbmatrix stub is vendored at the monorepo root (`tests/stubs/`) and put on the import path
+by the **root** `pyproject.toml` (pytest `pythonpath` + pyright `extraPaths`), so the stub is
+importable headless from the workspace root — no sibling `../led-ticker` path is involved.
+
+```bash
+uv sync --extra dev          # install deps (needs ../led-ticker checked out)
+uv run pytest -q             # full suite (asyncio_mode = "auto")
+make lint                    # lint (monorepo root); or: uv run ruff check plugins/crypto
+```
+
+Python **3.14+** only.
+
+## Package layout
+
+```
+src/led_ticker_crypto/
+  __init__.py         # register(api) → api.widget("coingecko")(CoinGeckoMonitor)
+  coingecko.py        # CoinGeckoMonitor (Container): start(), update(), _build_coins,
+                      #   _resolve_symbols; _CoinTicker: per-coin story with draw()
+  _ticker_render.py   # draw_price_ticker(): shared price-ticker renderer ported from core's
+                      #   coinbase widget; _format_price(); _ConstantColor; make_default_font_color
+  _colors.py          # UP_TREND_COLOR / DOWN_TREND_COLOR / NEUTRAL_TREND_COLOR via lazy_palette
+```
+
+`register(api)` (in `__init__.py`):
+
+```python
+def register(api):
+    api.widget("coingecko")(CoinGeckoMonitor)
+```
+
+## Load-bearing invariants
+
+Each rule must hold when modifying the named files.
+
+**Import only the public surface** — every `led_ticker` import MUST come from `led_ticker.plugin`,
+never `led_ticker.<internal>`. Enforced by `tests/test_import_purity.py`, which AST-walks every
+source file (catches `from`-imports *and* `import led_ticker.x` forms, not just a text grep).
+Intra-package imports (`from led_ticker_crypto._colors import …`) are fine. If you need a core
+symbol that isn't on `led_ticker.plugin.__all__`, that's a core API change — raise it upstream,
+don't reach around the surface.
+
+**Python 3.14 / PEP 649** — no `from __future__ import annotations` anywhere (same rule as core).
+Bare `tuple[int, int, int]` annotations are fine.
+
+**`CoinGeckoMonitor` is a Container** — it exposes `feed_stories: list[_CoinTicker]` (one story
+per coin). The engine reads `feed_stories` via `_expand_sources` on every pass through the
+section, so live updates surface within at most one cycle. A single-coin config produces a
+one-story container — the same code path, no special case. Never snapshot `feed_stories` into a
+cycle iterator at section build time; that was the longboi stale-display pattern.
+
+**`update()` uses ONE batched fetch with comma-joined ids** — multiple coin ids MUST be joined
+into a single `ids` string (`ids=bitcoin,ethereum,dogecoin`). Passing a Python list would make
+aiohttp emit repeated `ids=bitcoin&ids=ethereum` query parameters, which CoinGecko rejects for
+more than one id. The comment in `update()` documents this constraint explicitly; do not change
+the join to a list.
+
+**Non-200 responses raise** — `update()` logs a warning (including `retry-after` if present),
+then calls `response.raise_for_status()` so `run_monitor_loop`'s exponential backoff engages.
+A 429 or any error body must NEVER be parsed as price data. This handles the CoinGecko free-tier
+rate limit (~5 calls/min keyless) and any transient API error.
+
+**`_format_price` adaptive precision** — coins ≥ $1 (or exactly $0) use the historical
+`f"{value:,.4f}"` form (4 decimals, thousands-separated). Sub-dollar coins get extra decimals
+computed as `min(12, max(4, 3 - floor(log10(abs(value)))))` so a coin at ~$0.0000046 renders
+as `0.0000046` rather than collapsing to `0.0000`. Do not revert this to a fixed `.4f` format.
+
+**`symbols` auto-lookup is unique-or-error** — `_resolve_symbols` queries the full
+`/coins/list` response. For each requested symbol: exactly one match → `(symbol.upper(), id)`;
+zero matches → `ValueError`; multiple matches → `ValueError` listing all candidate ids and
+telling the user to set `symbol_id`/`symbol_ids` to disambiguate. Input order is preserved.
+The `/coins/list` fetch only happens when `symbols` is non-empty; `symbol_ids`-only configs
+skip it entirely.
+
+**`_build_coins` assembles and deduplicates** — order is: legacy `symbol`+`symbol_id` → each
+entry in `symbol_ids` → `symbols` (auto-resolved). Deduplication is by coin_id, keeping first
+occurrence. Raises if the result is empty (the same message as `validate_config`).
+
+**Optional `x-cg-demo-api-key` header** — `api_key` is sourced from the TOML field first, then
+falls back to the `COINGECKO_API_KEY` environment variable (`os.getenv`). When non-empty, the
+key is sent as `x-cg-demo-api-key` in all CoinGecko requests (both the `/coins/list` startup
+fetch and the per-update `/simple/price` fetch). When empty, no key header is sent. No key is
+required for a single low-frequency widget.
+
+**`font_color` plumbing in `coingecko.py`** — `_CoinTicker.__attrs_post_init__` normalises the
+raw config value: `None` → `make_default_font_color()` (yellow `_ConstantColor`); a plain
+`Color` (not a `ColorProvider`) → `_ConstantColor(color)`. After `__attrs_post_init__`,
+`self.font_color` is always a `ColorProvider`. `draw()` passes `frame_for("font_color")` so
+animated providers (rainbow, shimmer) animate across engine ticks. The 24h change segment uses
+`_get_change_color` and ignores `font_color`; this is intentional — change is always
+trend-colored.
+
+**One INFO log per successful `update()`** — the Container contract: a silent log stream after
+startup signals the background task died. `update()` emits one INFO line per call showing
+updated/total counts and the coin ids — never the raw API response.
+
+**`start()` accepts `update_interval`** — this parameter is consumed by `start()` before the
+`attrs` constructor, so it does NOT appear in `attrs.fields(cls)` and is filtered out of the
+`**kwargs` forwarding. Any future parameter that belongs to the monitor lifecycle (not the
+widget state) should follow the same pattern: accept in `start()`, don't pass through to
+`cls(...)`.
+
+**This is a faithful port of core's CoinGecko renderer** — `_ticker_render.draw_price_ticker`
+was ported from `led_ticker.widgets.crypto.coinbase._draw_price_ticker` (coinbase was removed
+from core; the renderer traveled with this plugin). Pixel-identity to the original was proven
+during extraction (see PR history); `tools/compare_render.py` served that one-time validation
+purpose and was retired after core's renderer was removed in led-ticker#188. Do not change
+rendering logic in `_ticker_render.py` without confirming the diff is intentional.
+
+**Port adaptations in `_ticker_render.py`** — these are deliberate, documented deviations from
+how the original code was written that must NOT be reverted:
+
+- `draw_text` is called in the public absolute-return form:
+  `cursor_pos = draw_text(canvas, font, text, x, y, color)` — not the core-internal
+  `cursor_pos += draw_text(...)` form. The result is pixel-identical for plain text.
+- `compute_cursor`'s `center` parameter is keyword-only at the call site.
+- The default `font_color` is yellow `(255, 255, 0)`, matching core's `DEFAULT_COLOR`.
+- `_ConstantColor` is a local reproduction of core's private class (which is not on the public
+  surface). It wraps a plain `Color` so a `font_color = [r,g,b]` config routes through the same
+  `color_for` interface as effect providers.
+
+**Font constants** — `FONT_LABEL` (`7x13`) and `FONT_DELTA` (`6x10`) are resolved once at import
+via `resolve_font`. `FONT_VALUE` and `FONT_VALUE_SMALL` alias `FONT_DEFAULT` / `FONT_SMALL` from
+`led_ticker.plugin` — these are BDF faces (`6x12` / `5x8`). The price font auto-downgrades to
+`FONT_VALUE_SMALL` when the price string exceeds 10 characters (long decimals and large values).
+
+**Trend palette is lazy** — `_colors.py` uses `colors.lazy_palette` (PEP 562 `__getattr__`),
+so importing the module is a no-op against the rgbmatrix `graphics` library. In-module code
+(e.g. inside `_ticker_render.py`) accesses them as module-level names
+(`UP_TREND_COLOR`, `DOWN_TREND_COLOR`, `NEUTRAL_TREND_COLOR`), which triggers the lazy resolver
+on first access. Do not call `_trend_palette(name)` directly from outside `_colors.py`.
+
+## Tests / CI
+
+`uv run pytest -q` runs the suite (`tests/`):
+
+- `test_import_purity.py` — AST tripwire (public-surface-only). Treat a failure as a contract
+  violation, not a test to relax.
+- `test_smoke.py` — loads the plugin through led-ticker's real plugin loader and asserts
+  `crypto.coingecko` registers under the `crypto` namespace (entry-point wiring guard).
+- `test_coingecko.py` — behavior coverage: price formatting, change coloring, `font_color`
+  normalization, `draw()` routing, `update()` logging contract, multi-coin batching, symbol
+  resolution, rate-limit error handling.
+
+`tools/compare_render.py` — standalone comparison tool used during extraction to assert pixel
+identity between the ported renderer and core's original. Retired after core's renderer was
+removed in led-ticker#188; see PR history for the comparison baseline.
+
+CI is the monorepo's single root path-filtered per-member matrix (`.github/workflows/ci.yml`):
+it checks out led-ticker as a sibling (deploy key), Python 3.14, `uv sync --extra dev`, then
+runs ruff check, ruff format --check, pyright, and pytest for the changed member.
+
+## Adding to the plugin
+
+Register the class in `register()` in `__init__.py` (`api.widget`); it becomes `crypto.<name>`.
+Import any core dependency from `led_ticker.plugin` only, and keep the import-purity test green.
+If the new widget shares the price-ticker layout (symbol + price + change), reuse
+`_ticker_render.draw_price_ticker` rather than duplicating the draw logic.

led_ticker_crypto-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Awesome
+
+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.

led_ticker_crypto-0.2.0/Makefile

@@ -0,0 +1,18 @@
+.PHONY: dev test lint format typecheck
+
+dev:  ## Install dev deps + pre-commit hooks
+	uv sync --extra dev
+	uv run pre-commit install
+	uv run pre-commit install --hook-type pre-push
+
+test:  ## Run tests with coverage
+	uv run pytest --cov=src --cov-report=term-missing
+
+lint:  ## Ruff lint
+	uv run ruff check src tests
+
+format:  ## Ruff format
+	uv run ruff format src tests
+
+typecheck:  ## Pyright
+	uv run pyright src

led_ticker_crypto-0.2.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: led-ticker-crypto
+Version: 0.2.0
+Summary: Crypto-price widgets for led-ticker (CoinGecko).
+Project-URL: Homepage, https://docs.ledticker.dev
+Project-URL: Repository, https://github.com/JamesAwesome/led-ticker-plugins
+Project-URL: Issues, https://github.com/JamesAwesome/led-ticker-plugins/issues
+Author-email: James Awesome <james@morelli.nyc>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.14
+Requires-Dist: aiohttp
+Requires-Dist: led-ticker-core>=2.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# led-ticker-crypto
+
+A cryptocurrency price ticker **plugin** for [led-ticker](https://github.com/JamesAwesome/led-ticker), backed by the free CoinGecko v3 API. It contributes a `crypto.coingecko` **Container widget** that cycles one scrolling price line per configured coin — configure one coin for a single ticker, or a list to cycle through several.
+
+Each line shows the coin symbol, current price (adaptive precision — sub-dollar tokens never collapse to `0.0000`), and 24-hour percent change. The change value is trend-colored: green for positive, red for negative, gray for neutral — readable at a glance on any panel.
+
+![crypto.coingecko cycling BTC, ETH, and SHIB (note the sub-cent SHIB price)](docs/crypto-coingecko.gif)
+
+## Prerequisites
+
+- A working [led-ticker](https://github.com/JamesAwesome/led-ticker) install.
+- Internet access on the Pi (the widget calls the CoinGecko public API).
+
+## Install
+
+The widget auto-registers via the `led_ticker.plugins` entry point — once the package is installed, no `[plugins]` config change is needed.
+
+**Into a containerized led-ticker (recommended):** add this package to `config/requirements-plugins.txt` (copy it from `config/requirements-plugins.example.txt`, which already lists it), then rebuild:
+
+```bash
+# in your led-ticker checkout
+cp config/requirements-plugins.example.txt config/requirements-plugins.txt
+docker compose up -d --build
+```
+
+That example file lists every first-party plugin — trim the live copy to just the ones you want. The crypto line is:
+
+```text
+git+https://github.com/JamesAwesome/led-ticker-crypto.git@main
+```
+
+**Standalone (a venv that already has led-ticker):**
+
+```bash
+pip install "git+https://github.com/JamesAwesome/led-ticker-crypto.git@main"
+```
+
+led-ticker isn't on PyPI, so this path only works where led-ticker is already installed. See the led-ticker [Plugins docs](https://docs.ledticker.dev/plugins/) for the constraint-based install the Docker image uses.
+
+## Configuration
+
+Reference the widget in a playlist section by `type = "crypto.coingecko"`. Three coin-spec styles are supported — choose the one that fits your workflow:
+
+### Single coin (legacy style)
+
+```toml
+[[playlist.section.widget]]
+type = "crypto.coingecko"
+symbol = "BTC"
+symbol_id = "bitcoin"
+currency = "USD"
+```
+
+### Multiple coins by explicit CoinGecko id
+
+```toml
+[[playlist.section.widget]]
+type = "crypto.coingecko"
+symbol_ids = ["bitcoin", "ethereum", "dogecoin"]
+currency = "USD"
+```
+
+Each id in `symbol_ids` is also used as the on-panel label (uppercased). Use `symbol_ids` when you know the exact CoinGecko ids and want to skip the startup lookup.
+
+### Multiple coins by ticker symbol (auto-resolved)
+
+```toml
+[[playlist.section.widget]]
+type = "crypto.coingecko"
+symbols = ["BTC", "ETH", "SOL"]
+currency = "USD"
+```
+
+`symbols` are resolved at startup against CoinGecko's `/coins/list` endpoint. Resolution is **unique-or-error**: if a symbol matches more than one CoinGecko id, the widget fails at startup and lists the candidate ids — use `symbol_id` or `symbol_ids` to disambiguate.
+
+You can combine all three styles in one widget; duplicates (by coin id) are silently dropped, keeping the first occurrence.
+
+New to led-ticker configs? The [first-config tutorial](https://docs.ledticker.dev/tutorial/02-first-config/) walks through the overall structure — the blocks above show just the crypto-specific keys.
+
+### Finding `symbol_id`
+
+`symbol_id` is CoinGecko's internal coin identifier (e.g. `"bitcoin"`, `"ethereum"`, `"solana"`, `"dogecoin"`). It's the `id` field in CoinGecko's `/coins/list` endpoint and appears in a coin's page URL: `coingecko.com/en/coins/<id>`.
+
+Use `symbol_id` (or `symbol_ids`) when:
+- You want to skip the startup `/coins/list` lookup that `symbols` triggers.
+- A symbol is ambiguous — the startup error lists the candidates and tells you which ids to use.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `symbol` | string | — | Single-coin label shown on the panel (e.g. `"BTC"`). Requires `symbol_id`. |
+| `symbol_id` | string | — | Single-coin CoinGecko id (e.g. `"bitcoin"`). Requires `symbol`. |
+| `symbols` | list of strings | — | Ticker symbols auto-resolved to CoinGecko ids at startup (e.g. `["BTC", "ETH"]`). Unique-or-error. |
+| `symbol_ids` | list of strings | — | CoinGecko ids used directly, uppercased as panel labels (e.g. `["bitcoin", "ethereum"]`). |
+| `currency` | string | `"USD"` | Fiat currency code (e.g. `"USD"`, `"EUR"`). |
+| `update_interval` | int | `300` | Seconds between CoinGecko fetches (5 min default). |
+| `center` | bool | `true` | Center the ticker on the canvas when it fits; scroll when it overflows. |
+| `padding` | int | `6` | Horizontal spacing (logical px) between the symbol, price, and change segments. |
+| `hold_time` | float | `0.0` | Seconds to hold each coin's ticker before the engine cycles to the next. |
+| `bg_color` | `[r,g,b]` | none | Background fill behind the ticker. |
+| `font_color` | `[r,g,b]` / string / table | yellow `(255,255,0)` | Color for the symbol and price. Accepts any led-ticker color provider (e.g. `"rainbow"`, `{style="shimmer", ...}`). The 24h change color is always trend-colored and ignores this field. |
+
+At least one of `symbol`+`symbol_id`, `symbols`, or `symbol_ids` must be specified — the widget fails at config validation otherwise.
+
+### Rate limits & API key
+
+CoinGecko's keyless free tier allows roughly **5 requests per minute**. For a single low-frequency widget at the default 5-minute interval this is plenty; if you add more coins or shorten `update_interval`, you may hit HTTP 429. When that happens the widget logs the rate-limit clearly and lets its monitor loop back off — it will not show stale garbage.
+
+To raise the limit, create a free account at [coingecko.com](https://www.coingecko.com) and get a **Demo API key** (no credit card required). Supply it via the `COINGECKO_API_KEY` environment variable (the only supported path — config-file secrets are intentionally not accepted):
+
+```bash
+export COINGECKO_API_KEY="CG-xxxxxxxxxxxxxxxxxxxx"
+```
+
+The key is sent as the `x-cg-demo-api-key` request header.
+
+## Development
+
+led-ticker isn't on PyPI, so this plugin resolves it from a sibling checkout. Clone both side by side:
+
+```
+~/projects/.../led-ticker
+~/projects/.../led-ticker-crypto
+```
+
+```bash
+uv sync --extra dev      # resolves led-ticker from ../led-ticker
+uv run pytest -q
+uv run ruff check src tests
+```
+
+> **Note:** led-ticker's `graphics` surface works headless via its bundled stub, but the full `RGBMatrix`/canvas test stub lives in led-ticker's `tests/stubs/` and isn't shipped. This repo's tests put it on the path via `pyproject.toml`'s `[tool.pytest.ini_options] pythonpath = ["../led-ticker/tests/stubs"]`.
+
+The plugin imports only the public `led_ticker.plugin` surface — `tests/test_import_purity.py` enforces it.
+
+## Links
+
+- [led-ticker](https://github.com/JamesAwesome/led-ticker) — the core project
+- [Docs site](https://docs.ledticker.dev) · [Plugin system](https://docs.ledticker.dev/plugins/)

led_ticker_crypto-0.2.0/README.md

@@ -0,0 +1,140 @@
+# led-ticker-crypto
+
+A cryptocurrency price ticker **plugin** for [led-ticker](https://github.com/JamesAwesome/led-ticker), backed by the free CoinGecko v3 API. It contributes a `crypto.coingecko` **Container widget** that cycles one scrolling price line per configured coin — configure one coin for a single ticker, or a list to cycle through several.
+
+Each line shows the coin symbol, current price (adaptive precision — sub-dollar tokens never collapse to `0.0000`), and 24-hour percent change. The change value is trend-colored: green for positive, red for negative, gray for neutral — readable at a glance on any panel.
+
+![crypto.coingecko cycling BTC, ETH, and SHIB (note the sub-cent SHIB price)](docs/crypto-coingecko.gif)
+
+## Prerequisites
+
+- A working [led-ticker](https://github.com/JamesAwesome/led-ticker) install.
+- Internet access on the Pi (the widget calls the CoinGecko public API).
+
+## Install
+
+The widget auto-registers via the `led_ticker.plugins` entry point — once the package is installed, no `[plugins]` config change is needed.
+
+**Into a containerized led-ticker (recommended):** add this package to `config/requirements-plugins.txt` (copy it from `config/requirements-plugins.example.txt`, which already lists it), then rebuild:
+
+```bash
+# in your led-ticker checkout
+cp config/requirements-plugins.example.txt config/requirements-plugins.txt
+docker compose up -d --build
+```
+
+That example file lists every first-party plugin — trim the live copy to just the ones you want. The crypto line is:
+
+```text
+git+https://github.com/JamesAwesome/led-ticker-crypto.git@main
+```
+
+**Standalone (a venv that already has led-ticker):**
+
+```bash
+pip install "git+https://github.com/JamesAwesome/led-ticker-crypto.git@main"
+```
+
+led-ticker isn't on PyPI, so this path only works where led-ticker is already installed. See the led-ticker [Plugins docs](https://docs.ledticker.dev/plugins/) for the constraint-based install the Docker image uses.
+
+## Configuration
+
+Reference the widget in a playlist section by `type = "crypto.coingecko"`. Three coin-spec styles are supported — choose the one that fits your workflow:
+
+### Single coin (legacy style)
+
+```toml
+[[playlist.section.widget]]
+type = "crypto.coingecko"
+symbol = "BTC"
+symbol_id = "bitcoin"
+currency = "USD"
+```
+
+### Multiple coins by explicit CoinGecko id
+
+```toml
+[[playlist.section.widget]]
+type = "crypto.coingecko"
+symbol_ids = ["bitcoin", "ethereum", "dogecoin"]
+currency = "USD"
+```
+
+Each id in `symbol_ids` is also used as the on-panel label (uppercased). Use `symbol_ids` when you know the exact CoinGecko ids and want to skip the startup lookup.
+
+### Multiple coins by ticker symbol (auto-resolved)
+
+```toml
+[[playlist.section.widget]]
+type = "crypto.coingecko"
+symbols = ["BTC", "ETH", "SOL"]
+currency = "USD"
+```
+
+`symbols` are resolved at startup against CoinGecko's `/coins/list` endpoint. Resolution is **unique-or-error**: if a symbol matches more than one CoinGecko id, the widget fails at startup and lists the candidate ids — use `symbol_id` or `symbol_ids` to disambiguate.
+
+You can combine all three styles in one widget; duplicates (by coin id) are silently dropped, keeping the first occurrence.
+
+New to led-ticker configs? The [first-config tutorial](https://docs.ledticker.dev/tutorial/02-first-config/) walks through the overall structure — the blocks above show just the crypto-specific keys.
+
+### Finding `symbol_id`
+
+`symbol_id` is CoinGecko's internal coin identifier (e.g. `"bitcoin"`, `"ethereum"`, `"solana"`, `"dogecoin"`). It's the `id` field in CoinGecko's `/coins/list` endpoint and appears in a coin's page URL: `coingecko.com/en/coins/<id>`.
+
+Use `symbol_id` (or `symbol_ids`) when:
+- You want to skip the startup `/coins/list` lookup that `symbols` triggers.
+- A symbol is ambiguous — the startup error lists the candidates and tells you which ids to use.
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `symbol` | string | — | Single-coin label shown on the panel (e.g. `"BTC"`). Requires `symbol_id`. |
+| `symbol_id` | string | — | Single-coin CoinGecko id (e.g. `"bitcoin"`). Requires `symbol`. |
+| `symbols` | list of strings | — | Ticker symbols auto-resolved to CoinGecko ids at startup (e.g. `["BTC", "ETH"]`). Unique-or-error. |
+| `symbol_ids` | list of strings | — | CoinGecko ids used directly, uppercased as panel labels (e.g. `["bitcoin", "ethereum"]`). |
+| `currency` | string | `"USD"` | Fiat currency code (e.g. `"USD"`, `"EUR"`). |
+| `update_interval` | int | `300` | Seconds between CoinGecko fetches (5 min default). |
+| `center` | bool | `true` | Center the ticker on the canvas when it fits; scroll when it overflows. |
+| `padding` | int | `6` | Horizontal spacing (logical px) between the symbol, price, and change segments. |
+| `hold_time` | float | `0.0` | Seconds to hold each coin's ticker before the engine cycles to the next. |
+| `bg_color` | `[r,g,b]` | none | Background fill behind the ticker. |
+| `font_color` | `[r,g,b]` / string / table | yellow `(255,255,0)` | Color for the symbol and price. Accepts any led-ticker color provider (e.g. `"rainbow"`, `{style="shimmer", ...}`). The 24h change color is always trend-colored and ignores this field. |
+
+At least one of `symbol`+`symbol_id`, `symbols`, or `symbol_ids` must be specified — the widget fails at config validation otherwise.
+
+### Rate limits & API key
+
+CoinGecko's keyless free tier allows roughly **5 requests per minute**. For a single low-frequency widget at the default 5-minute interval this is plenty; if you add more coins or shorten `update_interval`, you may hit HTTP 429. When that happens the widget logs the rate-limit clearly and lets its monitor loop back off — it will not show stale garbage.
+
+To raise the limit, create a free account at [coingecko.com](https://www.coingecko.com) and get a **Demo API key** (no credit card required). Supply it via the `COINGECKO_API_KEY` environment variable (the only supported path — config-file secrets are intentionally not accepted):
+
+```bash
+export COINGECKO_API_KEY="CG-xxxxxxxxxxxxxxxxxxxx"
+```
+
+The key is sent as the `x-cg-demo-api-key` request header.
+
+## Development
+
+led-ticker isn't on PyPI, so this plugin resolves it from a sibling checkout. Clone both side by side:
+
+```
+~/projects/.../led-ticker
+~/projects/.../led-ticker-crypto
+```
+
+```bash
+uv sync --extra dev      # resolves led-ticker from ../led-ticker
+uv run pytest -q
+uv run ruff check src tests
+```
+
+> **Note:** led-ticker's `graphics` surface works headless via its bundled stub, but the full `RGBMatrix`/canvas test stub lives in led-ticker's `tests/stubs/` and isn't shipped. This repo's tests put it on the path via `pyproject.toml`'s `[tool.pytest.ini_options] pythonpath = ["../led-ticker/tests/stubs"]`.
+
+The plugin imports only the public `led_ticker.plugin` surface — `tests/test_import_purity.py` enforces it.
+
+## Links
+
+- [led-ticker](https://github.com/JamesAwesome/led-ticker) — the core project
+- [Docs site](https://docs.ledticker.dev) · [Plugin system](https://docs.ledticker.dev/plugins/)

led_ticker_crypto-0.2.0/docs/demo.toml

@@ -0,0 +1,20 @@
+# render-duration: 18
+# Demo config for the crypto.coingecko widget (multi-coin ticker).
+# Explicit symbol_ids for a deterministic render; shiba-inu showcases the
+# adaptive sub-cent price formatting.
+[display]
+rows = 16
+cols = 32
+chain_length = 5
+default_scale = 1
+brightness = 60
+
+[[playlist.section]]
+mode = "swap"
+loop_count = 1
+hold_time = 3.0
+
+[[playlist.section.widget]]
+type = "crypto.coingecko"
+symbol_ids = ["bitcoin", "ethereum", "shiba-inu"]
+currency = "USD"