alphatrack 0.1.0__py3-none-any.whl

alphatrack/__init__.py

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

alphatrack/__main__.py

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

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/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/adapters/opensea/__init__.py

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

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/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

alphatrack/adapters/opensea/client.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+import requests
+
+GQL_URL = "https://gql.opensea.io/graphql"
+
+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"
+    ),
+    "accept": (
+        "application/graphql-response+json, application/graphql+json, "
+        "application/json, text/event-stream, multipart/mixed"
+    ),
+    "accept-language": "en-US,en;q=0.9",
+    "content-type": "application/json",
+    "Origin": "https://opensea.io",
+    "Referer": "https://opensea.io/",
+    "x-app-id": "os2-web",
+    "x-graphql-operation-type": "query",
+    "sec-ch-ua": '"Chromium";v="148", "Google Chrome";v="148", "Not/A)Brand";v="99"',
+    "sec-ch-ua-mobile": "?0",
+    "sec-ch-ua-platform": '"macOS"',
+    "Sec-Fetch-Dest": "empty",
+    "Sec-Fetch-Mode": "cors",
+    "Sec-Fetch-Site": "same-site",
+}
+
+ELIGIBILITY_QUERY = {
+    "extensions": {
+        "persistedQuery": {
+            "sha256Hash": (
+                "d893f026d731e8f14986921fa4229098e018289f6cc7683f8ee2dd83749dd95d"
+            ),
+            "version": 1,
+        }
+    },
+    "operationName": "DropEligibilityQuery",
+}
+
+DROP_SCHEDULE_QUERY = """
+query DropStages($slug: String!) {
+  dropBySlug(slug: $slug) {
+    __typename
+    ... on Drop {
+      stages {
+        label
+        stageType
+        stageIndex
+        startTime
+        endTime
+        maxTotalMintableByWallet
+      }
+    }
+  }
+}
+"""
+
+
+def get_drop_schedule(slug: str) -> List[dict]:
+    """Fetch mint schedule (start/end times). No auth required."""
+    payload = {
+        "query": DROP_SCHEDULE_QUERY,
+        "variables": {"slug": slug},
+    }
+    response = requests.post(GQL_URL, json=payload, headers=BASE_HEADERS, timeout=30)
+    data = response.json()
+    return data.get("data", {}).get("dropBySlug", {}).get("stages", []) or []
+
+
+def get_eligibility(session: requests.Session, address: str, slug: str) -> List[dict]:
+    """
+    Query drop eligibility for a wallet.
+
+    The connected-account-server-hint cookie must match the wallet address
+    being queried — OpenSea uses it to resolve isEligible.
+    """
+    addr_lower = address.lower()
+    session.cookies.set(
+        "connected-account-server-hint", addr_lower, domain="gql.opensea.io", path="/"
+    )
+    session.cookies.set(
+        "connected-account-server-hint", addr_lower, domain="opensea.io", path="/"
+    )
+
+    payload: dict[str, Any] = {
+        **ELIGIBILITY_QUERY,
+        "variables": {
+            "address": addr_lower,
+            "collectionSlug": slug,
+        },
+    }
+
+    response = session.post(GQL_URL, json=payload, headers=BASE_HEADERS, timeout=30)
+    data = response.json()
+    stages = data.get("data", {}).get("dropBySlug", {}).get("stages", [])
+    return stages if stages else []

