crypttrace 0.17.0__tar.gz → 0.19.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.17.0
+Version: 0.19.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
@@ -681,7 +689,6 @@ cases/             # worked investigations with their data
 - More exchanges on Bitcoin, Tron, Solana (now: Binance, OKX, HTX, Bybit) and
   TON (now: Binance),
   and refreshing these lists as the exchanges republish them
-- Internal transactions (completes `funder` and contract-mediated transfers)
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets
 - Entity clustering on EVM via the gas-funding heuristic
 

{crypttrace-0.17.0 → crypttrace-0.19.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
@@ -647,7 +655,6 @@ cases/             # worked investigations with their data
 - More exchanges on Bitcoin, Tron, Solana (now: Binance, OKX, HTX, Bybit) and
   TON (now: Binance),
   and refreshing these lists as the exchanges republish them
-- Internal transactions (completes `funder` and contract-mediated transfers)
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets
 - Entity clustering on EVM via the gas-funding heuristic
 

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

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

{crypttrace-0.17.0 → crypttrace-0.19.0}/src/crypttrace/chains.py

@@ -102,15 +102,26 @@ def balance(address: str, chain: str = "eth") -> float:
 # ---------- normalized row builders ----------
 
 def _evm_native(address: str, chain: str, limit: int) -> List[Dict]:
+    """The native coin moved: normal transactions plus internal ones (sent by contracts —
+    withdrawals from mixers and exchanges, ETH back from swaps). Failed calls moved nothing."""
     rows = []
-    for tx in etherscan.get_txs(address, chain, limit=limit):
+    calls = [(tx, False) for tx in etherscan.get_txs(address, chain, limit=limit)]
+    calls += [(tx, True) for tx in etherscan.get_internal_txs(address, chain, limit=limit)]
+    for tx, internal in calls:
+        if str(tx.get("isError", "0")) == "1":
+            continue
         try:
             val = int(tx.get("value", 0)) / config.WEI
         except (TypeError, ValueError):
             val = 0.0
-        rows.append({"from": tx.get("from", "").lower(), "to": tx.get("to", "").lower(),
-                     "value": val, "timestamp": int(tx.get("timeStamp", "0") or 0),
-                     "hash": tx.get("hash", ""), "symbol": symbol(chain)})
+        if internal and val <= 0:
+            continue
+        row = {"from": tx.get("from", "").lower(), "to": (tx.get("to") or "").lower(),
+               "value": val, "timestamp": int(tx.get("timeStamp", "0") or 0),
+               "hash": tx.get("hash", ""), "symbol": symbol(chain)}
+        if internal:
+            row["internal"] = True
+        rows.append(row)
     return rows
 
 

{crypttrace-0.17.0 → crypttrace-0.19.0}/src/crypttrace/config.py

@@ -1,7 +1,22 @@
 """Configuration and shared constants."""
 import os
+import sys
 from pathlib import Path
 
+
+def env(name: str, default: str = "") -> str:
+    """An environment variable — falling back, on Windows, to the user environment, so a key
+    saved with [Environment]::SetEnvironmentVariable(..., "User") works in an already-open shell."""
+    value = os.environ.get(name)
+    if not value and sys.platform == "win32":
+        try:
+            import winreg
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as reg:
+                value = winreg.QueryValueEx(reg, name)[0]
+        except OSError:
+            value = None
+    return (value or default).strip()
+
 # Data dir for cache + labels (created on first run)
 DATA_DIR = Path(os.environ.get("CRYPTTRACE_HOME", Path.home() / ".crypttrace"))
 DATA_DIR.mkdir(parents=True, exist_ok=True)
@@ -11,7 +26,7 @@ CACHE_DB = DATA_DIR / "cache.sqlite"
 # Etherscan v2 API. One key works across all EVM chains via chainid param.
 # Get a free key at https://etherscan.io/myapikey and export it:
 #   export ETHERSCAN_API_KEY=xxxx
-ETHERSCAN_API_KEY = os.environ.get("ETHERSCAN_API_KEY", "")
+ETHERSCAN_API_KEY = env("ETHERSCAN_API_KEY")
 ETHERSCAN_BASE = "https://api.etherscan.io/v2/api"
 
 # Supported EVM chains: name -> chainid

{crypttrace-0.17.0 → crypttrace-0.19.0}/src/crypttrace/fetchers/etherscan.py

@@ -104,6 +104,19 @@ def get_txs(address: str, chain: str = "eth", limit: int = 1000,
     return result if isinstance(result, list) else []
 
 
+def get_internal_txs(address: str, chain: str = "eth", limit: int = 1000,
+                     sort: str = "desc") -> List[dict]:
+    """Internal transactions: the native coin a contract sent or received as part of a call
+    (a mixer or exchange withdrawal, ETH back from a DEX swap, a multisig payout)."""
+    data = _call(chain, {
+        "module": "account", "action": "txlistinternal", "address": address,
+        "startblock": "0", "endblock": "99999999",
+        "page": "1", "offset": str(limit), "sort": sort,
+    })
+    result = data.get("result")
+    return result if isinstance(result, list) else []
+
+
 def get_token_txs(address: str, chain: str = "eth", limit: int = 1000) -> List[dict]:
     """ERC-20 token transfers, newest first."""
     data = _call(chain, {

{crypttrace-0.17.0 → crypttrace-0.19.0}/src/crypttrace/labels/known.json

@@ -10,10 +10,10 @@
   "0x1522900b6dafac587d499a862861c0869be6e428": {"name": "OKX", "type": "exchange"},
   "0x2faf487a4414fe77e2327f0bf4ae2a264a776ad2": {"name": "FTX (defunct)", "type": "exchange"},
   "0x722122df12d4e14e13ac3b6895a86e84145b6967": {"name": "Tornado Cash: Router", "type": "mixer"},
-  "0xd90e2f925da726b50c4ed8d0fb90ad053324f31b": {"name": "Tornado Cash: 0.1 ETH", "type": "mixer"},
+  "0xd90e2f925da726b50c4ed8d0fb90ad053324f31b": {"name": "Tornado Cash: router", "type": "mixer", "chain": "eth", "source": "own check of its internal transactions (2026-10-17): pays out withdrawals of the 0.1, 1 and 10 ETH pools, so a router, not the 0.1 ETH pool it was labelled as", "source_kind": "research", "added": "2026-10-17"},
   "0x910cbd523d972eb0a6f4cae4618ad62622b39dbf": {"name": "Tornado Cash: 10 ETH", "type": "mixer"},
   "0xa160cdab225685da1d56aa342ad8841c3b53f291": {"name": "Tornado Cash: 100 ETH", "type": "mixer"},
-  "0x12d66f87a04a9e220743712ce6d9bb1b5616b8fc": {"name": "Tornado Cash: 1 ETH", "type": "mixer"},
+  "0x12d66f87a04a9e220743712ce6d9bb1b5616b8fc": {"name": "Tornado Cash: 0.1 ETH", "type": "mixer", "chain": "eth", "source": "own check of its internal transactions (2026-10-17): every withdrawal pays out 0.1 ETH in total (recipient plus relayer fee); was labelled 1 ETH", "source_kind": "research", "added": "2026-10-17"},
   "0x3ee18b2214aff97000d974cf647e7c347e8fa585": {"name": "Wormhole: Token Bridge", "type": "bridge"},
   "0x99c9fc46f92e8a1c0dec1b1747d010903e884be1": {"name": "Optimism: Gateway (L1 Bridge)", "type": "bridge"},
   "0x4dbd4fc535ac27206064b68ffcf827b0a60bab3f": {"name": "Arbitrum: Delayed Inbox", "type": "bridge"},

{crypttrace-0.17.0 → crypttrace-0.19.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.19.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.19.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.19.0/src/crypttrace/labels/tronscan.py

@@ -0,0 +1,95 @@
+"""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 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]:
+    return config.env("TRONSCAN_API_KEY") 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.19.0}/src/crypttrace/store.py

@@ -86,6 +86,14 @@ def _conn() -> sqlite3.Connection:
         c.execute("DELETE FROM fetched WHERE chain='ton'")
         c.execute("PRAGMA user_version=3")
         c.commit()
+    if c.execute("PRAGMA user_version").fetchone()[0] < 4:
+        # 0.19: EVM native history now includes internal transactions — read it again
+        evm = tuple(config.CHAINS)
+        marks = ",".join("?" * len(evm))
+        c.execute(f"DELETE FROM transfers WHERE chain IN ({marks}) AND (contract IS NULL OR contract='')", evm)
+        c.execute(f"DELETE FROM fetched WHERE chain IN ({marks}) AND asset=''", evm)
+        c.execute("PRAGMA user_version=4")
+        c.commit()
     return c
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.17.0
+Version: 0.19.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
@@ -681,7 +689,6 @@ cases/             # worked investigations with their data
 - More exchanges on Bitcoin, Tron, Solana (now: Binance, OKX, HTX, Bybit) and
   TON (now: Binance),
   and refreshing these lists as the exchanges republish them
-- Internal transactions (completes `funder` and contract-mediated transfers)
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets
 - Entity clustering on EVM via the gas-funding heuristic
 

{crypttrace-0.17.0 → crypttrace-0.19.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