crypttrace 0.13.0__tar.gz → 0.14.0__tar.gz

{crypttrace-0.13.0/src/crypttrace.egg-info → crypttrace-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.13.0
+Version: 0.14.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -103,6 +103,7 @@ own credentials (all optional):
 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
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -481,6 +482,29 @@ wallets. That is what lets `offramp` flag deposit addresses on those chains. Fun
 list still show as `unknown`. Every label records where it came from — see
 `crypttrace labels audit`.
 
+**TON: names from tonapi.** On TON, addresses the curated set does not know are
+looked up on tonapi, which names exchange hot wallets ("Bybit 7", "Kucoin 1"),
+DEX contracts (STON.fi, DeDust) and services (Fragment), and flags scam
+accounts. These become labels of kind `explorer-tag`, cached for a week. A
+`.ton` name an owner chose for himself — "crypto-exch-io.ton", or an impostor's
+"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.
+
+**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
+customer's KYC. `trace`, `profile`, the web UI and the HTML report show every
+deposit an address made to an exchange with its memo:
+
+```
+├── ──1280.0000 TON (1 tx)──▶ 🟢 UQCA1BI4QR…la6Yug  [KuCoin hot wallet (memo required)]
+│   └── ↳ deposit memo 2093842166 — names one account at KuCoin, which holds its KYC
+```
+
+In the fragment-api case this found the attacker's KuCoin account directly, and
+the account of the exchange service he cashed out through (its relay deposits
+under one memo every time).
+
 **Deposit addresses, labelled outright.** OKX signs every address that holds
 customer funds — over 300,000, nearly all of them per-customer deposit addresses
 — and publishes the list with its proof of reserves. `crypttrace update-labels

{crypttrace-0.13.0 → crypttrace-0.14.0}/README.md

@@ -69,6 +69,7 @@ own credentials (all optional):
 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
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -447,6 +448,29 @@ wallets. That is what lets `offramp` flag deposit addresses on those chains. Fun
 list still show as `unknown`. Every label records where it came from — see
 `crypttrace labels audit`.
 
+**TON: names from tonapi.** On TON, addresses the curated set does not know are
+looked up on tonapi, which names exchange hot wallets ("Bybit 7", "Kucoin 1"),
+DEX contracts (STON.fi, DeDust) and services (Fragment), and flags scam
+accounts. These become labels of kind `explorer-tag`, cached for a week. A
+`.ton` name an owner chose for himself — "crypto-exch-io.ton", or an impostor's
+"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.
+
+**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
+customer's KYC. `trace`, `profile`, the web UI and the HTML report show every
+deposit an address made to an exchange with its memo:
+
+```
+├── ──1280.0000 TON (1 tx)──▶ 🟢 UQCA1BI4QR…la6Yug  [KuCoin hot wallet (memo required)]
+│   └── ↳ deposit memo 2093842166 — names one account at KuCoin, which holds its KYC
+```
+
+In the fragment-api case this found the attacker's KuCoin account directly, and
+the account of the exchange service he cashed out through (its relay deposits
+under one memo every time).
+
 **Deposit addresses, labelled outright.** OKX signs every address that holds
 customer funds — over 300,000, nearly all of them per-customer deposit addresses
 — and publishes the list with its proof of reserves. `crypttrace update-labels

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/__init__.py

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

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/chains.py

@@ -15,6 +15,7 @@ from typing import List, Dict, Optional
 from crypttrace import config
 from crypttrace import addresses as _addresses
 from crypttrace import spam as _spam
+from crypttrace.labels import labels as _labels
 from crypttrace.fetchers import etherscan, bitcoin, http as _http, tron, solana, ton
 
 EVM_CHAINS = set(config.CHAINS)
@@ -250,6 +251,35 @@ def flows(address: str, chain: str, top: int, direction: str = "out",
     return [(a, v, c) for a, (v, c) in ranked][:top]
 
 
+def exchange_deposits(address: str, chain: str, limit: int = 1000,
+                      asset: Optional[dict] = None, only_to: Optional[str] = None) -> List[Dict]:
+    """Deposits this address made to exchanges with a memo, per (exchange wallet, memo).
+
+    On TON an exchange's hot wallet takes every customer's deposits and tells
+    them apart by the memo (the transfer comment). The memo is therefore the
+    lead: it names one account at the exchange, which holds that customer's KYC.
+    Returns [{exchange_address, exchange, memo, value, txs, symbol, last_ts, hash}].
+    """
+    me = norm_addr(address, chain)
+    rows = [r for r in transfers(address, chain, limit, asset=asset)
+            if r.get("from") == me and (r.get("memo") or "").strip()
+            and (not only_to or r.get("to") == only_to)]
+    _labels.enrich({r.get("to") for r in rows}, chain)
+    agg: Dict[tuple, dict] = {}
+    for r in rows:
+        to, memo = r.get("to") or "", r["memo"].strip()
+        if _labels.type_of(to) != "exchange":
+            continue
+        rec = agg.setdefault((to, memo), {"exchange_address": to, "exchange": _labels.label_of(to),
+                                          "memo": memo, "value": 0.0, "txs": 0,
+                                          "symbol": r.get("symbol", ""), "last_ts": 0, "hash": ""})
+        rec["value"] += r.get("value", 0) or 0
+        rec["txs"] += 1
+        if (r.get("timestamp") or 0) >= rec["last_ts"]:
+            rec["last_ts"], rec["hash"] = r.get("timestamp") or 0, r.get("hash", "")
+    return sorted(agg.values(), key=lambda d: -d["value"])
+
+
 def outflows(address: str, chain: str, top: int, limit: int = 1000, asset=None):
     return flows(address, chain, top, "out", limit, asset)
 

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/cli.py

@@ -159,6 +159,9 @@ def profile(
                                             chains_mod.symbol(chain)))
     if rows:
         console.print(render.counterparties_rows_table(address, chain, rows))
+        deposits = chains_mod.exchange_deposits(address, chain)
+        if deposits:
+            console.print(render.deposits_table(deposits))
     else:
         console.print("[dim]No transactions found for this address on this chain.[/dim]")
 
@@ -191,7 +194,7 @@ def trace(
     console.print(tree)
     console.print(
         "\n[dim]Legend: \U0001F7E2 exchange  \U0001F7E3 mixer  \U0001F534 sanctioned/scam"
-        "  \U0001F309 bridge  ⚪ unknown[/dim]"
+        "  \U0001F309 bridge  \U0001F504 DEX  \U0001F537 service  ⚪ unknown[/dim]"
     )
 
 

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/fetchers/ton.py

@@ -70,6 +70,11 @@ def _addr(raw: Optional[str]) -> str:
     return addresses.ton_friendly(raw or "") or (raw or "")
 
 
+def _memo(text) -> str:
+    """A transfer comment, cleaned — exchanges read deposit memos from it."""
+    return str(text or "").replace("\x00", "").strip()
+
+
 def _hex(tx_hash: str) -> str:
     """toncenter gives base64 hashes; explorers link by hex."""
     try:
@@ -100,8 +105,12 @@ def transfers(address: str, limit: int = 1000) -> List[Dict]:
                 continue
             # the sender's and the receiver's transactions have different hashes;
             # the message hash is the same on both sides (the store keys on it)
-            rows.append({"from": src, "to": dst, "value": value, "timestamp": ts,
-                         "hash": h, "symbol": "TON", "msg_hash": _hex(m.get("hash") or "")})
+            row = {"from": src, "to": dst, "value": value, "timestamp": ts,
+                   "hash": h, "symbol": "TON", "msg_hash": _hex(m.get("hash") or "")}
+            memo = _memo(((m.get("message_content") or {}).get("decoded") or {}).get("comment"))
+            if memo:
+                row["memo"] = memo
+            rows.append(row)
     return rows
 
 
@@ -140,9 +149,11 @@ def jetton_transfers(address: str, limit: int = 1000) -> List[Dict]:
             value = int(t.get("amount") or 0) / (10 ** meta["decimals"])
         except (ValueError, TypeError):
             continue
+        payload = t.get("decoded_forward_payload") or {}
+        memo = _memo(payload.get("comment")) if isinstance(payload, dict) else ""
         rows.append({"from": _addr(t.get("source")), "to": _addr(t.get("destination")),
                      "value": value, "timestamp": int(t.get("transaction_now") or 0),
                      "hash": _hex(t.get("transaction_hash", "")),
                      "symbol": meta["symbol"], "name": meta["name"], "contract": master,
-                     "flagged": meta["scam"]})
+                     "flagged": meta["scam"], **({"memo": memo} if memo else {})})
     return rows

