led-ticker-crypto 0.2.0__py3-none-any.whl

led_ticker_crypto/__init__.py

@@ -0,0 +1,7 @@
+"""led-ticker-crypto: crypto-price widgets for led-ticker (CoinGecko)."""
+
+from led_ticker_crypto.coingecko import CoinGeckoMonitor
+
+
+def register(api):
+    api.widget("coingecko")(CoinGeckoMonitor)

led_ticker_crypto/_colors.py

@@ -0,0 +1,26 @@
+"""Trend colors for crypto widgets (ported from led-ticker core crypto/_colors.py).
+
+Positive / negative / neutral price movement. Constructed lazily via PEP 562
+`__getattr__` (same pattern as core), so importing this module is a no-op
+against the rgbmatrix graphics library.
+"""
+
+from typing import TYPE_CHECKING
+
+from led_ticker.plugin import colors
+
+if TYPE_CHECKING:
+    from led_ticker.plugin import Color
+
+
+_trend_palette = colors.lazy_palette(
+    {
+        "UP_TREND_COLOR": (46, 200, 46),
+        "DOWN_TREND_COLOR": (194, 24, 7),
+        "NEUTRAL_TREND_COLOR": (180, 180, 180),
+    }
+)
+
+
+def __getattr__(name: str) -> Color:
+    return _trend_palette(name)

led_ticker_crypto/_ticker_render.py

@@ -0,0 +1,142 @@
+"""Shared price-ticker renderer for crypto widgets.
+
+Ported from led-ticker core's `widgets/crypto/coinbase._draw_price_ticker`
+(coinbase was removed from core; the renderer travels with the plugin).
+Lives as a shared module so a future `crypto.coinbase` could reuse it.
+
+Adapted to the public `led_ticker.plugin` surface: the public `draw_text`
+returns the ABSOLUTE next-x (and routes inline emoji), so core's
+`cursor_pos += draw_text(canvas, font, x, y, color, text)` became
+`cursor_pos = draw_text(canvas, font, text, x, y, color)` — pixel-identical
+for plain text (proven by the led-ticker-baseball migration).
+"""
+
+import math
+
+from led_ticker.plugin import (
+    FONT_DEFAULT,
+    FONT_SMALL,
+    Canvas,
+    Color,
+    ColorProvider,
+    ColorProviderBase,
+    DrawResult,
+    Font,
+    compute_baseline,
+    compute_cursor,
+    draw_text,
+    get_text_width,
+    make_color,
+    resolve_font,
+)
+
+from led_ticker_crypto._colors import (
+    DOWN_TREND_COLOR,
+    NEUTRAL_TREND_COLOR,
+    UP_TREND_COLOR,
+)
+
+# Core FONT_VALUE/FONT_VALUE_SMALL == 6x12/5x8 (FONT_DEFAULT/FONT_SMALL);
+# FONT_LABEL/FONT_DELTA are the general 7x13/6x10 BDF faces.
+FONT_LABEL: Font = resolve_font("7x13")
+FONT_VALUE: Font = FONT_DEFAULT
+FONT_VALUE_SMALL: Font = FONT_SMALL
+FONT_DELTA: Font = resolve_font("6x10")
+
+
+class _ConstantColor(ColorProviderBase):
+    """Wraps a single Color so a plain `font_color = [r,g,b]` routes through
+    the same `color_for` interface as effects. (Core's _ConstantColor is private.)"""
+
+    per_char: bool = False
+    frame_invariant: bool = True
+
+    def __init__(self, color: Color) -> None:
+        self._color = color
+
+    def color_for(self, frame: int, char_index: int, total_chars: int) -> Color:
+        return self._color
+
+
+def make_default_font_color() -> ColorProvider:
+    """Core's default font_color: DEFAULT_COLOR == (255, 255, 0) (yellow)."""
+    return _ConstantColor(make_color(255, 255, 0))
+
+
+def _get_change_color(change_str: str) -> Color:
+    try:
+        value = float(change_str.rstrip("%"))
+    except ValueError, AttributeError:
+        return NEUTRAL_TREND_COLOR
+    if value < 0:
+        return DOWN_TREND_COLOR
+    if value > 0:
+        return UP_TREND_COLOR
+    return NEUTRAL_TREND_COLOR
+
+
+def _get_price_font(price_str: str) -> Font:
+    if len(price_str) > 10:
+        return FONT_VALUE_SMALL
+    return FONT_VALUE
+
+
+def _format_price(value: float) -> str:
+    """Format a price with adaptive precision.
+
+    Normal coins (>= 1) keep the historical 4-decimal, thousands-separated form.
+    Sub-dollar coins get extra decimals so cheap tokens (e.g. SHIB ~4.6e-06)
+    don't collapse to "0.0000".
+    """
+    if value >= 1 or value == 0:
+        return f"{value:,.4f}"
+    decimals = min(12, max(4, 3 - int(math.floor(math.log10(abs(value))))))
+    return f"{value:.{decimals}f}"
+
+
+def draw_price_ticker(
+    canvas: Canvas,
+    symbol: str,
+    price_str: str,
+    change_str: str,
+    cursor_pos: int = 0,
+    center: bool = True,
+    padding: int = 6,
+    end_padding: int = 6,
+    y_offset: int = 0,
+    font_color: ColorProvider | None = None,
+    frame_count: int = 0,
+) -> DrawResult:
+    change_color = _get_change_color(change_str)
+    font_price = _get_price_font(price_str)
+    label_color = (
+        font_color.color_for(frame_count, 0, 1)
+        if font_color is not None
+        else make_color(255, 255, 0)
+    )
+
+    content_width = (
+        get_text_width(FONT_LABEL, symbol, padding=6, canvas=canvas)
+        + get_text_width(font_price, price_str, padding=6, canvas=canvas)
+        + get_text_width(FONT_DELTA, change_str, padding=0, canvas=canvas)
+    )
+
+    cursor_pos, end_padding = compute_cursor(
+        canvas.width, content_width, cursor_pos, end_padding, center=center
+    )
+
+    baseline_y = compute_baseline(FONT_LABEL, canvas, valign="center") + y_offset
+    cursor_pos = draw_text(
+        canvas, FONT_LABEL, symbol, cursor_pos, baseline_y, label_color
+    )
+    cursor_pos += padding
+    cursor_pos = draw_text(
+        canvas, font_price, price_str, cursor_pos, baseline_y, label_color
+    )
+    cursor_pos += padding
+    cursor_pos = draw_text(
+        canvas, FONT_DELTA, change_str, cursor_pos, baseline_y, change_color
+    )
+    cursor_pos += end_padding
+
+    return canvas, cursor_pos

