alphatrack 0.1.0__tar.gz

alphatrack-0.1.0/LICENSE

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

alphatrack-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: alphatrack
+Version: 0.1.0
+Summary: AlphaTrack open-source local toolkit — NFT drop eligibility checkers (keys stay on your machine)
+Author: AlphaTrack
+License: MIT
+Project-URL: Homepage, https://alphatrack.xyz/
+Project-URL: Documentation, https://github.com/alphatrack/alphatrack
+Keywords: alphatrack,opensea,eligibility,nft,presale
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: eth-account>=0.10.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# AlphaTrack
+
+Open-source **local** toolkit for NFT drop eligibility checks.
+
+Private keys stay on your machine. This repo is separate from the hosted AlphaTrack platform.
+
+## Install
+
+```bash
+# from PyPI (once published)
+pip install alphatrack
+
+# or from this folder
+pip install -e .
+```
+
+## Quick start
+
+```bash
+cp wallets.example.txt wallets.txt
+# add burner private keys to wallets.txt
+
+cp config.example.yaml config.yaml
+# edit `checks:` — one block per platform, many collections each
+
+cp .env.example .env
+# optional: set ALCHEMY_API_KEY for balance checks
+
+alphatrack platforms
+
+# run every platform/collection block in config.yaml
+alphatrack check
+
+# or pass collections on the CLI (single platform per invocation)
+alphatrack check -p opensea -c your-collection-slug -c another-slug
+alphatrack check -c https://opensea.io/collection/your-collection/overview --balances
+```
+
+Example `config.yaml` with multiple platforms:
+
+```yaml
+wallets: wallets.txt
+balances: false
+checks:
+  - platform: opensea
+    collections:
+      - deadmood-42226579
+      - the-gh0sts
+  - platform: launchmynft   # when adapter is available
+    collections:
+      - some-lmnft-slug
+```
+
+Or without installing the script entrypoint:
+
+```bash
+python -m alphatrack check
+```
+
+## What this does
+
+1. Loads wallets from a local file
+2. Signs in to the marketplace locally (OpenSea SIWE today)
+3. Reports which wallets are eligible for which mint stages
+4. Optionally checks whether eligible wallets can afford the mint (Alchemy)
+
+It does **not** mint, submit transactions, or upload private keys to AlphaTrack servers.
+
+## Supported platforms
+
+| Platform | Status |
+|----------|--------|
+| OpenSea  | ✅ v0.1 |
+| LaunchMyNFT | planned |
+| Transient | planned |
+
+## Security
+
+- Use **burner wallets** when possible
+- Never commit `wallets.txt` or `.env`
+- Network calls go to the marketplace (and optionally Alchemy) — not to AlphaTrack
+- v1 only signs SIWE login messages, not mint transactions
+
+## License
+
+MIT

alphatrack-0.1.0/README.md

@@ -0,0 +1,86 @@
+# AlphaTrack
+
+Open-source **local** toolkit for NFT drop eligibility checks.
+
+Private keys stay on your machine. This repo is separate from the hosted AlphaTrack platform.
+
+## Install
+
+```bash
+# from PyPI (once published)
+pip install alphatrack
+
+# or from this folder
+pip install -e .
+```
+
+## Quick start
+
+```bash
+cp wallets.example.txt wallets.txt
+# add burner private keys to wallets.txt
+
+cp config.example.yaml config.yaml
+# edit `checks:` — one block per platform, many collections each
+
+cp .env.example .env
+# optional: set ALCHEMY_API_KEY for balance checks
+
+alphatrack platforms
+
+# run every platform/collection block in config.yaml
+alphatrack check
+
+# or pass collections on the CLI (single platform per invocation)
+alphatrack check -p opensea -c your-collection-slug -c another-slug
+alphatrack check -c https://opensea.io/collection/your-collection/overview --balances
+```
+
+Example `config.yaml` with multiple platforms:
+
+```yaml
+wallets: wallets.txt
+balances: false
+checks:
+  - platform: opensea
+    collections:
+      - deadmood-42226579
+      - the-gh0sts
+  - platform: launchmynft   # when adapter is available
+    collections:
+      - some-lmnft-slug
+```
+
+Or without installing the script entrypoint:
+
+```bash
+python -m alphatrack check
+```
+
+## What this does
+
+1. Loads wallets from a local file
+2. Signs in to the marketplace locally (OpenSea SIWE today)
+3. Reports which wallets are eligible for which mint stages
+4. Optionally checks whether eligible wallets can afford the mint (Alchemy)
+
+It does **not** mint, submit transactions, or upload private keys to AlphaTrack servers.
+
+## Supported platforms
+
+| Platform | Status |
+|----------|--------|
+| OpenSea  | ✅ v0.1 |
+| LaunchMyNFT | planned |
+| Transient | planned |
+
+## Security
+
+- Use **burner wallets** when possible
+- Never commit `wallets.txt` or `.env`
+- Network calls go to the marketplace (and optionally Alchemy) — not to AlphaTrack
+- v1 only signs SIWE login messages, not mint transactions
+
+## License
+
+MIT

