crypttrace 0.2.0__py3-none-any.whl

crypttrace/config.py

@@ -0,0 +1,27 @@
+"""Configuration and shared constants."""
+import os
+from pathlib import Path
+
+# 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)
+
+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_BASE = "https://api.etherscan.io/v2/api"
+
+# Supported EVM chains: name -> chainid
+CHAINS = {
+    "eth": 1,
+    "bsc": 56,
+    "polygon": 137,
+    "arbitrum": 42161,
+    "optimism": 10,
+    "base": 8453,
+}
+
+WEI = 10 ** 18

crypttrace/fetchers/bitcoin.py

@@ -0,0 +1,186 @@
+"""Bitcoin fetcher via mempool.space — no API key required.
+
+Bitcoin uses the UTXO model, not accounts: a transaction consumes previous
+outputs and creates new ones, so there is no single "from" or "to". To fit the
+same tracing engine used for EVM chains, transactions are normalized into
+directional transfer rows:
+
+  * if our address signed an input, each output that isn't ours is an outflow
+    (outputs back to ourselves are change and are skipped);
+  * otherwise, outputs paying us are inflows, attributed to the first input.
+
+Bitcoin also enables the strongest clustering heuristic in blockchain forensics:
+common-input-ownership. If several addresses sign inputs of the same
+transaction, one party almost certainly controls all of them.
+"""
+from typing import List, Dict, Optional
+
+import requests
+
+BASE = "https://mempool.space/api"
+SATS = 100_000_000
+
+
+class BitcoinError(RuntimeError):
+    pass
+
+
+def _get(path: str, timeout: int = 30):
+    """Cached, throttled GET against mempool.space."""
+    from crypttrace.fetchers import http
+    try:
+        data = http.request_json(f"{BASE}{path}", timeout=timeout)
+    except http.RateLimited as e:
+        raise BitcoinError(str(e))
+    except requests.RequestException as e:
+        raise BitcoinError(f"mempool.space request failed: {e}")
+    except ValueError as e:
+        raise BitcoinError(f"bad response from mempool.space: {e}")
+    if isinstance(data, dict) and "__status__" in data:
+        if data["__status__"] == 400:
+            raise BitcoinError("Bitcoin address rejected by mempool.space — check it is "
+                               "exact (BTC addresses are case-sensitive).")
+        raise BitcoinError("Address not found on the Bitcoin chain.")
+    return data
+
+
+def stats(address: str) -> Dict:
+    """Authoritative totals straight from the chain index.
+
+    These are the numbers our own parsing must agree with — the reference for
+    checking that a trace didn't miscount or silently miss history.
+    """
+    d = _get(f"/address/{address}")
+    cs = d.get("chain_stats", {}) or {}
+    ms = d.get("mempool_stats", {}) or {}
+    recv = (cs.get("funded_txo_sum", 0) + ms.get("funded_txo_sum", 0)) / SATS
+    sent = (cs.get("spent_txo_sum", 0) + ms.get("spent_txo_sum", 0)) / SATS
+    return {
+        "received": recv,
+        "sent": sent,
+        "balance": recv - sent,
+        "tx_count": (cs.get("tx_count", 0) + ms.get("tx_count", 0)),
+        "funded_outputs": (cs.get("funded_txo_count", 0) + ms.get("funded_txo_count", 0)),
+    }
+
+
+def balance(address: str) -> float:
+    return stats(address)["balance"]
+
+
+def raw_txs(address: str, max_txs: int = 500) -> List[dict]:
+    """Transactions touching this address, paging back through history.
+
+    mempool.space returns ~50 per call. A single page is not enough for
+    investigations: famous addresses get spammed with dust, which pushes the
+    transactions that actually matter out of the recent window. So we follow
+    the /txs/chain/:last_txid cursor until we have enough history.
+    """
+    out: List[dict] = []
+    last: Optional[str] = None
+    while len(out) < max_txs:
+        path = f"/address/{address}/txs" if last is None \
+            else f"/address/{address}/txs/chain/{last}"
+        batch = _get(path)
+        if not isinstance(batch, list) or not batch:
+            break
+        out.extend(batch)
+        if len(batch) < 25:      # last page
+            break
+        nxt = batch[-1].get("txid")
+        if not nxt or nxt == last:
+            break
+        last = nxt
+    return out[:max_txs]
+
+
+def _in_addrs(tx: dict) -> List[str]:
+    out = []
+    for v in tx.get("vin", []) or []:
+        a = (v.get("prevout") or {}).get("scriptpubkey_address")
+        if a:
+            out.append(a)
+    return out
+
+
+def _in_pairs(tx: dict):
+    """(address, value) for every input — a UTXO tx can be funded by many parties."""
+    for v in tx.get("vin", []) or []:
+        p = v.get("prevout") or {}
+        a = p.get("scriptpubkey_address")
+        if a:
+            yield a, (p.get("value", 0) or 0) / SATS
+
+
+def _out_pairs(tx: dict):
+    for o in tx.get("vout", []) or []:
+        a = o.get("scriptpubkey_address")
+        if a:
+            yield a, o.get("value", 0) / SATS
+
+
+def transfers(address: str, limit: int = 1000) -> List[Dict]:
+    """Normalized {from,to,value,timestamp,hash,symbol} rows.
+
+    A Bitcoin transaction has no single sender: it can be funded by many inputs
+    from different owners and pay many outputs. Attributing a whole transfer to
+    the first input address — the naive shortcut — badly misreports
+    consolidations, e.g. crediting one wallet with funds a hundred others
+    supplied. So value is split in proportion to what each side actually
+    contributed or received.
+    """
+    me = address
+    rows: List[Dict] = []
+    for tx in raw_txs(address, max_txs=max(limit, 200)):
+        ts = int((tx.get("status") or {}).get("block_time") or 0)
+        h = tx.get("txid", "")
+        ins = list(_in_pairs(tx))
+        outs = list(_out_pairs(tx))
+        total_in = sum(v for _, v in ins)
+        if total_in <= 0:
+            continue
+
+        if me in (a for a, _ in ins):
+            # outgoing: our share of the inputs funds our share of each output
+            mine_in = sum(v for a, v in ins if a == me)
+            share = mine_in / total_in
+            # The chain counts a spent output at full value; the recipient gets
+            # less, because the miner fee comes out in between. Carry our share
+            # of that fee so totals can be reconciled exactly rather than
+            # hidden inside a tolerance.
+            fee_share = (total_in - sum(v for _, v in outs)) * share
+            for a, v in outs:
+                if a == me or v <= 0:
+                    continue                      # change back to self
+                rows.append({"from": me, "to": a, "value": v * share,
+                             "timestamp": ts, "hash": h, "symbol": "BTC",
+                             "fee_share": fee_share})
+        else:
+            # incoming: credit every funder in proportion to what it put in
+            mine_out = sum(v for a, v in outs if a == me)
+            if mine_out <= 0:
+                continue
+            merged: Dict[str, float] = {}
+            for a, v in ins:
+                merged[a] = merged.get(a, 0.0) + v
+            for a, v in merged.items():
+                rows.append({"from": a, "to": me, "value": mine_out * (v / total_in),
+                             "timestamp": ts, "hash": h, "symbol": "BTC"})
+        if len(rows) >= limit:
+            break
+    return rows
+
+
+def cluster(address: str) -> List[tuple]:
+    """Common-input-ownership: addresses that co-signed inputs with `address`.
+
+    Returns [(address, times_seen_together)] — likely the same owner's wallets.
+    """
+    peers: Dict[str, int] = {}
+    for tx in raw_txs(address):
+        ins = _in_addrs(tx)
+        if address in ins and len(set(ins)) > 1:
+            for a in set(ins):
+                if a != address:
+                    peers[a] = peers.get(a, 0) + 1
+    return sorted(peers.items(), key=lambda kv: kv[1], reverse=True)