led_ticker_crypto/coingecko.py

@@ -0,0 +1,338 @@
+"""CoinGecko price monitor widget (crypto.coingecko).
+
+`CoinGeckoMonitor` is a Container: it cycles one `_CoinTicker` "story" per
+configured coin (each reusing the pixel-validated `draw_price_ticker`). The
+container does ONE batched `/simple/price` fetch per update and routes each
+coin's price into its story. Symbols can be auto-resolved to CoinGecko ids
+(unique-or-error), and an optional demo API key raises the free-tier limit.
+"""
+
+import logging
+import os
+from typing import Any, Self
+
+import aiohttp
+import attrs
+from led_ticker.plugin import (
+    Canvas,
+    Color,
+    ColorProvider,
+    DrawResult,
+    FrameAwareBase,
+    run_monitor_loop,
+    spawn_tracked,
+)
+
+from led_ticker_crypto._ticker_render import (
+    _ConstantColor,
+    _format_price,
+    draw_price_ticker,
+    make_default_font_color,
+)
+
+COINGECKO_API: str = "https://api.coingecko.com/api/v3"
+COINGECKO_COIN_LIST: str = f"{COINGECKO_API}/coins/list"
+COINGECKO_PRICE_API: str = f"{COINGECKO_API}/simple/price"
+
+
+@attrs.define
+class _CoinTicker(FrameAwareBase):
+    """One coin's price line — a Container "story" drawn via draw_price_ticker."""
+
+    symbol: str
+    center: bool = True
+    padding: int = 6
+    hold_time: float = 0.0
+    bg_color: Color | None = attrs.field(default=None, kw_only=True)
+    font_color: Color | ColorProvider = attrs.field(default=None, kw_only=True)
+    price_data: dict[str, str] = attrs.field(
+        init=False,
+        factory=lambda: {"price": "0.0000", "change_24h": "0.00%"},
+    )
+
+    def __attrs_post_init__(self) -> None:
+        if self.font_color is None:
+            self.font_color = make_default_font_color()
+        elif not hasattr(self.font_color, "color_for"):
+            self.font_color = _ConstantColor(self.font_color)
+
+    def draw(
+        self,
+        canvas: Canvas,
+        cursor_pos: int = 0,
+        *,
+        y_offset: int = 0,
+        font_color: Any = None,
+    ) -> DrawResult:
+        return draw_price_ticker(
+            canvas,
+            self.symbol,
+            self.price_data["price"],
+            self.price_data["change_24h"],
+            cursor_pos=cursor_pos,
+            center=self.center,
+            padding=self.padding,
+            end_padding=self.padding,
+            y_offset=y_offset,
+            font_color=self.font_color,
+            frame_count=self.frame_for("font_color"),
+        )
+
+
+def _resolve_symbols(
+    symbols: list[str], coin_list: list[dict[str, Any]]
+) -> list[tuple[str, str]]:
+    """Resolve display symbols to CoinGecko ids (unique-or-error).
+
+    For each symbol (case-insensitive on `coin_meta["symbol"]`):
+    exactly one match → `(symbol.upper(), id)`; zero → ValueError;
+    multiple → ValueError listing all candidate ids and telling the user
+    to set `symbol_id`/`symbol_ids` explicitly. Input order preserved.
+    """
+    resolved: list[tuple[str, str]] = []
+    for symbol in symbols:
+        matches = [
+            coin_meta["id"]
+            for coin_meta in coin_list
+            if coin_meta["symbol"].lower() == symbol.lower()
+        ]
+        if len(matches) == 1:
+            resolved.append((symbol.upper(), matches[0]))
+        elif not matches:
+            raise ValueError(f"symbol {symbol!r} not found on CoinGecko")
+        else:
+            candidates = ", ".join(matches)
+            raise ValueError(
+                f"symbol {symbol!r} is ambiguous on CoinGecko "
+                f"(candidate ids: {candidates}); set symbol_id or symbol_ids "
+                f"explicitly to disambiguate"
+            )
+    return resolved
+
+
+def _build_coins(
+    symbol: str | None,
+    symbol_id: str | None,
+    symbols: list[str] | None,
+    symbol_ids: list[str] | None,
+    coin_list: list[dict[str, Any]] | None,
+) -> list[tuple[str, str]]:
+    """Assemble an ordered, de-duplicated `(display_symbol, coin_id)` list.
+
+    Order: legacy `symbol`+`symbol_id` → each `symbol_ids` entry →
+    `symbols` (auto-resolved). De-duplicate by coin_id (keep first).
+    Raise if the result is empty.
+    """
+    coins: list[tuple[str, str]] = []
+    if symbol and symbol_id:
+        coins.append((symbol.upper(), symbol_id))
+    for cid in symbol_ids or []:
+        coins.append((cid.upper(), cid))
+    if symbols:
+        coins.extend(_resolve_symbols(symbols, coin_list or []))
+
+    seen: set[str] = set()
+    deduped: list[tuple[str, str]] = []
+    for display, cid in coins:
+        if cid in seen:
+            continue
+        seen.add(cid)
+        deduped.append((display, cid))
+
+    if not deduped:
+        raise ValueError(
+            "crypto.coingecko: specify at least one of symbol/symbol_id, "
+            "symbol_ids, or symbols"
+        )
+    return deduped
+
+
+@attrs.define
+class CoinGeckoMonitor:
+    """Crypto price Container cycling one _CoinTicker per coin (CoinGecko API)."""
+
+    coins: list[tuple[str, str]]
+    currency: str
+    session: aiohttp.ClientSession
+    center: bool = True
+    padding: int = 6
+    hold_time: float = 0.0
+    bg_color: Color | None = attrs.field(default=None, kw_only=True)
+    font_color: Color | ColorProvider = attrs.field(default=None, kw_only=True)
+    api_key: str = attrs.field(
+        factory=lambda: os.getenv("COINGECKO_API_KEY", ""), kw_only=True
+    )
+    feed_title: None = attrs.field(init=False, default=None)
+    feed_stories: list[_CoinTicker] = attrs.field(init=False, factory=list)
+    _story_by_id: dict = attrs.field(init=False, factory=dict)
+
+    def __attrs_post_init__(self) -> None:
+        self.feed_stories = [
+            _CoinTicker(
+                symbol=display,
+                center=self.center,
+                padding=self.padding,
+                hold_time=self.hold_time,
+                bg_color=self.bg_color,
+                font_color=self.font_color,
+            )
+            for display, _ in self.coins
+        ]
+        self._story_by_id = {
+            cid: story
+            for (_, cid), story in zip(self.coins, self.feed_stories, strict=True)
+        }
+
+    @classmethod
+    def validate_config(cls, cfg: dict[str, Any]) -> list[str]:
+        """Pre-coercion config check, run by the engine via validate_widget_cfg.
+
+        Returns message strings (does NOT raise); the engine turns any returned
+        messages into a pre-flight ValueError.
+        """
+        msgs: list[str] = []
+
+        has_legacy = bool(cfg.get("symbol") or cfg.get("symbol_id"))
+        has_symbols = bool(cfg.get("symbols"))
+        has_symbol_ids = bool(cfg.get("symbol_ids"))
+
+        if not (has_legacy or has_symbols or has_symbol_ids):
+            msgs.append(
+                "crypto.coingecko: specify at least one coin via "
+                "symbol+symbol_id, symbol_ids, or symbols"
+            )
+            return msgs
+
+        if has_symbols:
+            symbols = cfg["symbols"]
+            if not (
+                isinstance(symbols, list)
+                and all(isinstance(s, str) and s for s in symbols)
+            ):
+                msgs.append(
+                    "crypto.coingecko: symbols must be a non-empty list of strings"
+                )
+
+        if has_symbol_ids:
+            symbol_ids = cfg["symbol_ids"]
+            if not (
+                isinstance(symbol_ids, list)
+                and all(isinstance(s, str) and s for s in symbol_ids)
+            ):
+                msgs.append(
+                    "crypto.coingecko: symbol_ids must be a non-empty list of strings"
+                )
+
+        return msgs
+
+    def _headers(self) -> dict[str, str]:
+        return {"x-cg-demo-api-key": self.api_key} if self.api_key else {}
+
+    @classmethod
+    async def start(
+        cls,
+        *,
+        currency: str = "USD",
+        symbol: str | None = None,
+        symbol_id: str | None = None,
+        symbols: list[str] | None = None,
+        symbol_ids: list[str] | None = None,
+        session: aiohttp.ClientSession,
+        update_interval: int = 300,
+        **kwargs: Any,
+    ) -> Self:
+        api_key = os.getenv("COINGECKO_API_KEY", "")
+        headers = {"x-cg-demo-api-key": api_key} if api_key else {}
+        coin_list = (
+            await _get_coingecko_coin_list(session, headers=headers)
+            if symbols
+            else None
+        )
+        coins = _build_coins(symbol, symbol_id, symbols, symbol_ids, coin_list)
+
+        valid = {f.name for f in attrs.fields(cls)}
+        widget = cls(
+            coins=coins,
+            currency=currency,
+            session=session,
+            # api_key never comes from config — env (COINGECKO_API_KEY) only
+            **{k: v for k, v in kwargs.items() if k in valid and k != "api_key"},
+        )
+        # Tolerate a failed INITIAL price fetch (e.g. a CoinGecko 429 at boot)
+        # so the widget still constructs and the monitor loop can recover, rather
+        # than the whole widget being skipped for the session. The broad except
+        # also swallows a coding bug in update() — that surfaces only as a
+        # repeating warning log + frozen placeholder data, which is the
+        # acceptable tradeoff for "a data fetch must never crash startup".
+        try:
+            await widget.update()
+        except Exception as e:
+            logging.warning(
+                "crypto.coingecko initial fetch failed (%s); "
+                "starting with placeholder data, will retry",
+                e,
+            )
+        spawn_tracked(run_monitor_loop(widget, update_interval))
+        return widget
+
+    async def update(self) -> None:
+        # MULTIPLE ids MUST be comma-joined in ONE string — passing a list
+        # makes aiohttp emit ids=a&ids=b, which CoinGecko rejects for >1 id.
+        ids = ",".join(coin_id for _, coin_id in self.coins)
+        params: dict[str, Any] = {
+            "ids": ids,
+            "vs_currencies": self.currency,
+            "include_24hr_change": "true",
+        }
+        async with self.session.get(
+            COINGECKO_PRICE_API, params=params, headers=self._headers()
+        ) as response:
+            if response.status != 200:
+                retry = response.headers.get("retry-after")
+                suffix = f" (retry-after {retry})" if retry else ""
+                logging.warning(
+                    "CoinGecko price fetch failed: HTTP %s%s", response.status, suffix
+                )
+                # Raise so run_monitor_loop's backoff engages; never parse an
+                # error body as prices.
+                response.raise_for_status()
+
+            data = await response.json()
+
+        cur = self.currency.lower()
+        cur_change = f"{cur}_24h_change"
+
+        updated = 0
+        for coin_id, story in self._story_by_id.items():
+            entry = data.get(coin_id)
+            if not entry or cur not in entry or cur_change not in entry:
+                logging.warning(
+                    "CoinGecko: no price for %s (keeping prior value): %s",
+                    coin_id,
+                    entry,
+                )
+                continue
+            story.price_data = {
+                "price": _format_price(entry[cur]),
+                "change_24h": f"{entry[cur_change]:.2f}%",
+            }
+            updated += 1
+
+        # One INFO line per successful update (Container contract): a silent
+        # log stream after startup signals the background task died.
+        logging.info(
+            "CoinGecko updated: %s/%s coins (%s)",
+            updated,
+            len(self.coins),
+            ", ".join(coin_id for _, coin_id in self.coins),
+        )
+
+
+async def _get_coingecko_coin_list(
+    session: aiohttp.ClientSession,
+    headers: dict[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    logging.info("Fetching CoinGecko coin list...")
+    req_headers = {"Accept": "application/json", **(headers or {})}
+    async with session.get(COINGECKO_COIN_LIST, headers=req_headers) as response:
+        return await response.json()

led_ticker_crypto-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+led_ticker_crypto/__init__.py,sha256=zd9J-B80Bdjna32x0WturDdGRGvzSPxp0HlO23vqkZE,199
+led_ticker_crypto/_colors.py,sha256=Z-72XdJXaQNsnNcIoM-2kavFDEal7K1nWUDK8QJaPfA,667
+led_ticker_crypto/_ticker_render.py,sha256=9zL2uUznLssJajmraM3Z-Cr3_HPS2cfUc-Efmr8AYZw,4278
+led_ticker_crypto/coingecko.py,sha256=M0TXp-npsJnAMf3LGj4lLD4oH6utlMli5AWFKiJyylE,11851
+led_ticker_crypto-0.2.0.dist-info/METADATA,sha256=ahvHkwH4nXcuNvDHJlElyFhgQ8Ke7a_w5K88YKUB4aQ,8195
+led_ticker_crypto-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+led_ticker_crypto-0.2.0.dist-info/entry_points.txt,sha256=QtJHpnvsFUV4aZVTnvwvlT88uoug1be1bKe8CP4AJGE,57
+led_ticker_crypto-0.2.0.dist-info/licenses/LICENSE,sha256=kFECdLBfsSUUTLoH4nlAu-gQPyXoHbWMZDg8p2DGAP4,1070
+led_ticker_crypto-0.2.0.dist-info/RECORD,,

led_ticker_crypto-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

led_ticker_crypto-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[led_ticker.plugins]
+crypto = led_ticker_crypto:register

led_ticker_crypto-0.2.0.dist-info/licenses/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.