alphatrack-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alphatrack"
+version = "0.1.0"
+description = "AlphaTrack open-source local toolkit — NFT drop eligibility checkers (keys stay on your machine)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "AlphaTrack" }]
+keywords = ["alphatrack", "opensea", "eligibility", "nft", "presale"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "eth-account>=0.10.0",
+    "python-dotenv>=1.0.0",
+    "tqdm>=4.66.0",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["build", "twine"]
+
+[project.scripts]
+alphatrack = "alphatrack.cli:main"
+
+[project.urls]
+Homepage = "https://alphatrack.xyz/"
+Documentation = "https://github.com/alphatrack/alphatrack"
+
+[tool.setuptools.packages.find]
+where = ["src"]

alphatrack-0.1.0/setup.cfg

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

alphatrack-0.1.0/src/alphatrack/__init__.py

@@ -0,0 +1,3 @@
+"""AlphaTrack — open-source local NFT eligibility toolkit."""
+
+__version__ = "0.1.0"

alphatrack-0.1.0/src/alphatrack/__main__.py

@@ -0,0 +1,4 @@
+from alphatrack.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

alphatrack-0.1.0/src/alphatrack/adapters/__init__.py

@@ -0,0 +1,3 @@
+from alphatrack.adapters.base import EligibilityAdapter, get_adapter, list_platforms
+
+__all__ = ["EligibilityAdapter", "get_adapter", "list_platforms"]

alphatrack-0.1.0/src/alphatrack/adapters/base.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Dict, List
+
+from alphatrack.core.models import EligibilityResult, Wallet
+
+
+class EligibilityAdapter(ABC):
+    """Platform-specific eligibility checker."""
+
+    name: str
+
+    @abstractmethod
+    def normalize_collection(self, collection_ref: str) -> str:
+        """Turn a URL or slug into the canonical collection id for this platform."""
+
+    @abstractmethod
+    def check_wallet(self, wallet: Wallet, collection: str) -> EligibilityResult:
+        """Check a single wallet against one collection."""
+
+    def check_wallets(
+        self,
+        wallets: List[Wallet],
+        collection: str,
+    ) -> Dict[str, EligibilityResult]:
+        """Default sequential check — adapters may override for concurrency."""
+        results: Dict[str, EligibilityResult] = {}
+        slug = self.normalize_collection(collection)
+        for wallet in wallets:
+            results[wallet.address] = self.check_wallet(wallet, slug)
+        return results
+
+
+_REGISTRY: Dict[str, EligibilityAdapter] = {}
+
+
+def register_adapter(adapter: EligibilityAdapter) -> None:
+    _REGISTRY[adapter.name] = adapter
+
+
+def get_adapter(platform: str) -> EligibilityAdapter:
+    key = platform.lower().strip()
+    if key not in _REGISTRY:
+        # Lazy import built-in adapters
+        _ensure_builtins()
+    if key not in _REGISTRY:
+        available = ", ".join(sorted(_REGISTRY)) or "(none)"
+        raise ValueError(f"Unknown platform '{platform}'. Available: {available}")
+    return _REGISTRY[key]
+
+
+def list_platforms() -> List[str]:
+    _ensure_builtins()
+    return sorted(_REGISTRY)
+
+
+def _ensure_builtins() -> None:
+    if "opensea" not in _REGISTRY:
+        from alphatrack.adapters.opensea import OpenSeaAdapter
+
+        register_adapter(OpenSeaAdapter())

alphatrack-0.1.0/src/alphatrack/adapters/opensea/__init__.py

@@ -0,0 +1,3 @@
+from alphatrack.adapters.opensea.checker import OpenSeaAdapter
+
+__all__ = ["OpenSeaAdapter"]

alphatrack-0.1.0/src/alphatrack/adapters/opensea/auth.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import datetime
+import threading
+import time
+
+import requests
+from eth_account import Account
+from eth_account.messages import encode_defunct
+
+# Limit concurrent SIWE logins to avoid 429s
+_auth_semaphore = threading.Semaphore(2)
+
+NONCE_URL = "https://opensea.io/__api/auth/siwe/nonce"
+VERIFY_URL = "https://opensea.io/__api/auth/siwe/verify"
+
+STATEMENT = (
+    "Click to sign in and accept the OpenSea Terms of Service "
+    "(https://opensea.io/tos) and Privacy Policy "
+    "(https://opensea.io/privacy)."
+)
+
+BASE_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/148.0.0.0 Safari/537.36"
+    ),
+    "Origin": "https://opensea.io",
+    "Referer": "https://opensea.io/",
+}
+
+
+def _post_with_retry(session: requests.Session, url: str, **kwargs):
+    for attempt in range(5):
+        r = session.post(url, **kwargs)
+        if r.status_code == 429:
+            time.sleep(2**attempt)
+            continue
+        r.raise_for_status()
+        return r
+    r.raise_for_status()
+    return r
+
+
+def _get_nonce(session: requests.Session) -> str:
+    r = _post_with_retry(
+        session,
+        NONCE_URL,
+        headers={**BASE_HEADERS, "Content-Type": "application/json"},
+    )
+    return r.json()["nonce"]
+
+
+def _build_message(address: str, nonce: str, uri: str = "https://opensea.io") -> dict:
+    issued_at = datetime.datetime.utcnow().isoformat(timespec="milliseconds") + "Z"
+    return {
+        "domain": "opensea.io",
+        "address": address,
+        "statement": STATEMENT,
+        "uri": uri,
+        "version": "1",
+        "chainId": "1",
+        "nonce": nonce,
+        "issuedAt": issued_at,
+        "accountType": "Ethereum",
+    }
+
+
+def _format_siwe_text(msg: dict) -> str:
+    return (
+        f"{msg['domain']} wants you to sign in with your Ethereum account:\n"
+        f"{msg['address']}\n\n"
+        f"{msg['statement']}\n\n"
+        f"URI: {msg['uri']}\n"
+        f"Version: {msg['version']}\n"
+        f"Chain ID: {msg['chainId']}\n"
+        f"Nonce: {msg['nonce']}\n"
+        f"Issued At: {msg['issuedAt']}"
+    )
+
+
+def _siwe_login(session: requests.Session, address: str, private_key: str) -> str:
+    nonce = _get_nonce(session)
+    message = _build_message(address, nonce)
+    text = _format_siwe_text(message)
+    signed = Account.sign_message(encode_defunct(text=text), private_key=private_key)
+
+    payload = {
+        "message": message,
+        "signature": signed.signature.hex(),
+        "chainArch": "EVM",
+        "connectorId": "io.metamask",
+    }
+    r = _post_with_retry(
+        session,
+        VERIFY_URL,
+        json=payload,
+        headers={**BASE_HEADERS, "Content-Type": "application/json"},
+    )
+
+    access_token = r.cookies.get("access_token")
+    if not access_token:
+        raise ValueError("access_token not returned by OpenSea verify endpoint")
+    return access_token
+
+
+def login(session: requests.Session, address: str, private_key: str) -> str:
+    """
+    SIWE login against OpenSea. Sets session cookies used by GraphQL.
+
+    Private keys and signatures stay on this machine — only OpenSea auth
+    endpoints are contacted.
+    """
+    with _auth_semaphore:
+        access_token = _siwe_login(session, address, private_key)
+
+    for name in ("access_token", "auth_hint", "auth_access_hint"):
+        val = session.cookies.get(name)
+        if val:
+            session.cookies.set(name, val, domain="gql.opensea.io", path="/")
+
+    # Value used by OpenSea web client
+    os2 = "Wdr6yywSUvHzIWYeBybn17MOdxKRbbhM"
+    session.cookies.set("os2AccessEx", os2, domain="opensea.io", path="/")
+    session.cookies.set("os2AccessEx", os2, domain="gql.opensea.io", path="/")
+
+    return access_token