crypttrace/fetchers/etherscan.py

@@ -0,0 +1,114 @@
+"""Etherscan (v2 multichain) fetcher with a small SQLite cache.
+
+The blockchain is public: every transaction is queryable. This module wraps the
+Etherscan API and caches responses so repeated traces don't re-hit the API.
+"""
+import json
+import sqlite3
+import time
+from typing import List, Dict, Optional
+
+import requests
+
+from crypttrace import config
+
+
+def _db() -> sqlite3.Connection:
+    conn = sqlite3.connect(config.CACHE_DB)
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS cache ("
+        "  key TEXT PRIMARY KEY,"
+        "  ts INTEGER,"
+        "  payload TEXT)"
+    )
+    return conn
+
+
+def _cache_get(key: str, max_age: int = 3600) -> Optional[dict]:
+    conn = _db()
+    row = conn.execute("SELECT ts, payload FROM cache WHERE key=?", (key,)).fetchone()
+    conn.close()
+    if not row:
+        return None
+    ts, payload = row
+    if time.time() - ts > max_age:
+        return None
+    return json.loads(payload)
+
+
+def _cache_put(key: str, payload: dict) -> None:
+    conn = _db()
+    conn.execute(
+        "INSERT OR REPLACE INTO cache(key, ts, payload) VALUES (?,?,?)",
+        (key, int(time.time()), json.dumps(payload)),
+    )
+    conn.commit()
+    conn.close()
+
+
+class EtherscanError(RuntimeError):
+    pass
+
+
+def _call(chain: str, params: Dict[str, str], cache_age: int = 3600) -> dict:
+    if chain not in config.CHAINS:
+        raise EtherscanError(f"unsupported chain '{chain}'. Options: {list(config.CHAINS)}")
+    if not config.ETHERSCAN_API_KEY:
+        raise EtherscanError(
+            "No API key. Get a free one at https://etherscan.io/myapikey "
+            "then run: export ETHERSCAN_API_KEY=xxxx"
+        )
+    q = {
+        "chainid": config.CHAINS[chain],
+        "apikey": config.ETHERSCAN_API_KEY,
+        **params,
+    }
+    key = f"{chain}:" + "&".join(f"{k}={v}" for k, v in sorted(q.items()) if k != "apikey")
+    cached = _cache_get(key, cache_age)
+    if cached is not None:
+        return cached
+
+    resp = requests.get(config.ETHERSCAN_BASE, params=q, timeout=30)
+    resp.raise_for_status()
+    data = resp.json()
+    # status "0" with "No transactions found" is a valid empty result, not an error
+    if data.get("status") == "0" and "No transactions" not in str(data.get("message", "")):
+        # rate-limit or bad key etc.
+        if "rate limit" in str(data.get("result", "")).lower():
+            time.sleep(1)
+            return _call(chain, params, cache_age)
+        # otherwise return as-is; caller handles empty
+    _cache_put(key, data)
+    return data
+
+
+def get_balance(address: str, chain: str = "eth") -> float:
+    data = _call(chain, {"module": "account", "action": "balance",
+                         "address": address, "tag": "latest"})
+    try:
+        return int(data["result"]) / config.WEI
+    except (KeyError, ValueError):
+        return 0.0
+
+
+def get_txs(address: str, chain: str = "eth", limit: int = 1000,
+            sort: str = "desc") -> List[dict]:
+    """Normal (native-coin) transactions. sort='desc' (newest first) or 'asc' (oldest first)."""
+    data = _call(chain, {
+        "module": "account", "action": "txlist", "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, {
+        "module": "account", "action": "tokentx", "address": address,
+        "startblock": "0", "endblock": "99999999",
+        "page": "1", "offset": str(limit), "sort": "desc",
+    })
+    result = data.get("result")
+    return result if isinstance(result, list) else []