alphatrack/cli.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+import time
+
+from alphatrack import __version__
+from alphatrack.adapters import get_adapter, list_platforms
+from alphatrack.core.balance import fetch_eth_balances
+from alphatrack.core.report import print_summary
+from alphatrack.core.user_config import load_user_config, resolve_check_options
+from alphatrack.core.wallets import load_wallets
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="alphatrack",
+        description=(
+            "AlphaTrack open-source toolkit — check NFT drop eligibility locally. "
+            "Private keys never leave your machine."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("platforms", help="List supported platforms")
+
+    check = sub.add_parser(
+        "check",
+        help="Check wallet eligibility for one or more drops",
+        description=(
+            "Check eligibility from config.yaml (supports multiple platforms via "
+            "`checks:`) and/or -c flags. Example: alphatrack check"
+        ),
+    )
+    check.add_argument(
+        "-f",
+        "--config",
+        default=None,
+        help="Path to YAML config (default: ./config.yaml if present)",
+    )
+    check.add_argument(
+        "-c",
+        "--collection",
+        action="append",
+        default=None,
+        dest="collections",
+        help="Collection slug or URL (repeatable; overrides config jobs if set)",
+    )
+    check.add_argument(
+        "-p",
+        "--platform",
+        default=None,
+        help="Platform adapter (with -c, or forces one platform over config jobs)",
+    )
+    check.add_argument(
+        "-w",
+        "--wallets",
+        default=None,
+        help="Path to wallets file (default: from config, else wallets.txt)",
+    )
+    check.add_argument(
+        "--balances",
+        action="store_true",
+        help="Fetch ETH balances for eligible wallets (needs ALCHEMY_API_KEY)",
+    )
+    check.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Verbose logging",
+    )
+
+    return parser
+
+
+def _cmd_platforms() -> int:
+    for name in list_platforms():
+        print(name)
+    return 0
+
+
+def _collect_eligible_addresses(results) -> list[str]:
+    eligible = set()
+    for result in results.values():
+        for stage in result.stages:
+            if stage.is_eligible and stage.stage_type != "PUBLIC_SALE":
+                eligible.add(result.address)
+                break
+    return list(eligible)
+
+
+def _run_collection(adapter, wallets, collection_ref, balances_enabled, log):
+    slug = adapter.normalize_collection(collection_ref)
+    col_start = time.time()
+    results = adapter.check_wallets(wallets, slug)
+
+    balances = None
+    if balances_enabled:
+        eligible_addrs = _collect_eligible_addresses(results)
+        if eligible_addrs:
+            if not os.getenv("ALCHEMY_API_KEY"):
+                log.warning("ALCHEMY_API_KEY missing — skipping balances")
+            else:
+                log.info(
+                    "Fetching ETH balances for %d eligible wallet(s)...",
+                    len(eligible_addrs),
+                )
+                balances = fetch_eth_balances(eligible_addrs)
+
+    print_summary(
+        wallets,
+        results,
+        collection=slug,
+        platform=adapter.name,
+        balances=balances,
+    )
+    log.info("Collection finished in %.1fs", time.time() - col_start)
+    return slug
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="[%(asctime)s] %(message)s",
+        datefmt="%H:%M:%S",
+        stream=sys.stdout,
+    )
+    log = logging.getLogger("alphatrack")
+
+    try:
+        config = load_user_config(args.config)
+    except (FileNotFoundError, ValueError) as e:
+        log.error("%s", e)
+        return 1
+
+    try:
+        opts = resolve_check_options(args, config)
+    except ValueError as e:
+        log.error("%s", e)
+        return 1
+
+    jobs = opts["jobs"]
+    if not jobs:
+        log.error(
+            "No collections specified. Add a `checks:` block (or legacy "
+            "`collections:`) in config.yaml, or pass -c/--collection."
+        )
+        return 1
+
+    if args.config:
+        log.info("Using config: %s", args.config)
+    elif config:
+        log.info("Using config: config.yaml")
+
+    wallets = load_wallets(opts["wallets"])
+    log.info("Loaded %d wallet(s) from %s", len(wallets), opts["wallets"])
+
+    total_collections = sum(len(j["collections"]) for j in jobs)
+    log.info(
+        "Jobs: %d platform block(s), %d collection(s) total",
+        len(jobs),
+        total_collections,
+    )
+
+    total_start = time.time()
+    done = 0
+    for job in jobs:
+        platform = job["platform"]
+        try:
+            adapter = get_adapter(platform)
+        except ValueError as e:
+            log.error("%s", e)
+            return 1
+
+        log.info("Platform: %s (%d collection(s))", adapter.name, len(job["collections"]))
+        for collection_ref in job["collections"]:
+            done += 1
+            slug = adapter.normalize_collection(collection_ref)
+            log.info("[%d/%d] Checking %s/%s", done, total_collections, adapter.name, slug)
+            _run_collection(adapter, wallets, collection_ref, opts["balances"], log)
+
+    log.info("Done in %.1fs", time.time() - total_start)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "platforms":
+        return _cmd_platforms()
+    if args.command == "check":
+        return _cmd_check(args)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