{crypttrace-0.13.0 → crypttrace-0.14.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
+from crypttrace.labels import bulk, tonapi
 
 _HERE = Path(__file__).parent
 _IMPORTED = config.DATA_DIR / "imported_labels.json"
@@ -162,6 +162,8 @@ RISK = {
     "scam": 85,
     "bridge": 40,
     "exchange": 20,
+    "dex": 0,
+    "service": 0,
     "unknown": 0,
 }
 
@@ -171,6 +173,8 @@ TYPE_ICON = {
     "scam": "\U0001F534",
     "bridge": "\U0001F309",      # bridge
     "exchange": "\U0001F7E2",    # green
+    "dex": "\U0001F504",         # swap arrows
+    "service": "\U0001F537",     # blue diamond
     "unknown": "⚪",         # white
 }
 
@@ -182,7 +186,18 @@ def lookup(address: str) -> Optional[dict]:
     hit = _KNOWN.get(address.lower())
     if hit:
         return hit
-    return _match_partial(address) or bulk.lookup(address)
+    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
+    return found
+
+
+def enrich(addrs, chain: str) -> None:
+    """Fetch explorer tags the curated set lacks (TON: tonapi names). Network, cached."""
+    if chain == "ton":
+        _load()
+        tonapi.enrich(a for a in addrs
+                      if a and not _KNOWN.get((addresses.ton_friendly(a) or a).lower()))
 
 
 def is_deposit(address: str) -> bool:

crypttrace-0.14.0/src/crypttrace/labels/tonapi.py

@@ -0,0 +1,109 @@
+"""TON account names from tonapi — exchanges, DEXes and known services.
+
+tonapi names the hot wallets of exchanges ("Bybit 7", "Kucoin 1"), DEX routers
+("STON.fi DEX") and services ("Fragment"), and flags scam accounts. That is
+the TON equivalent of an explorer's address tags, so it is used the same way:
+a label with its source, of kind "explorer-tag".
+
+Two things are deliberately *not* trusted:
+- names ending in .ton / .t.me — those are DNS names the owner gave himself
+  ("crypto-exch-io.ton", or an impostor's "kucoin-1.ton");
+- anything unknown to tonapi stays unknown — no guessing from interfaces alone,
+  except that STON.fi / DeDust contracts are DEXes whatever they are called.
+
+Lookups are cached on disk for a week (positive and negative), so a trace pays
+for each address once. Only `enrich()` touches the network; `lookup()` reads
+the cache, which keeps label lookups cheap everywhere else.
+"""
+import datetime as dt
+import json
+import os
+import re
+import time
+from typing import Dict, Iterable, Optional
+
+import requests
+
+from crypttrace import addresses, config
+from crypttrace.fetchers import http
+
+API = "https://tonapi.io/v2/accounts/{}"
+CACHE = config.DATA_DIR / "tonapi_names.json"
+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
+
+
+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 tonapi account record, or None if it names nothing we trust."""
+    name = (account.get("name") or "").strip()
+    ifaces = " ".join(account.get("interfaces") or [])
+    self_named = bool(re.search(r"\.(ton|t\.me)$", name, re.I))
+    if account.get("is_scam"):
+        return {"name": f"{name or 'account'} (flagged as scam by tonapi)", "type": "scam"}
+    if "stonfi" in ifaces or "dedust" in ifaces:
+        return {"name": name or "DEX contract", "type": "dex"}
+    if not name or self_named:
+        return None
+    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"}
+
+
+def lookup(address: str) -> Optional[dict]:
+    """Cached tonapi label for a TON address, without touching the network."""
+    key = addresses.ton_friendly(address) or address
+    entry = _load().get(key)
+    if not entry or not entry.get("label"):
+        return None
+    return {**entry["label"], "chain": "ton", "source_kind": "explorer-tag",
+            "source": f"tonapi account name, fetched {entry.get('day', '')}"}
+
+
+def enrich(addrs: Iterable[str]) -> None:
+    """Fetch tonapi names for addresses not in the cache (or stale)."""
+    cache, now, changed = _load(), time.time(), False
+    for a in dict.fromkeys(addrs):
+        key = addresses.ton_friendly(a or "")
+        if not key or now - cache.get(key, {}).get("at", 0) < MAX_AGE:
+            continue
+        try:
+            rec = http.request_json(API.format(key), {}, timeout=20,
+                                    headers={"Authorization": f"Bearer {_KEY}"} if _KEY else None)
+        except (http.RateLimited, requests.RequestException, ValueError):
+            continue
+        if not isinstance(rec, dict) or "__status__" in rec:
+            continue
+        cache[key] = {"at": now, "day": dt.date.today().isoformat(), "label": classify(rec)}
+        changed = True
+    if changed:
+        _save()

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/offramp.py

@@ -30,6 +30,10 @@ def _one(address: str, chain: str, threshold: float, asset: Optional[dict]) -> O
         to = r.get("to") or ""
         if r.get("from") != me or not to:
             continue
+        # a deposit with a memo (TON) is a customer paying into their own exchange
+        # account — the memo is the lead (chains.exchange_deposits), not this address
+        if r.get("memo") and labels.type_of(to) == "exchange":
+            continue
         val = r.get("value", 0) or 0
         out_total += val
         # sending *into* another customer's deposit address is a cash-out by

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/render.py

@@ -224,6 +224,20 @@ def funding_tree(address: str, hops: list, symbol: str = "ETH") -> Tree:
     return root
 
 
+def deposits_table(deposits: list) -> Table:
+    """Exchange deposits made with a memo — each memo names one account at the exchange."""
+    t = Table(title="Exchange deposits — the memo names one account at the exchange (KYC)",
+              header_style="bold")
+    t.add_column("Exchange wallet")
+    t.add_column("Memo", style="bold green")
+    t.add_column("Amount", justify="right")
+    t.add_column("Txs", justify="right")
+    for d in deposits:
+        t.add_row(escape(d["exchange"]), escape(d["memo"]), f"{d['value']:,.4f} {escape(d['symbol'])}",
+                  str(d["txs"]))
+    return t
+
+
 def holdings_table(address: str, chain: str, holdings: list, show_all: bool = False) -> Table:
     """Token holdings with per-token and total USD value.
 

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/report.py

@@ -228,7 +228,8 @@ def _render_md(d: dict, json_name: str) -> str:
     if d["key_findings"]:
         L.append("| Entity | Type | Risk | Value reached | ≈ USD |\n|---|---|---|---|---|\n")
         for f in d["key_findings"]:
-            L.append(f"| {f['label']} | {f['type']} | {f['risk']}/100 | {f['value_reached']} "
+            memo = f" (deposit memo {f['memo']})" if f.get("memo") else ""
+            L.append(f"| {f['label']}{memo} | {f['type']} | {f['risk']}/100 | {f['value_reached']} "
                      f"{f.get('symbol', '')} | {prices.fmt_usd(f.get('usd_reached'))} |\n")
     else:
         L.append("_None within the traced depth._\n")
@@ -390,6 +391,12 @@ def render_html(d: dict, raw_json: str, digest: str, json_name: str) -> str:
         if sig["name"] in ("address poisoning", "paid a look-alike"):
             acts.append(f"<div class='box alert'><b>Address poisoning.</b> {_e(sig['observed'])} — "
                         f"{_e(sig['implication'])}.</div>")
+    for f in d["key_findings"]:
+        if f.get("memo"):
+            acts.append(f"<div class='box alert'><b>Deposit to {_e(labels.company(f['label']))} with memo "
+                        f"{_e(f['memo'])}.</b> The memo names one account at the exchange, which holds "
+                        "its owner's KYC and can freeze it. Quote the memo and the transaction hashes "
+                        "below in the report to the exchange and the police.</div>")
     exch = sorted({labels.company(f["label"]) for f in d["key_findings"]
                    if f["type"] in ("exchange", "offramp")})
     if exch:

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/store.py

@@ -67,6 +67,16 @@ def _conn() -> sqlite3.Connection:
         c.execute("DELETE FROM fetched WHERE chain='ton'")
         c.execute("PRAGMA user_version=1")
         c.commit()
+    if c.execute("PRAGMA user_version").fetchone()[0] < 2:
+        # 0.14: transfer comments — on TON an exchange deposit's memo names the account
+        cols = [r[1] for r in c.execute("PRAGMA table_info(transfers)")]
+        if "memo" not in cols:
+            c.execute("ALTER TABLE transfers ADD COLUMN memo TEXT")
+        # TON rows stored before had their memos dropped: read them again
+        c.execute("DELETE FROM transfers WHERE chain='ton'")
+        c.execute("DELETE FROM fetched WHERE chain='ton'")
+        c.execute("PRAGMA user_version=2")
+        c.commit()
     return c
 
 
@@ -90,12 +100,12 @@ def save(chain: str, address: str, rows: List[dict], asset_key: str = "",
     try:
         c.executemany(
             "INSERT OR REPLACE INTO transfers"
-            "(id,chain,tx_hash,from_addr,to_addr,value,symbol,contract,ts,fee_share)"
-            " VALUES (?,?,?,?,?,?,?,?,?,?)",
+            "(id,chain,tx_hash,from_addr,to_addr,value,symbol,contract,ts,fee_share,memo)"
+            " VALUES (?,?,?,?,?,?,?,?,?,?,?)",
             [(_row_id(chain, r), chain, r.get("hash", ""), r.get("from", ""),
               r.get("to", ""), float(r.get("value", 0) or 0), r.get("symbol", ""),
               r.get("contract", ""), int(r.get("timestamp", 0) or 0),
-              float(r.get("fee_share", 0) or 0)) for r in rows])
+              float(r.get("fee_share", 0) or 0), r.get("memo") or None) for r in rows])
         c.execute("INSERT OR REPLACE INTO fetched(chain,address,asset,fetched_at,rows,complete)"
                   " VALUES (?,?,?,?,?,?)",
                   (chain, address, asset_key, int(time.time()), len(rows), int(complete)))
