launchtape 0.1.0__tar.gz

launchtape-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+# data files are licensed separately and never go in this repo
+*.jsonl.gz
+*.jsonl
+*.manifest.json

launchtape-0.1.0/LICENSE

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

launchtape-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: launchtape
+Version: 0.1.0
+Summary: Load Launch Tape's daily Solana launch data (pump.fun graduations and launches, other launchpads, Meteora pools) in Python
+Project-URL: Homepage, https://launchtape.io
+Project-URL: Datasets, https://launchtape.io/#datasets
+Project-URL: Pricing, https://launchtape.io/#buy
+Project-URL: Data licence, https://launchtape.io/#licence
+Project-URL: Source, https://github.com/launchtape-io/launchtape
+Author-email: Launch Tape <launchio48@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crypto,dataset,market data,meteora,pump.fun,pumpswap,raydium,solana
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.20
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# launchtape
+
+Python access to [Launch Tape](https://launchtape.io): daily files of Solana launch data, one gzipped JSON-lines
+file per dataset per UTC day.
+
+| Dataset | What it is |
+|---|---|
+| `gradtrades` | Every PumpSwap buy and sell in the first 30 minutes after each pump.fun graduation (wallet, amounts, price, pool reserves, fees) |
+| `pregrad` | Who is behind each pump.fun launch: creator and its funding, curve and graduation-slot buyers, the cap path, and a +10 min outcome |
+| `padfeed` | Graduations on Meteora DBC and Raydium LaunchLab: migration facts, pool balances every few seconds, top holders, US$ quote prices |
+| `meteora-pools` | Per-minute price, TVL, volume and exact fees for ~200 Meteora DLMM pools |
+
+A free 2-hour sample of every dataset is on the site; `launchtape` downloads it, checks its SHA-256 and reads it.
+
+## Install
+
+```sh
+pip install launchtape              # needs only requests
+pip install "launchtape[pandas]"    # adds pandas for launchtape.frame()
+```
+
+Python 3.9 or newer.
+
+## Quickstart
+
+Crash rate of pump.fun graduates, split by "instant" launches (graduated within 5 s of creation):
+
+```python
+import launchtape as lt
+
+path = lt.sample("pregrad")                                    # free sample, SHA-256 checked, cached
+rec = lt.frame(path, types="record")[["mint", "sym", "instant", "ageS"]]
+out = lt.frame(path, types="outcome")[["mint", "crashed", "maxGain"]]
+df = rec.merge(out, on="mint")                                 # one row per graduate seen in both
+print(df.groupby("instant")["crashed"].agg(["mean", "count"]))
+print(lt.schema("pregrad"))                                    # every row type and field
+```
+
+The sample is two hours, so the counts are small: it shows the shape of the data, not a result.
+
+## API
+
+| Call | Does |
+|---|---|
+| `lt.datasets()` | the datasets as `(name, description)` pairs |
+| `lt.schema(dataset)` | the schema as Markdown text (bundled, works offline) |
+| `lt.sample(dataset)` | downloads the free sample into `~/.cache/launchtape`, checks it against the site's `SHA256SUMS`, returns its path; a good cached copy is reused |
+| `lt.load(path_or_dataset, types=None, limit=None)` | streams the rows as dicts; `types` keeps only rows whose `type` is one of them, `limit` stops after that many rows; a dataset name reads its sample |
+| `lt.frame(path_or_dataset, types=None, limit=None)` | the same rows as a pandas DataFrame (nested fields stay dicts/lists) |
+| `lt.fetch(link_or_token, dataset, day, dest=None)` | downloads a paid day file from your delivery link, checks it against its `.manifest.json`, returns its path |
+
+```python
+for row in lt.load("gradtrades", types="grad", limit=5):      # streams, so a 5-million-row day is fine
+    print(row["mint"], row["capSol"])
+
+path = lt.fetch("https://launchtape.io/dl/<token>", "pregrad", "2026-10-11", dest="data/")
+```
+
+Times: `t` is milliseconds since 1970 UTC (`pd.to_datetime(df["t"], unit="ms", utc=True)`). Coverage gaps are rows
+in the files (`down`, `up`, `resume`, `end`), never filled in: see each schema.
+
+A full `gradtrades` day is about 5 million rows; for a DataFrame, pass `types=` and/or `limit=`, or stream with
+`load()`. A download that does not match its SHA-256 raises `launchtape.ChecksumError` and is not kept.
+Environment: `LAUNCHTAPE_CACHE` changes the cache folder.
+
+## Command line
+
+```sh
+launchtape datasets
+launchtape sample gradtrades                  # prints the cached path
+launchtape head gradtrades -n 5               # first rows of the sample, as JSON lines
+launchtape head pregrad -t record -n 2        # only rows of one type
+launchtape schema pregrad
+launchtape fetch https://launchtape.io/dl/<token> pregrad 2026-10-11 -o data/
+```
+
+`python -m launchtape ...` works too.
+
+## Full days: prices and how to buy
+
+Day file (one dataset, one UTC day): 0.05 SOL or 6 USDC. Month of history (one dataset, 30 days): 0.5 SOL or
+60 USDC. Daily feed (every dataset, each new day as it closes): 1 SOL or 120 USDC a month. Send SOL or USDC on
+Solana to `5vf1PzK8LrF9D5bemYJYPsFYp4nHULSTA1biBampgU58` with a memo giving your email address or Telegram handle
+and the datasets and days you want; within 24 hours you get a private download link
+(`https://launchtape.io/dl/<token>`, valid 7 days) that `launchtape fetch` reads. Or buy through
+[launchtape.io](https://launchtape.io/#buy), which has a Solana Pay QR code and a contact form.
+
+## Licences
+
+- **This package** (the code): MIT, see [LICENSE](LICENSE).
+- **The data** it downloads, the free samples included, has its own licence: personal and research use inside
+  your own team. No resale, republishing or redistribution of the files, in whole or in part. Results you derive
+  from it (charts, papers, models, strategies) are yours. Full text: [launchtape.io](https://launchtape.io/#licence).
+
+The data is market data recorded from public sources, provided as is. It is not financial advice.

launchtape-0.1.0/README.md

@@ -0,0 +1,95 @@
+# launchtape
+
+Python access to [Launch Tape](https://launchtape.io): daily files of Solana launch data, one gzipped JSON-lines
+file per dataset per UTC day.
+
+| Dataset | What it is |
+|---|---|
+| `gradtrades` | Every PumpSwap buy and sell in the first 30 minutes after each pump.fun graduation (wallet, amounts, price, pool reserves, fees) |
+| `pregrad` | Who is behind each pump.fun launch: creator and its funding, curve and graduation-slot buyers, the cap path, and a +10 min outcome |
+| `padfeed` | Graduations on Meteora DBC and Raydium LaunchLab: migration facts, pool balances every few seconds, top holders, US$ quote prices |
+| `meteora-pools` | Per-minute price, TVL, volume and exact fees for ~200 Meteora DLMM pools |
+
+A free 2-hour sample of every dataset is on the site; `launchtape` downloads it, checks its SHA-256 and reads it.
+
+## Install
+
+```sh
+pip install launchtape              # needs only requests
+pip install "launchtape[pandas]"    # adds pandas for launchtape.frame()
+```
+
+Python 3.9 or newer.
+
+## Quickstart
+
+Crash rate of pump.fun graduates, split by "instant" launches (graduated within 5 s of creation):
+
+```python
+import launchtape as lt
+
+path = lt.sample("pregrad")                                    # free sample, SHA-256 checked, cached
+rec = lt.frame(path, types="record")[["mint", "sym", "instant", "ageS"]]
+out = lt.frame(path, types="outcome")[["mint", "crashed", "maxGain"]]
+df = rec.merge(out, on="mint")                                 # one row per graduate seen in both
+print(df.groupby("instant")["crashed"].agg(["mean", "count"]))
+print(lt.schema("pregrad"))                                    # every row type and field
+```
+
+The sample is two hours, so the counts are small: it shows the shape of the data, not a result.
+
+## API
+
+| Call | Does |
+|---|---|
+| `lt.datasets()` | the datasets as `(name, description)` pairs |
+| `lt.schema(dataset)` | the schema as Markdown text (bundled, works offline) |
+| `lt.sample(dataset)` | downloads the free sample into `~/.cache/launchtape`, checks it against the site's `SHA256SUMS`, returns its path; a good cached copy is reused |
+| `lt.load(path_or_dataset, types=None, limit=None)` | streams the rows as dicts; `types` keeps only rows whose `type` is one of them, `limit` stops after that many rows; a dataset name reads its sample |
+| `lt.frame(path_or_dataset, types=None, limit=None)` | the same rows as a pandas DataFrame (nested fields stay dicts/lists) |
+| `lt.fetch(link_or_token, dataset, day, dest=None)` | downloads a paid day file from your delivery link, checks it against its `.manifest.json`, returns its path |
+
+```python
+for row in lt.load("gradtrades", types="grad", limit=5):      # streams, so a 5-million-row day is fine
+    print(row["mint"], row["capSol"])
+
+path = lt.fetch("https://launchtape.io/dl/<token>", "pregrad", "2026-10-11", dest="data/")
+```
+
+Times: `t` is milliseconds since 1970 UTC (`pd.to_datetime(df["t"], unit="ms", utc=True)`). Coverage gaps are rows
+in the files (`down`, `up`, `resume`, `end`), never filled in: see each schema.
+
+A full `gradtrades` day is about 5 million rows; for a DataFrame, pass `types=` and/or `limit=`, or stream with
+`load()`. A download that does not match its SHA-256 raises `launchtape.ChecksumError` and is not kept.
+Environment: `LAUNCHTAPE_CACHE` changes the cache folder.
+
+## Command line
+
+```sh
+launchtape datasets
+launchtape sample gradtrades                  # prints the cached path
+launchtape head gradtrades -n 5               # first rows of the sample, as JSON lines
+launchtape head pregrad -t record -n 2        # only rows of one type
+launchtape schema pregrad
+launchtape fetch https://launchtape.io/dl/<token> pregrad 2026-10-11 -o data/
+```
+
+`python -m launchtape ...` works too.
+
+## Full days: prices and how to buy
+
+Day file (one dataset, one UTC day): 0.05 SOL or 6 USDC. Month of history (one dataset, 30 days): 0.5 SOL or
+60 USDC. Daily feed (every dataset, each new day as it closes): 1 SOL or 120 USDC a month. Send SOL or USDC on
+Solana to `5vf1PzK8LrF9D5bemYJYPsFYp4nHULSTA1biBampgU58` with a memo giving your email address or Telegram handle
+and the datasets and days you want; within 24 hours you get a private download link
+(`https://launchtape.io/dl/<token>`, valid 7 days) that `launchtape fetch` reads. Or buy through
+[launchtape.io](https://launchtape.io/#buy), which has a Solana Pay QR code and a contact form.
+
+## Licences
+
+- **This package** (the code): MIT, see [LICENSE](LICENSE).
+- **The data** it downloads, the free samples included, has its own licence: personal and research use inside
+  your own team. No resale, republishing or redistribution of the files, in whole or in part. Results you derive
+  from it (charts, papers, models, strategies) are yours. Full text: [launchtape.io](https://launchtape.io/#licence).
+
+The data is market data recorded from public sources, provided as is. It is not financial advice.

launchtape-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "launchtape"
+dynamic = ["version"]
+description = "Load Launch Tape's daily Solana launch data (pump.fun graduations and launches, other launchpads, Meteora pools) in Python"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Launch Tape", email = "launchio48@gmail.com" }]
+keywords = ["solana", "pump.fun", "pumpswap", "meteora", "raydium", "dataset", "market data", "crypto"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+]
+dependencies = ["requests>=2.20"]
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.3"]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://launchtape.io"
+Datasets = "https://launchtape.io/#datasets"
+Pricing = "https://launchtape.io/#buy"
+"Data licence" = "https://launchtape.io/#licence"
+Source = "https://github.com/launchtape-io/launchtape"
+
+[project.scripts]
+launchtape = "launchtape.cli:main"
+
+[tool.hatch.version]
+path = "src/launchtape/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/launchtape"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/launchtape", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

launchtape-0.1.0/src/launchtape/__init__.py

@@ -0,0 +1,18 @@
+"""Launch Tape: daily files of Solana launch data (https://launchtape.io) in Python.
+
+    import launchtape as lt
+    path = lt.sample("pregrad")              # free 2-hour sample, SHA-256 checked
+    for row in lt.load(path, types="record", limit=3):
+        print(row["sym"], row["instant"])
+"""
+
+from ._catalog import DATASETS, Dataset, datasets, schema
+from ._download import ChecksumError, LaunchTapeError, cache_dir, fetch, sample
+from ._read import frame, load
+from ._version import __version__
+
+__all__ = [
+    "DATASETS", "Dataset", "datasets", "schema",
+    "sample", "fetch", "cache_dir", "LaunchTapeError", "ChecksumError",
+    "load", "frame", "__version__",
+]

launchtape-0.1.0/src/launchtape/__main__.py

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

launchtape-0.1.0/src/launchtape/_catalog.py

@@ -0,0 +1,54 @@
+"""The datasets, their one-line descriptions and their bundled schema docs."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from typing import List, NamedTuple
+
+
+class Dataset(NamedTuple):
+    name: str
+    description: str
+
+
+_DATASETS = (
+    Dataset(
+        "gradtrades",
+        "Every PumpSwap buy and sell in the first 30 minutes after each pump.fun graduation "
+        "(wallet, amounts, price, pool reserves, fees)",
+    ),
+    Dataset(
+        "pregrad",
+        "Who is behind each pump.fun launch: creator and its funding, curve and graduation-slot "
+        "buyers, the cap path, and a +10 min outcome",
+    ),
+    Dataset(
+        "padfeed",
+        "Graduations on Meteora DBC and Raydium LaunchLab: migration facts, pool balances every "
+        "few seconds, top holders, US$ quote prices",
+    ),
+    Dataset(
+        "meteora-pools",
+        "Per-minute price, TVL, volume and exact fees for ~200 Meteora DLMM pools",
+    ),
+)
+
+DATASETS = tuple(d.name for d in _DATASETS)
+
+
+def check_dataset(dataset: str) -> str:
+    if dataset not in DATASETS:
+        raise ValueError(f"unknown dataset {dataset!r}; choose one of: {', '.join(DATASETS)}")
+    return dataset
+
+
+def datasets() -> List[Dataset]:
+    """The datasets as (name, description) pairs."""
+    return list(_DATASETS)
+
+
+def schema(dataset: str) -> str:
+    """The schema of a dataset as Markdown text (every row type and field)."""
+    check_dataset(dataset)
+    # one name per joinpath: Python 3.9's Traversable takes a single argument
+    return files("launchtape").joinpath("schemas").joinpath(f"{dataset}.md").read_text(encoding="utf-8")

launchtape-0.1.0/src/launchtape/_download.py

@@ -0,0 +1,216 @@
+"""Downloads: the free samples and paid day files. A file is kept only after its SHA-256 matches the published one."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+import json
+import os
+import re
+import sys
+import warnings
+from pathlib import Path
+from typing import Dict, Optional, Union
+from urllib.parse import urlsplit
+
+import requests
+
+from ._catalog import check_dataset
+from ._version import __version__
+
+DEFAULT_URL = "https://launchtape.io"
+CHUNK = 1 << 20
+TIMEOUT = (15, 120)  # connect, read (seconds)
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+_HEX64 = re.compile(r"[0-9a-fA-F]{64}")
+_TOKEN = re.compile(r"[0-9a-f]{32}")
+_NAME = re.compile(r"[a-z][a-z0-9-]*")
+_DAY = re.compile(r"\d{4}-\d{2}-\d{2}")
+
+
+class LaunchTapeError(Exception):
+    """A download could not be completed or checked."""
+
+
+class ChecksumError(LaunchTapeError):
+    """A downloaded file's SHA-256 does not match the published one (the file is not kept)."""
+
+
+def base_url() -> str:
+    """The site to download from: $LAUNCHTAPE_URL, else https://launchtape.io."""
+    return os.environ.get("LAUNCHTAPE_URL", DEFAULT_URL).rstrip("/")
+
+
+def cache_dir() -> Path:
+    """Where samples are kept: $LAUNCHTAPE_CACHE, else ~/.cache/launchtape."""
+    env = os.environ.get("LAUNCHTAPE_CACHE")
+    return Path(env).expanduser() if env else Path.home() / ".cache" / "launchtape"
+
+
+def sha256_file(path: PathLike) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(CHUNK), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def _get(url: str, stream: bool = False) -> requests.Response:
+    try:
+        r = requests.get(url, stream=stream, timeout=TIMEOUT,
+                         headers={"User-Agent": f"launchtape-python/{__version__}"})
+    except requests.RequestException as e:
+        raise LaunchTapeError(f"could not reach {url}: {e}") from e
+    if r.status_code != 200:
+        r.close()
+        hint = ""
+        if r.status_code == 404 and "/dl/" in url:
+            hint = " (download links last 7 days and list only the files you bought; write to us through launchtape.io)"
+        raise LaunchTapeError(f"{url}: HTTP {r.status_code}{hint}")
+    return r
+
+
+def _progress(name: str, done: int, total: Optional[int]) -> None:
+    size = f"{done / 1e6:,.1f} / {total / 1e6:,.1f} MB" if total else f"{done / 1e6:,.1f} MB"
+    sys.stderr.write(f"\r{name}: {size}")
+    sys.stderr.flush()
+
+
+def _download(url: str, target: Path, sha256: str, total: Optional[int] = None, progress: bool = False) -> Path:
+    """Stream url to target, hashing on the way; the file appears under its name only if the hash matches."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    part = target.with_name(f"{target.name}.{os.getpid()}.part")
+    h = hashlib.sha256()
+    done = 0
+    try:
+        with _get(url, stream=True) as r, open(part, "wb") as out:
+            total = total or int(r.headers.get("content-length") or 0) or None
+            for chunk in r.iter_content(CHUNK):
+                out.write(chunk)
+                h.update(chunk)
+                done += len(chunk)
+                if progress:
+                    _progress(target.name, done, total)
+        if progress:
+            sys.stderr.write("\n")
+        got = h.hexdigest()
+        if got != sha256.lower():
+            raise ChecksumError(f"{target.name}: SHA-256 {got} does not match the published {sha256.lower()}; "
+                                "the download was discarded, please try again")
+        os.replace(part, target)
+    except BaseException:
+        try:
+            part.unlink()
+        except FileNotFoundError:
+            pass
+        raise
+    return target
+
+
+def _parse_sums(text: str) -> Dict[str, str]:
+    """`sha256sum` output -> {file name: hex digest}."""
+    sums = {}
+    for line in text.splitlines():
+        parts = line.strip().split(None, 1)
+        if len(parts) == 2 and _HEX64.fullmatch(parts[0]):
+            sums[parts[1].lstrip("*")] = parts[0].lower()
+    return sums
+
+
+def sample(dataset: str, *, cache: Optional[PathLike] = None, progress: bool = False) -> Path:
+    """Download the free 2-hour sample of a dataset (checked against the site's SHA256SUMS) and return its path.
+
+    A sample already in the cache is reused when its hash still matches. If the site cannot be reached, a sample
+    already in the cache (checked when it was downloaded) is returned with a warning.
+    """
+    check_dataset(dataset)
+    folder = Path(cache).expanduser() if cache is not None else cache_dir()
+    pattern = re.compile(rf"{re.escape(dataset)}-\d{{4}}-\d{{2}}-\d{{2}}-\d{{4}}-\d{{4}}utc\.jsonl\.gz")
+    kept = sorted(p for p in folder.glob(f"{dataset}-*utc.jsonl.gz") if pattern.fullmatch(p.name))
+    base = base_url()
+    try:
+        with _get(f"{base}/sample/SHA256SUMS") as r:
+            sums = _parse_sums(r.text)
+    except LaunchTapeError as e:
+        if kept:
+            warnings.warn(f"{e}; using the {dataset} sample already in {folder}", stacklevel=2)
+            return kept[-1]
+        raise
+    names = sorted(n for n in sums if pattern.fullmatch(n))
+    if not names:
+        raise LaunchTapeError(f"no {dataset} sample is listed in {base}/sample/SHA256SUMS")
+    name = names[-1]
+    target = folder / name
+    if not (target.is_file() and sha256_file(target) == sums[name]):
+        _download(f"{base}/sample/{name}", target, sums[name], progress=progress)
+    for old in kept:  # an older sample window of the same dataset
+        if old != target:
+            old.unlink()
+    return target
+
+
+def _delivery_base(url_or_token: str) -> str:
+    s = str(url_or_token).strip()
+    if _TOKEN.fullmatch(s):
+        return f"{base_url()}/dl/{s}"
+    parts = urlsplit(s)
+    m = re.match(r"/dl/([0-9a-f]{32})(?:/|$)", parts.path)
+    if parts.scheme not in ("http", "https") or not parts.netloc or not m:
+        raise ValueError(f"not a Launch Tape delivery link or token: {url_or_token!r} "
+                         "(expected https://launchtape.io/dl/<token> or the 32-character token)")
+    return f"{parts.scheme}://{parts.netloc}/dl/{m.group(1)}"
+
+
+def _day(day: Union[str, _dt.date]) -> str:
+    if isinstance(day, _dt.datetime):
+        day = day.date()
+    if isinstance(day, _dt.date):
+        return day.isoformat()
+    s = str(day).strip()
+    if _DAY.fullmatch(s):
+        try:
+            _dt.date.fromisoformat(s)
+            return s
+        except ValueError:
+            pass
+    raise ValueError(f"day must be a UTC date like 2026-10-11, got {day!r}")
+
+
+def fetch(url_or_token: str, dataset: str, day: Union[str, _dt.date], dest: Optional[PathLike] = None,
+          *, progress: bool = False) -> Path:
+    """Download one paid day file from a delivery link and return its path.
+
+    url_or_token: the link from your delivery mail (https://launchtape.io/dl/<token>) or just its token.
+    day: the UTC day, "YYYY-MM-DD" or a date. dest: a folder (default: the current folder) or a file path ending
+    in .gz. The file is checked against the SHA-256 in <dataset>-<day>.manifest.json, which is saved next to it.
+    A file already at the destination with the right hash is not downloaded again.
+    """
+    if not _NAME.fullmatch(str(dataset)):
+        raise ValueError(f"not a dataset name: {dataset!r}")
+    stem = f"{dataset}-{_day(day)}"
+    fname = f"{stem}.jsonl.gz"
+    base = _delivery_base(url_or_token)
+    with _get(f"{base}/{stem}.manifest.json") as r:
+        raw = r.content
+    try:
+        manifest = json.loads(raw)
+    except ValueError as e:
+        raise LaunchTapeError(f"{stem}.manifest.json is not valid JSON: {e}") from None
+    files = manifest.get("files") if isinstance(manifest, dict) else None
+    entry = next((f for f in files or [] if isinstance(f, dict) and f.get("file") == fname), None)
+    sha = entry.get("sha256") if entry else None
+    if not isinstance(sha, str) or not _HEX64.fullmatch(sha):
+        raise LaunchTapeError(f"{stem}.manifest.json has no SHA-256 for {fname}")
+    size = entry.get("bytes")
+    if dest is None:
+        target = Path.cwd() / fname
+    else:
+        target = Path(dest).expanduser()
+        if target.is_dir() or not target.name.endswith(".gz"):
+            target = target / fname
+    if not (target.is_file() and sha256_file(target) == sha.lower()):
+        _download(f"{base}/{fname}", target, sha, total=size if isinstance(size, int) else None, progress=progress)
+    (target.parent / f"{stem}.manifest.json").write_bytes(raw)
+    return target