crypttrace/fetchers/http.py

@@ -0,0 +1,139 @@
+"""Shared HTTP layer for the non-EVM fetchers: caching, throttling, 429 backoff.
+
+Tracing walks many addresses, and each hop is an API call. Free endpoints
+(TronGrid, mempool.space, public Solana RPC) rate-limit aggressively, so this
+module:
+
+  * caches responses in the same SQLite file the Etherscan fetcher uses, so a
+    re-run — or an address seen twice in one trace — costs nothing;
+  * spaces requests per host so we don't trip limits in the first place;
+  * retries with exponential backoff when a 429 happens anyway.
+"""
+import json
+import sqlite3
+import threading
+import time
+from typing import Optional
+from urllib.parse import urlencode, urlparse
+
+import requests
+
+from crypttrace import config
+
+# minimum seconds between calls to the same host
+MIN_INTERVAL = {
+    "api.trongrid.io": 0.4,
+    "mempool.space": 0.25,
+    "api.mainnet-beta.solana.com": 0.3,
+}
+DEFAULT_INTERVAL = 0.25
+
+_last_call = {}
+_lock = threading.Lock()
+
+
+class RateLimited(RuntimeError):
+    pass
+
+
+def _db() -> sqlite3.Connection:
+    conn = sqlite3.connect(config.CACHE_DB)
+    conn.execute("CREATE TABLE IF NOT EXISTS cache "
+                 "(key TEXT PRIMARY KEY, ts INTEGER, payload TEXT)")
+    return conn
+
+
+def cache_get(key: str, max_age: int) -> Optional[dict]:
+    try:
+        conn = _db()
+        row = conn.execute("SELECT ts, payload FROM cache WHERE key=?", (key,)).fetchone()
+        conn.close()
+    except sqlite3.Error:
+        return None
+    if not row:
+        return None
+    ts, payload = row
+    if time.time() - ts > max_age:
+        return None
+    try:
+        return json.loads(payload)
+    except ValueError:
+        return None
+
+
+def cache_put(key: str, payload) -> None:
+    try:
+        conn = _db()
+        conn.execute("INSERT OR REPLACE INTO cache(key, ts, payload) VALUES (?,?,?)",
+                     (key, int(time.time()), json.dumps(payload)))
+        conn.commit()
+        conn.close()
+    except (sqlite3.Error, TypeError):
+        pass
+
+
+def _throttle(host: str) -> None:
+    with _lock:
+        gap = MIN_INTERVAL.get(host, DEFAULT_INTERVAL)
+        wait = gap - (time.time() - _last_call.get(host, 0.0))
+        if wait > 0:
+            time.sleep(wait)
+        _last_call[host] = time.time()
+
+
+def request_json(url: str, params: dict = None, *, body: dict = None,
+                 cache_key: str = None, ttl: int = 3600, retries: int = 3,
+                 timeout: int = 30, headers: dict = None):
+    """GET (or POST when `body` is given) returning JSON, cached and rate-limited."""
+    key = cache_key or (url + ("?" + urlencode(sorted(params.items())) if params else ""))
+    hit = cache_get(key, ttl)
+    if hit is not None:
+        return hit
+
+    host = urlparse(url).netloc
+    delay = 1.0
+    last_err = None
+    for attempt in range(retries + 1):
+        _throttle(host)
+        try:
+            if body is not None:
+                r = requests.post(url, json=body, timeout=timeout, headers=headers)
+            else:
+                r = requests.get(url, params=params, timeout=timeout, headers=headers)
+        except requests.RequestException as e:
+            last_err = e
+            if attempt < retries:
+                time.sleep(delay)
+                delay *= 2
+                continue
+            raise
+
+        if r.status_code == 429:
+            if attempt < retries:
+                # honour Retry-After when the server sends it
+                try:
+                    delay = max(delay, float(r.headers.get("Retry-After", 0)))
+                except ValueError:
+                    pass
+                time.sleep(delay)
+                delay *= 2
+                continue
+            raise RateLimited(
+                f"{host} rate limit reached. Wait a few seconds and retry, lower --depth/--branching, "
+                "or set an API key for a higher quota.")
+
+        if r.status_code in (400, 404):
+            return {"__status__": r.status_code}
+
+        r.raise_for_status()
+        try:
+            data = r.json()
+        except ValueError as e:
+            last_err = e
+            raise
+        cache_put(key, data)
+        return data
+
+    if last_err:
+        raise last_err
+    return None