alphatrack-0.1.0/src/alphatrack/adapters/opensea/checker.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import logging
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Dict, List, Optional
+from urllib.parse import urlparse
+
+import requests
+from tqdm import tqdm
+
+from alphatrack.adapters.base import EligibilityAdapter
+from alphatrack.adapters.opensea import auth, client
+from alphatrack.core.config import SUBMIT_STAGGER_SEC, WORKERS
+from alphatrack.core.models import EligibilityResult, StageResult, Wallet
+
+log = logging.getLogger(__name__)
+
+
+def parse_collection_slug(collection_ref: str) -> str:
+    """Accept a slug or full OpenSea collection URL."""
+    ref = collection_ref.strip().rstrip("/")
+    if "opensea.io" in ref or ref.startswith("http"):
+        path = urlparse(ref).path
+        parts = [p for p in path.split("/") if p]
+        if "collection" in parts:
+            idx = parts.index("collection")
+            if idx + 1 < len(parts):
+                return parts[idx + 1]
+        raise ValueError(f"Could not parse collection slug from URL: {collection_ref}")
+    return ref
+
+
+def _price_from_stage(stage: dict) -> tuple[Optional[float], str]:
+    price_info = stage.get("eligiblePrice") or {}
+    token = price_info.get("token") or {}
+    unit = token.get("unit")
+    symbol = token.get("symbol") or "ETH"
+    if unit is None:
+        return None, symbol
+    return float(unit), symbol
+
+
+def _to_stage_results(
+    stages: List[dict],
+    schedule_by_idx: Dict[int, dict],
+) -> List[StageResult]:
+    label_map = {
+        "SIGNED_PRESALE": "Presale",
+        "PUBLIC_SALE": "Public",
+    }
+    results: List[StageResult] = []
+    for stage in stages:
+        if not isinstance(stage, dict):
+            continue
+        idx = stage.get("stageIndex", 0)
+        sched = schedule_by_idx.get(idx, {})
+        price_eth, symbol = _price_from_stage(stage)
+        stage_type = stage.get("stageType", "STAGE")
+        api_label = (sched.get("label") or "").strip()
+        short = api_label or label_map.get(stage_type, stage_type)
+        if stage_type == "SIGNED_PRESALE" and not api_label:
+            short = f"{short} {idx}".strip()
+
+        results.append(
+            StageResult(
+                stage_index=idx,
+                stage_type=stage_type,
+                label=short,
+                is_eligible=bool(stage.get("isEligible")),
+                max_mint=stage.get("eligibleMaxTotalMintableByWallet"),
+                price_eth=price_eth,
+                price_symbol=symbol,
+                start_time=sched.get("startTime"),
+                end_time=sched.get("endTime"),
+                raw=stage,
+            )
+        )
+    return results
+
+
+class OpenSeaAdapter(EligibilityAdapter):
+    name = "opensea"
+
+    def normalize_collection(self, collection_ref: str) -> str:
+        return parse_collection_slug(collection_ref)
+
+    def check_wallet(self, wallet: Wallet, collection: str) -> EligibilityResult:
+        slug = self.normalize_collection(collection)
+        try:
+            session = requests.Session()
+            auth.login(session, wallet.address, wallet.private_key)
+            schedule = client.get_drop_schedule(slug)
+            schedule_by_idx = {s.get("stageIndex"): s for s in schedule}
+            stages = client.get_eligibility(session, wallet.address, slug)
+            return EligibilityResult(
+                address=wallet.address,
+                platform=self.name,
+                collection=slug,
+                stages=_to_stage_results(stages, schedule_by_idx),
+            )
+        except Exception as e:
+            return EligibilityResult(
+                address=wallet.address,
+                platform=self.name,
+                collection=slug,
+                error=str(e),
+            )
+
+    def check_wallets(
+        self,
+        wallets: List[Wallet],
+        collection: str,
+    ) -> Dict[str, EligibilityResult]:
+        slug = self.normalize_collection(collection)
+        # Prefetch schedule once (shared across wallets)
+        try:
+            schedule = client.get_drop_schedule(slug)
+        except Exception as e:
+            log.warning("Failed to fetch drop schedule: %s", e)
+            schedule = []
+        schedule_by_idx = {s.get("stageIndex"): s for s in schedule}
+
+        results: Dict[str, EligibilityResult] = {}
+        futures = {}
+
+        def _one(wallet: Wallet) -> EligibilityResult:
+            try:
+                session = requests.Session()
+                auth.login(session, wallet.address, wallet.private_key)
+                stages = client.get_eligibility(session, wallet.address, slug)
+                return EligibilityResult(
+                    address=wallet.address,
+                    platform=self.name,
+                    collection=slug,
+                    stages=_to_stage_results(stages, schedule_by_idx),
+                )
+            except Exception as e:
+                return EligibilityResult(
+                    address=wallet.address,
+                    platform=self.name,
+                    collection=slug,
+                    error=str(e),
+                )
+
+        with ThreadPoolExecutor(max_workers=WORKERS) as executor:
+            for wallet in wallets:
+                future = executor.submit(_one, wallet)
+                futures[future] = wallet.address
+                time.sleep(SUBMIT_STAGGER_SEC)
+
+            with tqdm(total=len(wallets), desc=slug, unit="wallet") as pbar:
+                for future in as_completed(futures):
+                    addr = futures[future]
+                    results[addr] = future.result()
+                    pbar.update(1)
+
+        return results