@@ -125,7 +135,7 @@ def is_fresh(chain: str, address: str, asset_key: str = "",
 def load(chain: str, address: str, contract: str = "", native_symbol: str = "") -> List[dict]:
     """Every stored transfer touching this address, newest first."""
     c = _conn()
-    cols = "SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share FROM transfers"
+    cols = "SELECT from_addr,to_addr,value,symbol,contract,ts,tx_hash,fee_share,memo FROM transfers"
     try:
         if contract == "*":
             # every token, whatever its contract (address-poisoning checks need fakes too)
@@ -151,13 +161,15 @@ def load(chain: str, address: str, contract: str = "", native_symbol: str = "")
     finally:
         c.close()
     out = []
-    for f, t, v, sym, con, ts, h, fee in rows:
+    for f, t, v, sym, con, ts, h, fee, memo in rows:
         r = {"from": f, "to": t, "value": v, "symbol": sym,
              "timestamp": ts, "hash": h}
         if con:
             r["contract"] = con
         if fee:
             r["fee_share"] = fee
+        if memo:
+            r["memo"] = memo
         out.append(r)
     return out
 

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/trace.py

@@ -33,16 +33,27 @@ def _edge_text(ctx, to, val, cnt):
     return Text.assemble(Text(f"──{money} ({cnt} tx){tail}{arrow}"), render.addr_label(to))
 
 
-def _record_finding(findings, ctx, to, val, cnt):
+def _record_finding(findings, ctx, to, val, cnt, memos=()):
     if findings is None:
         return
     hit = labels.lookup(to)
-    if not hit:
+    if not hit or hit["type"] in ("dex", "service"):
         return
-    findings.append({"address": to, "type": hit["type"], "label": hit["name"],
-                     "risk": labels.risk_score(to), "value_reached": round(val, 6),
-                     "symbol": ctx.symbol, "usd_reached": prices.usd(val, ctx.price),
-                     "tx_count": cnt})
+    f = {"address": to, "type": hit["type"], "label": hit["name"],
+         "risk": labels.risk_score(to), "value_reached": round(val, 6),
+         "symbol": ctx.symbol, "usd_reached": prices.usd(val, ctx.price),
+         "tx_count": cnt}
+    if memos:
+        f["memo"] = ", ".join(memos)
+    findings.append(f)
+
+
+def _deposit_memos(sender, to, ctx):
+    """Memos of `sender`'s deposits into exchange wallet `to` (TON) — each names an account."""
+    if ctx.direction != "out" or labels.type_of(to) != "exchange":
+        return []
+    from crypttrace import chains
+    return [d["memo"] for d in chains.exchange_deposits(sender, ctx.chain, asset=ctx.asset, only_to=to)]
 
 
 def _expand(node, address, ctx, depth, seen, findings=None, is_root=False):
@@ -54,6 +65,10 @@ def _expand(node, address, ctx, depth, seen, findings=None, is_root=False):
     if not is_root and labels.type_of(address) in ("exchange", "mixer", "sanctioned"):
         node.add(Text("↳ trail ends here (identifiable entity — subpoena / off-chain)", style="dim"))
         return
+    if not is_root and labels.type_of(address) == "dex":
+        node.add(Text("↳ DEX swap — the funds come back to the sender in another token; "
+                      "trace the sender with --asset to follow them", style="cyan"))
+        return
     if not is_root and labels.type_of(address) == "bridge":
         node.add(Text("↳ bridge — funds leave this chain; run `crypttrace crosschain` "
                       "on the sender to find the destination chain", style="cyan"))
@@ -75,9 +90,15 @@ def _expand(node, address, ctx, depth, seen, findings=None, is_root=False):
                                  "usd_reached": prices.usd(off["forwarded"], ctx.price),
                                  "tx_count": 0})
             return