crypttrace/fetchers/solana.py

@@ -0,0 +1,97 @@
+"""Solana fetcher via public JSON-RPC — no API key required.
+
+Solana has no "list transfers for an address" endpoint: you fetch the address's
+recent signatures, then each transaction, and read the parsed instructions. That
+means one RPC call per transaction, so this fetcher is slower and intentionally
+capped. Set CRYPTTRACE_SOLANA_RPC to use your own (faster) endpoint.
+"""
+import os
+from typing import List, Dict
+
+import requests
+
+RPC = os.environ.get("CRYPTTRACE_SOLANA_RPC", "https://api.mainnet-beta.solana.com")
+LAMPORTS = 1_000_000_000
+MAX_TXS = 25  # keep the number of RPC round-trips sane
+
+
+class SolanaError(RuntimeError):
+    pass
+
+
+def _rpc(method: str, params: list, timeout: int = 30):
+    """Cached, throttled JSON-RPC call."""
+    import json as _json
+    from crypttrace.fetchers import http
+    body = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+    key = f"sol:{method}:{_json.dumps(params, sort_keys=True, default=str)}"
+    try:
+        j = http.request_json(RPC, body=body, cache_key=key, timeout=timeout)
+    except http.RateLimited as e:
+        raise SolanaError(str(e) + " (tip: set CRYPTTRACE_SOLANA_RPC to your own endpoint)")
+    except requests.RequestException as e:
+        raise SolanaError(f"Solana RPC request failed: {e}")
+    except ValueError as e:
+        raise SolanaError(f"bad response from Solana RPC: {e}")
+    if not isinstance(j, dict):
+        return None
+    if "error" in j:
+        raise SolanaError(f"Solana RPC error: {j['error'].get('message')}")
+    return j.get("result")
+
+
+def balance(address: str) -> float:
+    res = _rpc("getBalance", [address])
+    if isinstance(res, dict):
+        return (res.get("value") or 0) / LAMPORTS
+    return 0.0
+
+
+def _signatures(address: str, limit: int) -> List[str]:
+    res = _rpc("getSignaturesForAddress", [address, {"limit": min(limit, MAX_TXS)}]) or []
+    return [s.get("signature") for s in res if s.get("signature")]
+
+
+def _parse_tx(sig: str) -> List[Dict]:
+    tx = _rpc("getTransaction", [sig, {"encoding": "jsonParsed",
+                                       "maxSupportedTransactionVersion": 0}])
+    if not tx:
+        return []
+    ts = int(tx.get("blockTime") or 0)
+    rows = []
+    msg = (tx.get("transaction") or {}).get("message") or {}
+    instrs = list(msg.get("instructions") or [])
+    for inner in (tx.get("meta") or {}).get("innerInstructions") or []:
+        instrs.extend(inner.get("instructions") or [])
+    for ins in instrs:
+        parsed = ins.get("parsed")
+        if not isinstance(parsed, dict):
+            continue
+        info = parsed.get("info") or {}
+        ptype = parsed.get("type")
+        prog = ins.get("program")
+        if prog == "system" and ptype in ("transfer", "transferWithSeed"):
+            rows.append({"from": info.get("source", ""), "to": info.get("destination", ""),
+                         "value": (info.get("lamports") or 0) / LAMPORTS,
+                         "timestamp": ts, "hash": sig, "symbol": "SOL"})
+        elif prog == "spl-token" and ptype in ("transfer", "transferChecked"):
+            amt = info.get("tokenAmount") or {}
+            try:
+                val = float(amt.get("uiAmountString") or amt.get("uiAmount") or info.get("amount") or 0)
+            except (TypeError, ValueError):
+                val = 0.0
+            rows.append({"from": info.get("source", "") or info.get("authority", ""),
+                         "to": info.get("destination", ""), "value": val,
+                         "timestamp": ts, "hash": sig, "symbol": "SPL"})
+    return rows
+
+
+def transfers(address: str, limit: int = MAX_TXS) -> List[Dict]:
+    """Normalized transfer rows. Note: capped at MAX_TXS transactions."""
+    rows: List[Dict] = []
+    for sig in _signatures(address, limit):
+        try:
+            rows.extend(_parse_tx(sig))
+        except SolanaError:
+            continue
+    return rows