alphatrack/core/__init__.py

@@ -0,0 +1,9 @@
+from alphatrack.core.models import EligibilityResult, StageResult, Wallet
+from alphatrack.core.wallets import load_wallets
+
+__all__ = [
+    "EligibilityResult",
+    "StageResult",
+    "Wallet",
+    "load_wallets",
+]

alphatrack/core/balance.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+from decimal import Decimal, getcontext
+from typing import Dict, List, Optional
+
+import requests
+from dotenv import load_dotenv
+
+getcontext().prec = 28
+load_dotenv()
+
+ALCHEMY_NETWORK = "eth-mainnet"
+
+
+def _hex_to_eth(balance_hex: str) -> float:
+    raw = int(balance_hex or "0x0", 16)
+    return float(Decimal(raw) / Decimal(10**18))
+
+
+def fetch_eth_balance(address: str, api_key: Optional[str] = None) -> float:
+    """Fetch native ETH balance for a single wallet via Alchemy."""
+    api_key = api_key or os.getenv("ALCHEMY_API_KEY")
+    if not api_key:
+        raise ValueError("ALCHEMY_API_KEY not set (required for balance checks)")
+
+    endpoint = f"https://api.g.alchemy.com/data/v1/{api_key}/assets/tokens/by-address"
+    payload = {
+        "addresses": [{"address": address.lower(), "networks": [ALCHEMY_NETWORK]}],
+        "omitMetadata": True,
+        "pageSize": 200,
+        "includeNativeBalances": True,
+    }
+    response = requests.post(endpoint, json=payload, timeout=30)
+    if not response.ok:
+        detail = response.text[:200]
+        raise requests.HTTPError(
+            f"{response.status_code} from Alchemy: {detail}",
+            response=response,
+        )
+
+    for token in response.json().get("data", {}).get("tokens") or []:
+        if token.get("tokenAddress") is None:
+            return _hex_to_eth(token.get("tokenBalance"))
+    return 0.0
+
+
+def fetch_eth_balances(
+    addresses: List[str],
+    api_key: Optional[str] = None,
+) -> Dict[str, float]:
+    """Fetch native ETH balances one wallet at a time."""
+    balances: Dict[str, float] = {}
+    for addr in addresses:
+        normalized = addr.lower()
+        balances[normalized] = fetch_eth_balance(normalized, api_key=api_key)
+    return balances

alphatrack/core/config.py

@@ -0,0 +1,10 @@
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Keep low to avoid 429s on marketplace auth endpoints
+WORKERS = int(os.getenv("ALPHATRACK_WORKERS", "2"))
+GAS_BUFFER_ETH = float(os.getenv("ALPHATRACK_GAS_BUFFER_ETH", "0.005"))
+SUBMIT_STAGGER_SEC = float(os.getenv("ALPHATRACK_SUBMIT_STAGGER_SEC", "0.8"))

alphatrack/core/models.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class Wallet:
+    private_key: str
+    address: str
+    group: Optional[str] = None
+    label: Optional[str] = None
+
+
+@dataclass
+class StageResult:
+    stage_index: int
+    stage_type: str
+    label: str
+    is_eligible: bool
+    max_mint: Optional[int] = None
+    price_eth: Optional[float] = None
+    price_symbol: str = "ETH"
+    start_time: Optional[str] = None
+    end_time: Optional[str] = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EligibilityResult:
+    address: str
+    platform: str
+    collection: str
+    stages: list[StageResult] = field(default_factory=list)
+    error: Optional[str] = None