-    for to, val, cnt in _outflows(address, ctx.chain, ctx.branching, ctx.asset, ctx.direction):
-        _record_finding(findings, ctx, to, val, cnt)
+    outs = _outflows(address, ctx.chain, ctx.branching, ctx.asset, ctx.direction)
+    labels.enrich([to for to, _, _ in outs], ctx.chain)
+    for to, val, cnt in outs:
+        memos = _deposit_memos(address, to, ctx)
+        _record_finding(findings, ctx, to, val, cnt, memos)
         child = node.add(_edge_text(ctx, to, val, cnt))
+        for memo in memos:
+            child.add(Text(f"↳ deposit memo {memo} — names one account at "
+                           f"{labels.company(labels.label_of(to))}, which holds its KYC", style="bold green"))
         _expand(child, to, ctx, depth - 1, seen, findings)
 
 
@@ -149,18 +170,27 @@ def build_graph(address, chain, depth, branching, asset=None, direction="out"):
         if d <= 0 or key in seen:
             return
         seen.add(key)
-        if not is_root and labels.type_of(addr) in ("exchange", "mixer", "sanctioned", "bridge"):
+        if not is_root and labels.type_of(addr) in ("exchange", "mixer", "sanctioned", "bridge", "dex"):
             nodes[key]["terminal"] = True
             return