crypttrace/fetchers/tron.py

@@ -0,0 +1,128 @@
+"""Tron fetcher via TronGrid — no API key required for basic use.
+
+Tron matters for victim cases: a very large share of everyday scams (romance
+scams, fake investment platforms, "pig butchering") move USDT-TRC20 on Tron
+because fees are near zero.
+
+Tron uses an account model like EVM, but the API returns addresses in hex
+(41-prefixed) for native transfers, so they're converted to the familiar base58
+"T..." form here.
+"""
+import hashlib
+from typing import List, Dict
+
+import requests
+
+BASE = "https://api.trongrid.io"
+SUN = 1_000_000  # 1 TRX
+_B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+class TronError(RuntimeError):
+    pass
+
+
+def hex_to_base58(h: str) -> str:
+    """Convert a Tron hex address (41…) to base58check (T…)."""
+    if not h:
+        return ""
+    if h.startswith("T"):  # already base58
+        return h
+    if h.startswith("0x"):
+        h = h[2:]
+    try:
+        b = bytes.fromhex(h)
+    except ValueError:
+        return h
+    if len(b) == 20:
+        b = b"\x41" + b
+    chk = hashlib.sha256(hashlib.sha256(b).digest()).digest()[:4]
+    b = b + chk
+    n = int.from_bytes(b, "big")
+    s = ""
+    while n > 0:
+        n, r = divmod(n, 58)
+        s = _B58[r] + s
+    pad = 0
+    for c in b:
+        if c == 0:
+            pad += 1
+        else:
+            break
+    return "1" * pad + s
+
+
+def _get(path: str, params: dict = None, timeout: int = 30):
+    """Cached, throttled GET. Set TRONGRID_API_KEY for a higher rate limit."""
+    import os
+    from crypttrace.fetchers import http
+    headers = {}
+    key = os.environ.get("TRONGRID_API_KEY")
+    if key:
+        headers["TRON-PRO-API-KEY"] = key
+    try:
+        data = http.request_json(f"{BASE}{path}", params or {},
+                                 timeout=timeout, headers=headers or None)
+    except http.RateLimited as e:
+        raise TronError(str(e))
+    except requests.RequestException as e:
+        raise TronError(f"TronGrid request failed: {e}")
+    except ValueError as e:
+        raise TronError(f"bad response from TronGrid: {e}")
+    if isinstance(data, dict) and "__status__" in data:
+        return {"data": []}
+    return data
+
+
+def balance(address: str) -> float:
+    d = _get(f"/v1/accounts/{address}")
+    data = d.get("data") or []
+    if not data:
+        return 0.0
+    return (data[0].get("balance") or 0) / SUN
+
+
+def _native(address: str, limit: int) -> List[Dict]:
+    d = _get(f"/v1/accounts/{address}/transactions", {"limit": min(limit, 200)})
+    rows = []
+    for tx in d.get("data", []) or []:
+        try:
+            c = (tx.get("raw_data", {}).get("contract") or [])[0]
+            if c.get("type") != "TransferContract":
+                continue
+            v = c["parameter"]["value"]
+            frm = hex_to_base58(v.get("owner_address", ""))
+            to = hex_to_base58(v.get("to_address", ""))
+            amt = (v.get("amount") or 0) / SUN
+        except (KeyError, IndexError, TypeError):
+            continue
+        if amt <= 0:
+            continue
+        rows.append({"from": frm, "to": to, "value": amt,
+                     "timestamp": int((tx.get("block_timestamp") or 0) / 1000),
+                     "hash": tx.get("txID", ""), "symbol": "TRX"})
+    return rows
+
+
+def token_transfers(address: str, limit: int = 200) -> List[Dict]:
+    """TRC20 transfers (USDT and friends) — already base58 in the API."""
+    d = _get(f"/v1/accounts/{address}/transactions/trc20", {"limit": min(limit, 200)})
+    rows = []
+    for t in d.get("data", []) or []:
+        info = t.get("token_info") or {}
+        dec = int(info.get("decimals") or 6)
+        try:
+            val = int(t.get("value") or 0) / (10 ** dec)
+        except (ValueError, TypeError):
+            continue
+        rows.append({"from": t.get("from", ""), "to": t.get("to", ""), "value": val,
+                     "timestamp": int((t.get("block_timestamp") or 0) / 1000),
+                     "hash": t.get("transaction_id", ""),
+                     "symbol": info.get("symbol", "TRC20"),
+                     "contract": (info.get("address") or "").lower()})
+    return rows
+
+
+def transfers(address: str, limit: int = 200) -> List[Dict]:
+    """Native TRX transfers (use token_transfers for USDT-TRC20)."""
+    return _native(address, limit)