alphatrack/core/report.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from alphatrack.core.config import GAS_BUFFER_ETH
+from alphatrack.core.models import EligibilityResult, StageResult, Wallet
+
+
+def _format_mint_time(start: Optional[str], end: Optional[str]) -> str:
+    if not start:
+        return ""
+    start_dt = datetime.fromisoformat(start.replace("Z", "+00:00"))
+    if not end:
+        return start_dt.strftime("%b %d %H:%M UTC")
+    end_dt = datetime.fromisoformat(end.replace("Z", "+00:00"))
+    if start_dt.date() == end_dt.date():
+        return f"{start_dt.strftime('%b %d %H:%M')}–{end_dt.strftime('%H:%M UTC')}"
+    return f"{start_dt.strftime('%b %d %H:%M')} → {end_dt.strftime('%b %d %H:%M UTC')}"
+
+
+def _required_eth(price: Optional[float], max_mint: Optional[int]) -> Optional[float]:
+    if price is None or max_mint is None:
+        return None
+    return price * max_mint + GAS_BUFFER_ETH
+
+
+def _format_balance_status(balance: float, required: Optional[float]) -> str:
+    if required is None:
+        return f"{balance:.4g} ETH"
+    if balance >= required:
+        return f"{balance:.4g} ETH  ✓"
+    return f"{balance:.4g} ETH  ✗ need ≥{required:.4g} ETH"
+
+
+def _stage_heading(stage: StageResult) -> str:
+    price = (
+        f"{stage.price_eth:.4g} {stage.price_symbol}"
+        if stage.price_eth is not None
+        else "?"
+    )
+    label = stage.label or stage.stage_type
+    return f"{label} ({price})"
+
+
+def print_summary(
+    wallets: List[Wallet],
+    results: Dict[str, EligibilityResult],
+    collection: str,
+    platform: str = "opensea",
+    balances: Optional[Dict[str, float]] = None,
+) -> None:
+    sep = "=" * 60
+    print(f"\n{sep}")
+    print(f"PLATFORM: {platform}")
+    print(f"COLLECTION: {collection}")
+    print(f"{sep}")
+
+    # Pick a non-empty stage list as the template for ordering
+    all_stages: List[StageResult] = []
+    for result in results.values():
+        if result.stages:
+            type_order = {"SIGNED_PRESALE": 0, "PUBLIC_SALE": 1}
+            all_stages = sorted(
+                result.stages,
+                key=lambda s: (type_order.get(s.stage_type, 99), s.stage_index),
+            )
+            break
+
+    if not all_stages:
+        print("  No stage data returned.")
+        print(sep)
+        return
+
+    addr_to_group = {w.address: w.group for w in wallets}
+    eligible_by_stage: Dict[int, list] = {s.stage_index: [] for s in all_stages}
+
+    for wallet in wallets:
+        addr = wallet.address
+        result = results.get(addr)
+        if not result or result.error:
+            continue
+        by_idx = {s.stage_index: s for s in result.stages}
+        for stage in all_stages:
+            s = by_idx.get(stage.stage_index)
+            if s and s.is_eligible:
+                eligible_by_stage[stage.stage_index].append(
+                    (addr, s.max_mint, addr_to_group.get(addr), s)
+                )
+
+    for stage in all_stages:
+        if stage.stage_type == "PUBLIC_SALE":
+            continue
+
+        eligible = eligible_by_stage[stage.stage_index]
+        time_str = _format_mint_time(stage.start_time, stage.end_time)
+        time_part = f"  —  {time_str}" if time_str else ""
+
+        funded = 0
+        if balances and stage.price_eth is not None:
+            for addr, max_mint, _, _ in eligible:
+                required = _required_eth(stage.price_eth, max_mint)
+                if required is not None and balances.get(addr.lower(), 0) >= required:
+                    funded += 1
+
+        funded_part = ""
+        if balances and stage.price_eth is not None and eligible:
+            funded_part = f"  —  {funded}/{len(eligible)} can afford mint"
+
+        print(
+            f"\n  {_stage_heading(stage)}{time_part}  —  "
+            f"{len(eligible)} eligible wallet(s){funded_part}"
+        )
+        print("  " + "-" * 40)
+
+        if not eligible:
+            print("    (none)")
+            continue
+
+        for addr, max_mint, group, _ in eligible:
+            group_str = f"  [{group}]" if group else ""
+            bal_str = ""
+            if balances is not None:
+                bal = balances.get(addr.lower(), 0.0)
+                required = _required_eth(stage.price_eth, max_mint)
+                bal_str = f"  {_format_balance_status(bal, required)}"
+            print(f"    {addr}{group_str}  (max {max_mint}){bal_str}")
+
+    errors = [(a, r.error) for a, r in results.items() if r.error]
+    if errors:
+        print(f"\n  Errors ({len(errors)}):")
+        for addr, err in errors:
+            print(f"    {addr[:12]}... — {err}")
+
+    print(f"\n{sep}")

