crypttrace 0.17.0__tar.gz → 0.18.0__tar.gz

{crypttrace-0.17.0/src/crypttrace.egg-info → crypttrace-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.17.0
+Version: 0.18.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -104,6 +104,7 @@ export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
 export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
+export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -537,6 +538,13 @@ accounts. These become labels of kind `explorer-tag`, cached for a week. A
 "kucoin-1.ton" — is not taken as a label. A trace stops at a DEX: the funds
 come back to the sender in another token.
 
+**Tron: tags from Tronscan.** With a free Tronscan API key (`TRONSCAN_API_KEY`,
+created in a Tronscan account), Tron addresses the curated set does not know
+get Tronscan's tags: exchange wallets ("Binance-Cold 1", "Okex 1") become
+exchange labels and a red tag (scam, phishing) makes the address a scam — both
+as `explorer-tag` labels naming Tronscan as the source, cached for a week.
+Without a key nothing is fetched.
+
 **Exchange deposits with a memo.** A TON exchange takes all customers' deposits
 into one hot wallet and tells them apart by the transfer comment, the *memo*.
 The memo is the lead: it names one account at the exchange, which holds that

{crypttrace-0.17.0 → crypttrace-0.18.0}/README.md

@@ -70,6 +70,7 @@ export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
 export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
+export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -503,6 +504,13 @@ accounts. These become labels of kind `explorer-tag`, cached for a week. A
 "kucoin-1.ton" — is not taken as a label. A trace stops at a DEX: the funds
 come back to the sender in another token.
 
+**Tron: tags from Tronscan.** With a free Tronscan API key (`TRONSCAN_API_KEY`,
+created in a Tronscan account), Tron addresses the curated set does not know
+get Tronscan's tags: exchange wallets ("Binance-Cold 1", "Okex 1") become
+exchange labels and a red tag (scam, phishing) makes the address a scam — both
+as `explorer-tag` labels naming Tronscan as the source, cached for a week.
+Without a key nothing is fetched.
+
 **Exchange deposits with a memo.** A TON exchange takes all customers' deposits
 into one hot wallet and tells them apart by the transfer comment, the *memo*.
 The memo is the lead: it names one account at the exchange, which holds that

{crypttrace-0.17.0 → crypttrace-0.18.0}/src/crypttrace/__init__.py

@@ -1,2 +1,2 @@
 """crypttrace — OSINT crypto investigation CLI."""
-__version__ = "0.17.0"
+__version__ = "0.18.0"

{crypttrace-0.17.0 → crypttrace-0.18.0}/src/crypttrace/labels/labels.py

@@ -17,7 +17,7 @@ from typing import Optional, Dict, List
 import requests
 
 from crypttrace import addresses, config
-from crypttrace.labels import bulk, tonapi
+from crypttrace.labels import bulk, tonapi, tronscan
 
 _HERE = Path(__file__).parent
 _IMPORTED = config.DATA_DIR / "imported_labels.json"
@@ -189,15 +189,19 @@ def lookup(address: str) -> Optional[dict]:
     found = _match_partial(address) or bulk.lookup(address)
     if not found and (len(address) == 48 or ":" in address):
         found = tonapi.lookup(address)              # cached explorer tag, no network here
+    elif not found and len(address) == 34 and address.startswith("T"):
+        found = tronscan.lookup(address)
     return found
 
 
 def enrich(addrs, chain: str) -> None:
-    """Fetch explorer tags the curated set lacks (TON: tonapi names). Network, cached."""
+    """Fetch explorer tags the curated set lacks (TON: tonapi, Tron: Tronscan). Network, cached."""
+    _load()
     if chain == "ton":
-        _load()
         tonapi.enrich(a for a in addrs
                       if a and not _KNOWN.get((addresses.ton_friendly(a) or a).lower()))
+    elif chain == "tron":
+        tronscan.enrich(a for a in addrs if a and not _KNOWN.get(a.lower()))
 
 
 def is_deposit(address: str) -> bool:

crypttrace-0.18.0/src/crypttrace/labels/names.py

@@ -0,0 +1,8 @@
+"""Exchange names as explorers spell them — shared by the explorer-tag sources."""
+import re
+
+# custodial platforms that hold KYC and can freeze: a deposit there is a lead
+EXCHANGES = re.compile(
+    r"\b(binance|bybit|okx|okex|kucoin|htx|huobi|gate(\.io)?|mexc|bitget|kraken|coinbase|"
+    r"bitfinex|bingx|bitmart|lbank|whitebit|exmo|coinex|poloniex|crypto\.com|bitpanda|"
+    r"bithumb|upbit|cryptobot|crypto bot|xrocket|wallet in telegram|telegram wallet)\b", re.I)

{crypttrace-0.17.0 → crypttrace-0.18.0}/src/crypttrace/labels/tonapi.py

@@ -26,6 +26,7 @@ import requests
 
 from crypttrace import addresses, config
 from crypttrace.fetchers import http
+from crypttrace.labels.names import EXCHANGES
 
 API = "https://tonapi.io/v2/accounts/{}"
 CACHE = config.DATA_DIR / "tonapi_names.json"
@@ -33,12 +34,6 @@ MAX_AGE = 7 * 24 * 3600
 _KEY = os.environ.get("TONAPI_KEY")
 http.MIN_INTERVAL["tonapi.io"] = 0.12 if _KEY else 1.1
 
-# custodial platforms that hold KYC and can freeze: a deposit there is a lead
-_EXCHANGES = re.compile(
-    r"\b(binance|bybit|okx|okex|kucoin|htx|huobi|gate(\.io)?|mexc|bitget|kraken|coinbase|"
-    r"bitfinex|bingx|bitmart|lbank|whitebit|exmo|coinex|poloniex|crypto\.com|bitpanda|"
-    r"bithumb|upbit|cryptobot|crypto bot|xrocket|wallet in telegram|telegram wallet)\b", re.I)
-
 _cache: Optional[Dict[str, dict]] = None
 
 
@@ -73,7 +68,7 @@ def classify(account: dict) -> Optional[dict]:
         return {"name": name or "DEX contract", "type": "dex"}
     if not name or self_named:
         return None
-    if _EXCHANGES.search(name):
+    if EXCHANGES.search(name):
         memo = " (memo required)" if account.get("memo_required") else ""
         return {"name": f"{name}{memo}", "type": "exchange", "memo_required": bool(account.get("memo_required"))}
     return {"name": name, "type": "service"}

crypttrace-0.18.0/src/crypttrace/labels/tronscan.py

@@ -0,0 +1,105 @@
+"""Tron address tags from Tronscan — exchange wallets and risk warnings.
+
+Tronscan tags exchange hot and cold wallets ("Binance-Cold 1", "OKX-Hot") and
+puts red tags on addresses it flags as scams or phishing. Both become labels
+of kind "explorer-tag", with Tronscan named as the source; a red tag makes the
+address a scam. Grey tags and user feedback are not enough to call an address
+anything.
+
+Needs a free API key (TRONSCAN_API_KEY, created in a Tronscan account); without
+one nothing is fetched and Tron labels come from the curated set alone.
+Lookups are cached on disk for a week; only `enrich()` uses the network.
+"""
+import datetime as dt
+import json
+import os
+import sys
+import time
+from typing import Dict, Iterable, Optional
+
+import requests
+
+from crypttrace import config
+from crypttrace.fetchers import http
+from crypttrace.labels.names import EXCHANGES
+
+API = "https://apilist.tronscanapi.com/api/accountv2"
+CACHE = config.DATA_DIR / "tronscan_tags.json"
+MAX_AGE = 7 * 24 * 3600
+http.MIN_INTERVAL["apilist.tronscanapi.com"] = 0.25
+_cache: Optional[Dict[str, dict]] = None
+
+
+def _key() -> Optional[str]:
+    k = os.environ.get("TRONSCAN_API_KEY")
+    if not k and sys.platform == "win32":          # set with [Environment]::SetEnvironmentVariable(..., "User")
+        try:
+            import winreg
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as reg:
+                k = winreg.QueryValueEx(reg, "TRONSCAN_API_KEY")[0]
+        except OSError:
+            k = None
+    return (k or "").strip() or None
+
+
+def _load() -> Dict[str, dict]:
+    global _cache
+    if _cache is None:
+        try:
+            _cache = json.loads(CACHE.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            _cache = {}
+    return _cache
+
+
+def _save() -> None:
+    try:
+        CACHE.parent.mkdir(parents=True, exist_ok=True)
+        tmp = CACHE.with_suffix(".tmp")
+        tmp.write_text(json.dumps(_load(), ensure_ascii=False), encoding="utf-8")
+        tmp.replace(CACHE)
+    except OSError:
+        pass
+
+
+def classify(account: dict) -> Optional[dict]:
+    """A label from one Tronscan account record, or None if it names nothing."""
+    red = (account.get("redTag") or "").strip()
+    tag = (account.get("publicTag") or account.get("addressTag") or "").strip()
+    if red:
+        return {"name": f"{tag or red} (Tronscan: {red})", "type": "scam"}
+    if not tag:
+        return None
+    if EXCHANGES.search(tag.replace("-", " ")):
+        return {"name": tag, "type": "exchange"}
+    return {"name": tag, "type": "service"}
+
+
+def lookup(address: str) -> Optional[dict]:
+    """Cached Tronscan label, without touching the network."""
+    entry = _load().get(address)
+    if not entry or not entry.get("label"):
+        return None
+    return {**entry["label"], "chain": "tron", "source_kind": "explorer-tag",
+            "source": f"Tronscan address tag, fetched {entry.get('day', '')}"}
+
+
+def enrich(addrs: Iterable[str]) -> None:
+    """Fetch Tronscan tags for addresses not in the cache (or stale). No key, no fetch."""
+    key = _key()
+    if not key:
+        return
+    cache, now, changed = _load(), time.time(), False
+    for a in dict.fromkeys(addrs):
+        if not a or not a.startswith("T") or len(a) != 34 or now - cache.get(a, {}).get("at", 0) < MAX_AGE:
+            continue
+        try:
+            rec = http.request_json(API, {"address": a}, timeout=20, headers={"TRON-PRO-API-KEY": key})
+        except (http.RateLimited, requests.RequestException, ValueError):
+            continue
+        if not isinstance(rec, dict) or "__status__" in rec:
+            continue
+        cache[a] = {"at": now, "day": dt.date.today().isoformat(), "label": classify(rec)}
+        changed = True
+    if changed:
+        _save()

{crypttrace-0.17.0 → crypttrace-0.18.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.17.0
+Version: 0.18.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -104,6 +104,7 @@ export TRONGRID_API_KEY=xxxx            # optional: higher TronGrid quota
 export CRYPTTRACE_SOLANA_RPC=https://…  # optional: your own (faster) Solana RPC
 export TONCENTER_API_KEY=xxxx          # optional: toncenter allows ~1 request/s without it
 export TONAPI_KEY=xxxx                 # optional: faster tonapi name lookups on TON
+export TRONSCAN_API_KEY=xxxx           # optional: Tron exchange and scam tags from Tronscan
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -537,6 +538,13 @@ accounts. These become labels of kind `explorer-tag`, cached for a week. A
 "kucoin-1.ton" — is not taken as a label. A trace stops at a DEX: the funds
 come back to the sender in another token.
 
+**Tron: tags from Tronscan.** With a free Tronscan API key (`TRONSCAN_API_KEY`,
+created in a Tronscan account), Tron addresses the curated set does not know
+get Tronscan's tags: exchange wallets ("Binance-Cold 1", "Okex 1") become
+exchange labels and a red tag (scam, phishing) makes the address a scam — both
+as `explorer-tag` labels naming Tronscan as the source, cached for a week.
+Without a key nothing is fetched.
+
 **Exchange deposits with a memo.** A TON exchange takes all customers' deposits
 into one hot wallet and tells them apart by the transfer comment, the *memo*.
 The memo is the lead: it names one account at the exchange, which holds that

{crypttrace-0.17.0 → crypttrace-0.18.0}/src/crypttrace.egg-info/SOURCES.txt

@@ -44,6 +44,8 @@ src/crypttrace/labels/audit.py
 src/crypttrace/labels/bulk.py
 src/crypttrace/labels/known.json
 src/crypttrace/labels/labels.py
+src/crypttrace/labels/names.py
 src/crypttrace/labels/partial.json
 src/crypttrace/labels/tonapi.py
+src/crypttrace/labels/tronscan.py
 src/crypttrace/web/index.html