-        for to, val, cnt in _outflows(addr, chain, branching, asset, direction):
+        outs = _outflows(addr, chain, branching, asset, direction)
+        labels.enrich([to for to, _, _ in outs], chain)
+        for to, val, cnt in outs:
             _node(to, hop + 1)
             # arrows always point the way the money actually travelled
             src, dst = (key, _norm(to)) if direction == "out" else (_norm(to), key)
-            edges.append({"from": src, "to": dst,
-                          "value": round(val, 4), "tx": cnt,
-                          "usd": prices.usd(val, price)})
+            edge = {"from": src, "to": dst, "value": round(val, 4), "tx": cnt,
+                    "usd": prices.usd(val, price)}
+            if direction == "out" and labels.type_of(to) == "exchange":
+                from crypttrace import chains as _ch
+                memos = [m["memo"] for m in _ch.exchange_deposits(addr, chain, asset=asset, only_to=to)]
+                if memos:
+                    edge["memo"] = ", ".join(memos)
+            edges.append(edge)
             _walk(to, d - 1, seen, False, hop + 1)
 
     _walk(address, depth, set(), True, 0)
+    for n in nodes.values():                 # labels found by enrichment after the node was made
+        n["type"], n["label"] = labels.type_of(n["id"]), labels.label_of(n["id"])
     return {"nodes": list(nodes.values()), "edges": edges,
             "symbol": symbol, "direction": direction}

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/web/index.html