alphatrack/core/user_config.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+DEFAULT_CONFIG_PATHS = ("config.yaml", "config.yml")
+
+
+def load_user_config(path: str | Path | None = None) -> dict[str, Any]:
+    """
+    Load a local YAML config.
+
+    If path is None, tries ./config.yaml then ./config.yml.
+    Returns {} when no config file is found.
+    """
+    if path is not None:
+        file_path = Path(path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"Config file not found: {file_path}")
+        return _read_yaml(file_path)
+
+    for candidate in DEFAULT_CONFIG_PATHS:
+        file_path = Path(candidate)
+        if file_path.exists():
+            return _read_yaml(file_path)
+    return {}
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    data = yaml.safe_load(path.read_text()) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"Config root must be a mapping: {path}")
+    return data
+
+
+def _normalize_collections(raw: Any) -> list[str]:
+    if raw is None:
+        return []
+    if isinstance(raw, str):
+        return [raw.strip()] if raw.strip() else []
+    return [str(c).strip() for c in raw if str(c).strip()]
+
+
+def _jobs_from_checks_block(raw_checks: Any, default_platform: str) -> list[dict[str, Any]]:
+    if not isinstance(raw_checks, list):
+        raise ValueError("`checks` must be a list of platform blocks")
+
+    jobs: list[dict[str, Any]] = []
+    for i, block in enumerate(raw_checks):
+        if not isinstance(block, dict):
+            raise ValueError(f"`checks[{i}]` must be a mapping with platform/collections")
+        platform = str(block.get("platform") or default_platform)
+        collections = _normalize_collections(block.get("collections"))
+        if not collections:
+            raise ValueError(f"`checks[{i}]` has no collections")
+        jobs.append({"platform": platform, "collections": collections})
+    return jobs
+
+
+def _jobs_from_config(cfg: dict[str, Any]) -> list[dict[str, Any]]:
+    default_platform = str(cfg.get("platform") or "opensea")
+
+    if cfg.get("checks") is not None:
+        return _jobs_from_checks_block(cfg.get("checks"), default_platform)
+
+    # Legacy / simple shape: top-level platform + collections
+    collections = _normalize_collections(cfg.get("collections"))
+    if collections:
+        return [{"platform": default_platform, "collections": collections}]
+    return []
+
+
+def resolve_check_options(args: Any, config: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+    """
+    Merge CLI over config over built-in defaults.
+
+    Returns:
+      wallets, balances, jobs: [{platform, collections}, ...]
+    """
+    cfg = config or {}
+    default_platform = str(args.platform or cfg.get("platform") or "opensea")
+    wallets = args.wallets or cfg.get("wallets") or "wallets.txt"
+
+    if args.balances:
+        balances = True
+    elif "balances" in cfg:
+        balances = bool(cfg["balances"])
+    else:
+        balances = False
+
+    # CLI -c wins: single job (optionally with -p)
+    cli_collections = _normalize_collections(args.collections)
+    if cli_collections:
+        jobs = [{"platform": default_platform, "collections": cli_collections}]
+    else:
+        jobs = _jobs_from_config(cfg)
+        # If user passed -p with checks/legacy config, force that platform on all jobs
+        if args.platform:
+            jobs = [
+                {"platform": str(args.platform), "collections": j["collections"]}
+                for j in jobs
+            ]
+
+    return {
+        "wallets": str(wallets),
+        "balances": balances,
+        "jobs": jobs,
+    }

alphatrack/core/wallets.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from eth_account import Account
+
+from alphatrack.core.models import Wallet
+
+
+def load_wallets(path: str | Path = "wallets.txt") -> list[Wallet]:
+    """
+    Load wallets from a text file.
+
+    - One private key per line
+    - Blank lines ignored
+    - Lines starting with # are optional group labels for following keys
+    """
+    file_path = Path(path)
+    if not file_path.exists():
+        raise FileNotFoundError(
+            f"Wallet file not found: {file_path}. "
+            "Copy wallets.example.txt to wallets.txt and add burner keys."
+        )
+
+    wallets: list[Wallet] = []
+    current_group: str | None = None
+
+    for line in file_path.read_text().splitlines():
+        raw = line.strip()
+        if not raw:
+            continue
+        if raw.startswith("#"):
+            current_group = raw.lstrip("#").strip() or None
+            continue
+
+        account = Account.from_key(raw)
+        wallets.append(
+            Wallet(
+                private_key=raw,
+                address=account.address,
+                group=current_group,
+            )
+        )
+
+    if not wallets:
+        raise ValueError(f"No private keys found in {file_path}")
+
+    return wallets

alphatrack-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,22 @@
+alphatrack/__init__.py,sha256=wCg1JuPhnnHsoarYPpFnud_aWtoLvGuWDsJCS_2eRpI,87
+alphatrack/__main__.py,sha256=e_v2QFfP_9REcQy2f87yFyQuhuU9TG1_LS5ftlZ8B18,89
+alphatrack/cli.py,sha256=tWNcwsYbazNkXxJFJnEh2SN3QtOWB3BvzSxx0crXkx8,5934
+alphatrack/adapters/__init__.py,sha256=NHMNE5J_xyNfQ_dfdzrPiFBxyk0cQD7QrYDCRrFWu20,152
+alphatrack/adapters/base.py,sha256=ABeaGL6O1BB18yrWDbZEQylUhRefvVGXtjM45MjPe98,1835
+alphatrack/adapters/opensea/__init__.py,sha256=p9ht6b5P7X-4dTkaBS_BEiLg8H4UdGc09PnOe8-ca7w,93
+alphatrack/adapters/opensea/auth.py,sha256=1m1k8NVAlTcINsdCwpXjWOmyGTlqV-QZ29dbsLV6jB0,3799
+alphatrack/adapters/opensea/checker.py,sha256=-VPFtMYjV0KL4WOhna-721XMaFCOKBzUDuuhvjIR1c8,5632
+alphatrack/adapters/opensea/client.py,sha256=YIpQiin_f4zmDo8R186q7m9UScWA0H7Sa8PhZMg0cYE,2869
+alphatrack/core/__init__.py,sha256=5Ptw1iJ-O7aSknITPU7bfxOxa9jdgKbneNzSC13iBmQ,216
+alphatrack/core/balance.py,sha256=aiSQj7pF5sPZkW6PVdKQFtLfOAVoVnP84U3xJIrvChc,1787
+alphatrack/core/config.py,sha256=_k_Si4cO_Xf9L0nj5JVZ2QlqkVTbkRL9fMd_Dh_XjiY,315
+alphatrack/core/models.py,sha256=JRtEYXa4E1rWUIDNoo2g6MNPcMNik7CCvBzI9D2lsMA,763
+alphatrack/core/report.py,sha256=iqfDYPsGnrTPNBL5vHkF_TYzd1Xmv7RvtwzJx08AQMo,4636
+alphatrack/core/user_config.py,sha256=Dl1WKh4qcT_6Jrwht5XwLUr1CyilCgpAaFOUXv-ft-M,3615
+alphatrack/core/wallets.py,sha256=j1TFkuGh8Nih_BHE206CU1E3BSmZzTZfceqpYmWRlX0,1247
+alphatrack-0.1.0.dist-info/licenses/LICENSE,sha256=YOOCHjpsNjO6RXVOaYeuWLAkKks65W5Eh1EZtbDOS1Q,1067
+alphatrack-0.1.0.dist-info/METADATA,sha256=l7w23SBxdtIc9jGdurKmPE_2L5Ur76r6_YW_4o5Pxz8,2994
+alphatrack-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+alphatrack-0.1.0.dist-info/entry_points.txt,sha256=eXkfw7dLAhw70bwKDLI-E3x4_9kWIUlVktiMeYKM5fI,51
+alphatrack-0.1.0.dist-info/top_level.txt,sha256=2NhSOYi2MUXVpwSD7pM2G_cLkCN8_uEV10X8wBMBgrU,11
+alphatrack-0.1.0.dist-info/RECORD,,

alphatrack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

alphatrack-0.1.0.dist-info/entry_points.txt

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

alphatrack-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+alphatrack