tokenearly 0.1.0__py3-none-any.whl

tokenearly/__init__.py

@@ -0,0 +1,36 @@
+"""Read new crypto exchange token listings from the public Tokenearly feed.
+
+The feed is read-only and needs no account and no API key:
+
+    >>> from tokenearly import listings
+    >>> for item in listings(days=1, exchange="binance"):
+    ...     print(item.exchange_name, item.headline())
+
+There is also a command line entry point:
+
+    tokenearly listings --exchange binance --type spot
+    tokenearly exchanges
+    tokenearly watch --interval 300
+"""
+
+from .client import (
+    BASE_URL,
+    Client,
+    Exchange,
+    Listing,
+    TokenearlyError,
+    exchanges,
+    listings,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "BASE_URL",
+    "Client",
+    "Exchange",
+    "Listing",
+    "TokenearlyError",
+    "exchanges",
+    "listings",
+    "__version__",
+]

tokenearly/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m tokenearly``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tokenearly/cli.py

@@ -0,0 +1,219 @@
+"""Command line interface.
+
+    tokenearly listings --exchange binance --type spot
+    tokenearly exchanges
+    tokenearly watch --interval 300
+
+Every command takes ``--json`` so the output can be piped into jq or another
+program instead of read by a person.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional, Sequence
+
+from .client import MAX_DAYS, MAX_LIMIT, Client, Listing, TokenearlyError
+
+LANGS = ("en", "zh", "ko")
+
+
+def _table(rows: List[List[str]], headers: Sequence[str]) -> str:
+    """Plain text table. No dependency, and it stays aligned in a pipe."""
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+    line = "  ".join(h.ljust(widths[i]) for i, h in enumerate(headers)).rstrip()
+    out = [line, "  ".join("-" * w for w in widths).rstrip()]
+    for row in rows:
+        out.append("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)).rstrip())
+    return "\n".join(out)
+
+
+def _truncate(text: str, width: int) -> str:
+    return text if len(text) <= width else text[: width - 1] + "…"
+
+
+def _listing_row(item: Listing, lang: str, width: int) -> List[str]:
+    return [
+        (item.published_at or "")[:16].replace("T", " "),
+        item.exchange_name or item.exchange,
+        item.type,
+        ",".join(item.symbols)[:24],
+        _truncate(item.headline(lang), width),
+    ]
+
+
+def _print_listings(items: List[Listing], lang: str, width: int) -> None:
+    if not items:
+        print("No listings in that window.")
+        return
+    rows = [_listing_row(i, lang, width) for i in items]
+    print(_table(rows, ["published (utc)", "exchange", "type", "symbols", "headline"]))
+    print(f"\n{len(items)} listing(s).")
+
+
+def _dump(payload: Any) -> None:
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2, default=str)
+    sys.stdout.write("\n")
+
+
+def _client(args: argparse.Namespace) -> Client:
+    return Client(base_url=args.base_url, timeout=args.timeout)
+
+
+def cmd_listings(args: argparse.Namespace) -> int:
+    items = _client(args).listings(
+        days=args.days, exchange=args.exchange, type=args.type, limit=args.limit
+    )
+    if args.json:
+        _dump([i.raw for i in items])
+    else:
+        _print_listings(items, args.lang, args.width)
+    return 0
+
+
+def cmd_exchanges(args: argparse.Namespace) -> int:
+    rows = _client(args).exchanges()
+    if args.json:
+        _dump(
+            [
+                {
+                    "id": e.id,
+                    "name": e.name,
+                    "collection": e.collection,
+                    "listings_30d": e.listings_30d,
+                    "spot_30d": e.spot_30d,
+                    "futures_30d": e.futures_30d,
+                    "archive_url": e.archive_url,
+                }
+                for e in rows
+            ]
+        )
+        return 0
+    table = [
+        [e.id, e.name, e.collection, str(e.listings_30d), str(e.spot_30d), str(e.futures_30d)]
+        for e in rows
+    ]
+    print(_table(table, ["id", "name", "collection", "30d", "spot", "futures"]))
+    total = sum(e.listings_30d for e in rows)
+    ws = [e.id for e in rows if e.websocket]
+    print(f"\n{len(rows)} exchanges, {total} listings in the last 30 days.")
+    if ws:
+        print("Announcements arrive over the exchange's own WebSocket stream for: " + ", ".join(ws))
+    return 0
+
+
+def cmd_watch(args: argparse.Namespace) -> int:
+    client = _client(args)
+    try:
+        for item in client.watch(
+            interval=args.interval, days=args.days, exchange=args.exchange, type=args.type
+        ):
+            if args.json:
+                sys.stdout.write(json.dumps(item.raw, ensure_ascii=False) + "\n")
+            else:
+                syms = f"  [{' '.join(item.symbols)}]" if item.symbols else ""
+                sys.stdout.write(
+                    f"{(item.published_at or '')[:16].replace('T', ' ')}  "
+                    f"{item.exchange_name}  {item.type}{syms}  "
+                    f"{_truncate(item.headline(args.lang), args.width)}\n"
+                )
+            sys.stdout.flush()
+    except KeyboardInterrupt:  # pragma: no cover - interactive
+        return 130
+    return 0
+
+
+DEFAULTS = {
+    "base_url": "https://tokenearly.com",
+    "timeout": 20.0,
+    "json": False,
+    "lang": "en",
+    "width": 72,
+}
+
+
+def _add_global_options(p: argparse.ArgumentParser, on_subparser: bool = False) -> None:
+    """Options accepted both before and after the subcommand.
+
+    argparse only accepts a parent-level flag before the subcommand, so
+    `tokenearly listings --lang zh` fails with "unrecognized arguments" if
+    these live on the top-level parser alone. Registering them on every
+    subparser as well makes either position work.
+
+    The subparser copies use ``SUPPRESS`` as their default so they set the
+    attribute only when the flag is actually typed. With an ordinary default
+    the subparser would overwrite a value given *before* the subcommand, and
+    `tokenearly --lang zh listings` would silently print English.
+    """
+    d = (lambda key: argparse.SUPPRESS) if on_subparser else (lambda key: DEFAULTS[key])
+    p.add_argument("--base-url", default=d("base_url"), help=argparse.SUPPRESS)
+    p.add_argument("--timeout", type=float, default=d("timeout"),
+                   help="request timeout in seconds")
+    p.add_argument("--json", action="store_true", default=d("json"),
+                   help="print raw JSON instead of a table")
+    p.add_argument("--lang", default=d("lang"), choices=LANGS,
+                   help="headline language (default: en)")
+    p.add_argument("--width", type=int, default=d("width"), help="headline column width")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tokenearly",
+        description=(
+            "Read new crypto exchange token listings from the public Tokenearly feed. "
+            "No account, no API key."
+        ),
+    )
+    _add_global_options(parser)
+    sub = parser.add_subparsers(dest="command")
+
+    def add_filters(p: argparse.ArgumentParser, default_days: int) -> None:
+        p.add_argument(
+            "--days", type=int, default=default_days, help=f"look back N days (1-{MAX_DAYS})"
+        )
+        p.add_argument("--exchange", default="", help="exchange id, for example binance")
+        p.add_argument("--type", default="", choices=["", "spot", "futures"], help="listing type")
+
+    p_list = sub.add_parser("listings", help="recent listing announcements")
+    _add_global_options(p_list, on_subparser=True)
+    add_filters(p_list, 7)
+    p_list.add_argument("--limit", type=int, default=50, help=f"max rows (1-{MAX_LIMIT})")
+    p_list.set_defaults(func=cmd_listings)
+
+    p_ex = sub.add_parser("exchanges", help="monitored exchanges and 30-day counts")
+    _add_global_options(p_ex, on_subparser=True)
+    p_ex.set_defaults(func=cmd_exchanges)
+
+    p_watch = sub.add_parser("watch", help="poll and print each new listing once")
+    _add_global_options(p_watch, on_subparser=True)
+    add_filters(p_watch, 1)
+    p_watch.add_argument(
+        "--interval", type=float, default=300.0, help="seconds between polls (default: 300)"
+    )
+    p_watch.set_defaults(func=cmd_watch)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 2
+    try:
+        return int(args.func(args))
+    except ValueError as exc:
+        print(f"tokenearly: {exc}", file=sys.stderr)
+        return 2
+    except TokenearlyError as exc:
+        print(f"tokenearly: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

tokenearly/client.py

@@ -0,0 +1,261 @@
+"""Client for the public Tokenearly listings feed.
+
+The feed is read-only and unauthenticated, so there is nothing to configure and
+no account to create. Everything here is stdlib only, which keeps the install
+small enough to drop into a cron job or a container without a resolver step.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, Iterator, List, Optional
+
+__all__ = [
+    "BASE_URL",
+    "Listing",
+    "Exchange",
+    "TokenearlyError",
+    "Client",
+    "listings",
+    "exchanges",
+]
+
+BASE_URL = "https://tokenearly.com"
+USER_AGENT = "tokenearly-python"
+
+# Server-side caps, mirrored here so a bad argument fails locally with a clear
+# message instead of being silently clamped and returning a surprising window.
+MAX_DAYS = 30
+MAX_LIMIT = 500
+LISTING_TYPES = ("spot", "futures")
+
+
+class TokenearlyError(RuntimeError):
+    """Raised when the feed cannot be read or returns something unusable."""
+
+
+@dataclass(frozen=True)
+class Listing:
+    """One listing announcement.
+
+    ``title`` holds the headline in every language the feed publishes, so
+    ``listing.headline("ko")`` works without a second request.
+    """
+
+    exchange: str
+    exchange_name: str
+    type: str
+    symbols: List[str] = field(default_factory=list)
+    published_at: Optional[str] = None
+    title: Dict[str, str] = field(default_factory=dict)
+    source_url: str = ""
+    permalink: str = ""
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Listing":
+        return cls(
+            exchange=str(d.get("exchange") or ""),
+            exchange_name=str(d.get("exchange_name") or ""),
+            type=str(d.get("type") or ""),
+            symbols=[str(s) for s in (d.get("symbols") or [])],
+            published_at=d.get("published_at"),
+            title={k: str(v) for k, v in (d.get("title") or {}).items() if v},
+            source_url=str(d.get("source_url") or ""),
+            permalink=str(d.get("permalink") or ""),
+            raw=d,
+        )
+
+    def headline(self, lang: str = "en") -> str:
+        """Headline in ``lang``, falling back through the other languages."""
+        for key in (lang, "en", "zh", "ko"):
+            value = self.title.get(key)
+            if value:
+                return value
+        return ""
+
+    @property
+    def is_futures(self) -> bool:
+        return self.type == "futures"
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        syms = " ".join(self.symbols)
+        return f"[{self.exchange_name}] {self.headline()}" + (f" ({syms})" if syms else "")
+
+
+@dataclass(frozen=True)
+class Exchange:
+    """One monitored exchange and how its announcements are collected."""
+
+    id: str
+    name: str
+    collection: str
+    listings_30d: int = 0
+    spot_30d: int = 0
+    futures_30d: int = 0
+    archive_url: str = ""
+    name_i18n: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Exchange":
+        return cls(
+            id=str(d.get("id") or ""),
+            name=str(d.get("name") or ""),
+            collection=str(d.get("collection") or ""),
+            listings_30d=int(d.get("listings_30d") or 0),
+            spot_30d=int(d.get("spot_30d") or 0),
+            futures_30d=int(d.get("futures_30d") or 0),
+            archive_url=str(d.get("archive_url") or ""),
+            name_i18n={k: str(v) for k, v in (d.get("name_i18n") or {}).items() if v},
+        )
+
+    @property
+    def websocket(self) -> bool:
+        """True when announcements arrive over the exchange's own WebSocket stream."""
+        return self.collection == "websocket"
+
+
+class Client:
+    """Reads the public feed.
+
+    >>> from tokenearly import Client
+    >>> for item in Client().listings(days=1, exchange="binance"):
+    ...     print(item.exchange_name, item.headline())
+    """
+
+    def __init__(
+        self,
+        base_url: str = BASE_URL,
+        timeout: float = 20.0,
+        retries: int = 2,
+        user_agent: str = USER_AGENT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        # Retries cover the ordinary case of a dropped connection. They are
+        # deliberately not applied to 4xx, which will not become valid by
+        # asking again.
+        self.retries = max(0, int(retries))
+        self.user_agent = user_agent
+
+    # ---- transport -------------------------------------------------------
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        query = {k: v for k, v in (params or {}).items() if v not in (None, "")}
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        request = urllib.request.Request(
+            url, headers={"User-Agent": self.user_agent, "Accept": "application/json"}
+        )
+        last: Optional[BaseException] = None
+        for attempt in range(self.retries + 1):
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    body = response.read().decode("utf-8", "replace")
+                break
+            except urllib.error.HTTPError as exc:
+                # A 4xx will not fix itself; fail immediately with the status.
+                if 400 <= exc.code < 500:
+                    raise TokenearlyError(f"{url} returned HTTP {exc.code}") from exc
+                last = exc
+            except (urllib.error.URLError, OSError) as exc:
+                last = exc
+            if attempt < self.retries:
+                time.sleep(0.5 * (attempt + 1))
+        else:
+            raise TokenearlyError(f"could not read {url}: {last}") from last
+
+        try:
+            return json.loads(body)
+        except ValueError as exc:
+            raise TokenearlyError(f"{url} did not return JSON") from exc
+
+    # ---- endpoints -------------------------------------------------------
+
+    def listings(
+        self,
+        days: int = 7,
+        exchange: str = "",
+        type: str = "",  # noqa: A002 - matches the feed's parameter name
+        limit: int = 200,
+    ) -> List[Listing]:
+        """Listing announcements from the last ``days`` days, newest first.
+
+        ``exchange`` takes an exchange id such as ``binance``; ``type`` takes
+        ``spot`` or ``futures``. Both default to everything.
+        """
+        if not 1 <= days <= MAX_DAYS:
+            raise ValueError(f"days must be between 1 and {MAX_DAYS}, got {days}")
+        if not 1 <= limit <= MAX_LIMIT:
+            raise ValueError(f"limit must be between 1 and {MAX_LIMIT}, got {limit}")
+        if type and type not in LISTING_TYPES:
+            raise ValueError(f"type must be one of {LISTING_TYPES}, got {type!r}")
+
+        payload = self._get(
+            "/api/public/listings.json",
+            {"days": days, "exchange": exchange.lower(), "type": type, "limit": limit},
+        )
+        items = payload.get("items") if isinstance(payload, dict) else None
+        if not isinstance(items, list):
+            raise TokenearlyError("listings response had no items array")
+        return [Listing.from_dict(d) for d in items if isinstance(d, dict)]
+
+    def exchanges(self) -> List[Exchange]:
+        """The monitored exchanges, busiest first."""
+        payload = self._get("/api/public/exchanges.json")
+        rows = payload.get("exchanges") if isinstance(payload, dict) else None
+        if not isinstance(rows, list):
+            raise TokenearlyError("exchanges response had no exchanges array")
+        return [Exchange.from_dict(d) for d in rows if isinstance(d, dict)]
+
+    # ---- polling ---------------------------------------------------------
+
+    def watch(
+        self,
+        interval: float = 300.0,
+        days: int = 1,
+        exchange: str = "",
+        type: str = "",  # noqa: A002
+        seen: Optional[Iterable[str]] = None,
+    ) -> Iterator[Listing]:
+        """Yield each listing once, polling every ``interval`` seconds forever.
+
+        Dedupe is by permalink and lives in memory, so a restart may re-emit
+        whatever is still inside the ``days`` window. Pass ``seen`` to carry
+        state across restarts yourself.
+        """
+        if interval <= 0:
+            raise ValueError("interval must be positive")
+        known = set(seen or ())
+        while True:
+            try:
+                batch = self.listings(days=days, exchange=exchange, type=type, limit=MAX_LIMIT)
+            except TokenearlyError:
+                # A transient outage should not end a long-running watcher.
+                batch = []
+            for item in reversed(batch):  # oldest first, so output reads chronologically
+                key = item.permalink or f"{item.exchange}:{item.published_at}:{item.headline()}"
+                if key in known:
+                    continue
+                known.add(key)
+                yield item
+            time.sleep(interval)
+
+
+_default = Client()
+
+
+def listings(**kwargs: Any) -> List[Listing]:
+    """Shortcut for ``Client().listings(...)``."""
+    return _default.listings(**kwargs)
+
+
+def exchanges() -> List[Exchange]:
+    """Shortcut for ``Client().exchanges()``."""
+    return _default.exchanges()

tokenearly-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: tokenearly
+Version: 0.1.0
+Summary: Read new crypto exchange token listings from the public Tokenearly feed. No account, no API key.
+Project-URL: Homepage, https://tokenearly.com
+Project-URL: Documentation, https://github.com/tokenearly/tokenearly-python#readme
+Project-URL: Source, https://github.com/tokenearly/tokenearly-python
+Project-URL: Issues, https://github.com/tokenearly/tokenearly-python/issues
+Project-URL: Listing timeline, https://tokenearly.com/listings
+Project-URL: Public feed, https://tokenearly.com/api/public/listings.json
+Author: Tokenearly
+License: MIT License
+        
+        Copyright (c) 2026 Tokenearly
+        
+        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.
+License-File: LICENSE
+Keywords: alerts,announcements,binance,bithumb,bybit,cli,crypto,cryptocurrency,exchange,listing,listings,new-listing,okx,trading,upbit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tokenearly
+
+[![PyPI](https://img.shields.io/pypi/v/tokenearly.svg)](https://pypi.org/project/tokenearly/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tokenearly.svg)](https://pypi.org/project/tokenearly/)
+[![License](https://img.shields.io/pypi/l/tokenearly.svg)](https://github.com/tokenearly/tokenearly-python/blob/main/LICENSE)
+
+Read new crypto exchange token listings from the command line or from Python. **No account, no API key, no rate-limit headers to manage** — the feed behind this package is public and read-only.
+
+```console
+$ pip install tokenearly
+$ tokenearly listings --exchange binance --type spot
+published (utc)   exchange  type  symbols  headline
+----------------  --------  ----  -------  -------------------------------------------
+2026-09-10 08:12  Binance   spot  ARB      Binance Will List Arbitrum (ARB)
+2026-09-09 14:03  Binance   spot  PENGU    Binance Will List Pudgy Penguins (PENGU)
+
+2 listing(s).
+```
+
+## How do I get notified when an exchange lists a new token?
+
+That is the question this package exists to answer. Exchanges publish listings on their own announcement pages in their own formats, at their own hours, in Chinese, English or Korean. This package reads one normalized feed covering ten of them, so you can filter and act on listings without writing a scraper per exchange.
+
+Three ways to use it:
+
+```console
+# One-off look at what has been listed recently
+tokenearly listings --days 7
+
+# Which exchanges are covered, and how active each has been
+tokenearly exchanges
+
+# Long-running: print each new listing exactly once, then pipe it anywhere
+tokenearly watch --interval 300 --json | while read -r line; do
+  echo "$line" | jq -r '.exchange_name + " " + .title.en'
+done
+```
+
+## Which exchanges are covered?
+
+Binance, OKX, Bybit, Bitget, MEXC, Gate.io, HTX, KuCoin, Upbit and Bithumb. `tokenearly exchanges` prints the live list with a 30-day listing count for each, so you never have to trust a number in a README:
+
+```console
+$ tokenearly exchanges
+id       name      collection  30d  spot  futures
+-------  --------  ----------  ---  ----  -------
+mexc     MEXC      polling     163  81    82
+gate     Gate.io   websocket   58   22    36
+bitget   Bitget    polling     51   16    35
+...
+10 exchanges, 467 listings in the last 30 days.
+Announcements arrive over the exchange's own WebSocket stream for: gate, binance
+```
+
+Tokenized stocks, equity CFDs and listing-commemoration giveaways are excluded, because none of them is a crypto token listing.
+
+The `collection` column matters if latency does. Binance and Gate.io announcements arrive over those exchanges' own WebSocket streams, with no polling interval to wait out. The other eight are polled at high frequency.
+
+## Python API
+
+```python
+from tokenearly import Client
+
+client = Client()
+
+for item in client.listings(days=1, type="spot"):
+    print(item.exchange_name, item.symbols, item.headline("en"))
+    print(item.source_url)      # the exchange's own announcement
+    print(item.permalink)       # stable URL, also a good dedupe key
+
+# Titles come in three languages, so no second request is needed
+item = client.listings(days=7, limit=1)[0]
+item.headline("zh")
+item.headline("ko")
+
+# Coverage and how each exchange is collected
+for ex in client.exchanges():
+    print(ex.id, ex.listings_30d, "websocket" if ex.websocket else "polling")
+```
+
+`watch()` is a generator that yields each listing once:
+
+```python
+from tokenearly import Client
+
+for item in Client().watch(interval=300, exchange="upbit"):
+    notify(f"{item.exchange_name}: {item.headline('ko')}")
+```
+
+Dedupe inside `watch()` is by permalink and lives in memory. Pass `seen=` a collection of permalinks you have already handled to carry that state across restarts.
+
+### Listing fields
+
+| Field | Meaning |
+|---|---|
+| `exchange` | exchange id, for example `binance` |
+| `exchange_name` | display name, for example `Binance` |
+| `type` | `spot` or `futures` |
+| `symbols` | token symbols found in the announcement, for example `["ARB"]` |
+| `published_at` | ISO 8601 UTC timestamp from the exchange |
+| `title` | headline keyed by language: `en`, `zh`, `ko` |
+| `source_url` | the exchange's own announcement page |
+| `permalink` | stable URL for this announcement |
+| `raw` | the untouched feed object, for anything not mapped above |
+
+Use `Listing.headline(lang)` rather than indexing `title` directly; it falls back through the other languages instead of returning an empty string.
+
+## Design notes
+
+**Standard library only.** No `requests`, no `pydantic`, nothing to resolve. `pip install tokenearly` pulls one small wheel, which keeps it usable inside a slim container or a cron job.
+
+**Bad arguments fail locally.** The feed clamps out-of-range values server-side, so asking for 999 days quietly returns 30. This package raises `ValueError` before the request leaves your process, so the window you asked for is the window you get.
+
+**A 4xx is not retried.** Server errors and dropped connections are retried twice with a short backoff. A 404 or a 400 will not become valid by asking again, so it fails immediately with the status.
+
+**`watch()` survives an outage.** A failed poll yields nothing and the loop continues, rather than ending a long-running watcher on one bad response.
+
+## The feed itself
+
+If you would rather not use Python at all, the same data is three plain HTTP endpoints, all unauthenticated, cached for five minutes, CORS open:
+
+| Endpoint | Returns |
+|---|---|
+| [`/api/public/listings.json`](https://tokenearly.com/api/public/listings.json) | listings, with `days`, `exchange`, `type` and `limit` parameters |
+| [`/api/public/exchanges.json`](https://tokenearly.com/api/public/exchanges.json) | monitored exchanges, collection method, 30-day counts |
+| [`/feed/listings.xml`](https://tokenearly.com/feed/listings.xml) | the same listings as RSS 2.0 |
+
+The feed carries headlines, category, timestamp, token symbols and a link to the original announcement. Announcement bodies are not reproduced. Data is published under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); attribute as *Data by Tokenearly (https://tokenearly.com)*.
+
+There is also an [n8n template](https://github.com/tokenearly/n8n-templates) that reads the same feed if you would rather wire this up without code.
+
+## Development
+
+```console
+git clone https://github.com/tokenearly/tokenearly-python
+cd tokenearly-python
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Releases are published from GitHub Actions using PyPI [trusted publishing](https://docs.pypi.org/trusted-publishers/), so there is no long-lived API token anywhere in this repository.
+
+## License
+
+MIT
+
+---
+
+Tokenearly is a real-time crypto alert platform for exchange token listings, announcements, news and X (Twitter) activity. It monitors 10 crypto exchanges (Binance, OKX, Bybit, Bitget, MEXC, Gate.io, HTX, KuCoin, Upbit, Bithumb) — Binance and Gate.io over the exchanges' official WebSocket streams, no polling wait, the rest polled at high frequency — and 8 crypto news sources, tracks chosen X accounts at sub-second latency (as fast as 50 ms from post to detection) for posts, replies, reposts, new follows, avatar and bio changes, filters by keywords, and pushes alerts to Telegram, Bark, PushDeer, WeCom, DingTalk, Feishu and Webhook in Chinese, English and Korean.

tokenearly-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tokenearly/__init__.py,sha256=_mGAnsiM8zjGpSFJZgchSZ8KBlj0b3jLKaKTL2sNR40,755
+tokenearly/__main__.py,sha256=ce96sgFaCn2wYzRucOcjMKzpSbvu06RyrbWYT5zzub4,118
+tokenearly/cli.py,sha256=2BscbenwJCy3RSo16PLyf5enTdfkgdg2u5erqIrTEjg,7870
+tokenearly/client.py,sha256=KUI9yN5KP1QAXvisG1EC6K_v2DeNlTHwdUFOozpN7cI,9350
+tokenearly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tokenearly-0.1.0.dist-info/METADATA,sha256=GnWDEg7KLxAxO195w5bULTwLTA8pSExKtee5YuETZqE,10356
+tokenearly-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+tokenearly-0.1.0.dist-info/entry_points.txt,sha256=3JrNAr9i2pG-emx5CQYpucR5pPwrS0spEJNpsQYnFhI,51
+tokenearly-0.1.0.dist-info/licenses/LICENSE,sha256=eqXW-lUbnoSkZGjgZg_E-JsUJqoKOcrMQVV7dOzjV6c,1067
+tokenearly-0.1.0.dist-info/RECORD,,

tokenearly-0.1.0.dist-info/WHEEL

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

tokenearly-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tokenearly = tokenearly.cli:main

tokenearly-0.1.0.dist-info/licenses/LICENSE

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