@@ -368,7 +368,7 @@ function renderGraph(g){
   const edges=g.edges.map(e=>({
     from:e.from,to:e.to,arrows:{to:{enabled:true,scaleFactor:.7}},
     label:`${e.value} ${g.symbol}${e.usd!=null?'  ≈'+fmtUsd(e.usd):''}`,
-    title:`${e.value} ${g.symbol} in ${e.tx} tx — click to open on explorer`,
+    title:`${e.value} ${g.symbol} in ${e.tx} tx${e.memo?' · deposit memo '+e.memo:''} — click to open on explorer`,
     font:{color:'#93a1b5',size:10.5,strokeWidth:4,strokeColor:'rgba(8,11,18,.85)',align:'horizontal'},
     color:{color:'rgba(255,255,255,.18)',highlight:'#4d9dff',hover:'#4d9dff'},
     width:1.2, hoverWidth:2.4, selectionWidth:2.4,
@@ -444,6 +444,12 @@ async function inspect(addr){
       kv('transfers',p.txs)+
       kv('first seen',fmtTs(p.first_seen))+
       kv('last seen',fmtTs(p.last_seen)));
+    if(p.deposits && p.deposits.length){
+      h+=card('🏦 Exchange deposits with a memo',
+        `<div class="muted">The memo names one account at the exchange, which holds its KYC — quote it
+        with the transaction in a report or freeze request.</div>`+
+        p.deposits.map(d=>kv(esc(d.exchange),`memo <b class="mono">${esc(d.memo)}</b> · ${esc(d.value.toLocaleString())} ${esc(d.symbol)} · ${d.txs} tx`)).join(''),'alert');
+    }
     if(o.offramp){
       h+=card('⚠ Off-ramp detected',
         `<div class="muted">~${Math.round(o.offramp.fraction*100)}% of outgoing funds forwarded to

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace/webapp.py

@@ -119,6 +119,7 @@ def create_app() -> Flask:
             "type": labels.type_of(addr),
             "risk": labels.risk_score(addr),
             "explorer": chains.explorer_url(addr, chain),
+            "deposits": chains.exchange_deposits(addr, chain)[:5],
         })
 
     @app.route("/api/trace")

{crypttrace-0.13.0 → crypttrace-0.14.0/src/crypttrace.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.13.0
+Version: 0.14.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron, Solana and TON
 Author: bobslayerX
 License-Expression: MIT
@@ -103,6 +103,7 @@ own credentials (all optional):
 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
 ```
 
 (In PowerShell: `$env:TRONGRID_API_KEY = "xxxx"` and so on.)
@@ -481,6 +482,29 @@ wallets. That is what lets `offramp` flag deposit addresses on those chains. Fun
 list still show as `unknown`. Every label records where it came from — see
 `crypttrace labels audit`.
 
+**TON: names from tonapi.** On TON, addresses the curated set does not know are
+looked up on tonapi, which names exchange hot wallets ("Bybit 7", "Kucoin 1"),
+DEX contracts (STON.fi, DeDust) and services (Fragment), and flags scam
+accounts. These become labels of kind `explorer-tag`, cached for a week. A
+`.ton` name an owner chose for himself — "crypto-exch-io.ton", or an impostor's
+"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.
+
+**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
+customer's KYC. `trace`, `profile`, the web UI and the HTML report show every
+deposit an address made to an exchange with its memo:
+
+```
+├── ──1280.0000 TON (1 tx)──▶ 🟢 UQCA1BI4QR…la6Yug  [KuCoin hot wallet (memo required)]
+│   └── ↳ deposit memo 2093842166 — names one account at KuCoin, which holds its KYC
+```
+
+In the fragment-api case this found the attacker's KuCoin account directly, and
+the account of the exchange service he cashed out through (its relay deposits
+under one memo every time).
+
 **Deposit addresses, labelled outright.** OKX signs every address that holds
 customer funds — over 300,000, nearly all of them per-customer deposit addresses
 — and publishes the list with its proof of reserves. `crypttrace update-labels

{crypttrace-0.13.0 → crypttrace-0.14.0}/src/crypttrace.egg-info/SOURCES.txt

@@ -43,4 +43,5 @@ src/crypttrace/labels/bulk.py
 src/crypttrace/labels/known.json
 src/crypttrace/labels/labels.py
 src/crypttrace/labels/partial.json
+src/crypttrace/labels/tonapi.py
 src/crypttrace/web/index.html