crypttrace 0.5.0__tar.gz → 0.7.0__tar.gz

{crypttrace-0.5.0/src/crypttrace.egg-info → crypttrace-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crypttrace
-Version: 0.5.0
+Version: 0.7.0
 Summary: OSINT toolkit for crypto investigations: trace stolen funds across Ethereum, Bitcoin, Tron and Solana
 Author: bobslayerX
 License-Expression: MIT
@@ -163,6 +163,11 @@ It is also honest with you: most stolen crypto is not recovered, and what
 matters is speed and whether the funds touch a regulated exchange. The tool
 gives you evidence and timing — it cannot move funds or name a person by itself.
 
+**Stolen USDT or USDC?** Check at once whether it is still sitting at the
+thief's address — Tether and Circle can freeze it there, and only there:
+`crypttrace freeze THEIR_ADDRESS --chain tron`. `investigate` does this too
+and puts it first.
+
 **Sent money to an address that looked right?** That is usually address
 poisoning — see below. Check your own wallet with
 `crypttrace poisoning YOUR_ADDRESS`.
@@ -195,6 +200,9 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Is the USDT/USDC at this address frozen by Tether/Circle — and who can freeze it?
+crypttrace freeze TADDRESS --chain tron
+
 # Address poisoning: look-alike addresses planted in a wallet's history
 crypttrace poisoning TADDRESS --chain tron
 
@@ -217,7 +225,7 @@ crypttrace crosschain 0xADDRESS --window 48
 crypttrace watch add 0xADDRESS --note "my stolen ETH"
 crypttrace watch run --interval 300     # or --once for cron / Task Scheduler
 
-# Full investigation report to disk (Markdown + JSON)
+# Full investigation as a case file to send: one HTML page (plus Markdown + JSON)
 crypttrace report 0xADDRESS --depth 3
 
 # Refresh label lists (OFAC sanctions, …)
@@ -275,6 +283,29 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Stablecoin freezes
+
+Tether and Circle can freeze USDT and USDC at any address. For a victim of a
+stablecoin theft that is the one lever that actually stops the money — while it
+is still there. `crypttrace freeze` reads the issuers' own contracts (USDT's
+`isBlackListed`, USDC's `isBlacklisted`, balances; token-account state on
+Solana) on Ethereum, Tron and Solana, and answers three things: how much is
+there, whether it is already frozen, and if not, who can freeze it:
+
+- **Tether** freezes USDT at the request of law enforcement, often before a
+  court case — so the route is the police, quickly
+  ([policy](https://tether.to/en/legal/?tab=law-enforcement-requests)).
+- **Circle** freezes USDC only on a legal order such as a court order
+  ([terms](https://www.circle.com/legal/usdc-terms)), which takes longer.
+
+No API key is needed: Ethereum is read through a public node (set
+`CRYPTTRACE_ETH_RPC` to use your own). `investigate` runs the check on the
+address the money went to and makes it the first step; the web UI shows it in
+the side panel; a freeze also counts in the assessment. A check that fails is
+reported as unknown, never as "not frozen". Other chains carry bridged or
+third-party versions of these tokens that the issuers cannot freeze in the same
+way, so they are not checked.
+
 ### Address poisoning
 
 Wallets show addresses shortened — `TDDD34…rCr9Ps`. A poisoner generates an
@@ -429,10 +460,24 @@ are ignored, and every address is checked before it is stored.
 
 ### Reports
 
-`report` runs the full analysis and writes to `~/crypttrace-reports/` (override
-with `--out`): a readable Markdown report (assessment, summary, key findings,
-counterparties, the full fund-flow trace, methodology note) plus a `.json` with
-the raw structured data.
+`report` runs the full analysis and writes a **case file** to
+`~/crypttrace-reports/` (override with `--out`); `investigate` saves the same
+file with the victim's next steps in it. The case file is one HTML page, made
+for whoever receives it — an exchange's compliance team, the police, a lawyer:
+
+- the conclusion in plain words, and what to do now: stablecoins still at the
+  address and who can freeze them, the exchanges the money reached, address
+  poisoning;
+- the fund-flow graph, each address linking to a block explorer;
+- every transfer along the trace with its transaction hashes — the first thing
+  an exchange asks for;
+- where each label comes from, how the tool checked its own arithmetic, and
+  what the method cannot tell you.
+
+It has no scripts and loads nothing from the internet, so it opens in any
+browser or mail client, prints (or saves as PDF) cleanly, and opening it tells
+no one. The raw data is embedded for analysts and written next to it as JSON,
+with its SHA-256 printed on the page; a Markdown version is written too.
 
 ### Self-verification
 
@@ -530,11 +575,6 @@ cases/             # worked investigations with their data
 
 - More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
   and refreshing these lists as the exchanges republish them
-- Stablecoin freeze check: whether USDT/USDC at an address is already frozen
-  by the issuer, and who to ask for a freeze
-- `report --html`: one self-contained file with the interactive graph, to
-  send to an exchange or attach to a police report
-- `report --pdf` for exchange and law-enforcement filings
 - Internal transactions (completes `funder` and contract-mediated transfers)
 - Per-mint filtering for Solana SPL tokens
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets

{crypttrace-0.5.0 → crypttrace-0.7.0}/README.md

@@ -129,6 +129,11 @@ It is also honest with you: most stolen crypto is not recovered, and what
 matters is speed and whether the funds touch a regulated exchange. The tool
 gives you evidence and timing — it cannot move funds or name a person by itself.
 
+**Stolen USDT or USDC?** Check at once whether it is still sitting at the
+thief's address — Tether and Circle can freeze it there, and only there:
+`crypttrace freeze THEIR_ADDRESS --chain tron`. `investigate` does this too
+and puts it first.
+
 **Sent money to an address that looked right?** That is usually address
 poisoning — see below. Check your own wallet with
 `crypttrace poisoning YOUR_ADDRESS`.
@@ -161,6 +166,9 @@ crypttrace tokens 0xADDRESS
 # Who bootstrapped this wallet's first gas? Follow it toward a KYC point
 crypttrace funder 0xADDRESS --hops 6
 
+# Is the USDT/USDC at this address frozen by Tether/Circle — and who can freeze it?
+crypttrace freeze TADDRESS --chain tron
+
 # Address poisoning: look-alike addresses planted in a wallet's history
 crypttrace poisoning TADDRESS --chain tron
 
@@ -183,7 +191,7 @@ crypttrace crosschain 0xADDRESS --window 48
 crypttrace watch add 0xADDRESS --note "my stolen ETH"
 crypttrace watch run --interval 300     # or --once for cron / Task Scheduler
 
-# Full investigation report to disk (Markdown + JSON)
+# Full investigation as a case file to send: one HTML page (plus Markdown + JSON)
 crypttrace report 0xADDRESS --depth 3
 
 # Refresh label lists (OFAC sanctions, …)
@@ -241,6 +249,29 @@ crypttrace watch run --once             # single check, for scheduled tasks
 Optional Telegram alerts: set `CRYPTTRACE_TG_TOKEN` and `CRYPTTRACE_TG_CHAT`,
 then pass `--telegram`.
 
+### Stablecoin freezes
+
+Tether and Circle can freeze USDT and USDC at any address. For a victim of a
+stablecoin theft that is the one lever that actually stops the money — while it
+is still there. `crypttrace freeze` reads the issuers' own contracts (USDT's
+`isBlackListed`, USDC's `isBlacklisted`, balances; token-account state on
+Solana) on Ethereum, Tron and Solana, and answers three things: how much is
+there, whether it is already frozen, and if not, who can freeze it:
+
+- **Tether** freezes USDT at the request of law enforcement, often before a
+  court case — so the route is the police, quickly
+  ([policy](https://tether.to/en/legal/?tab=law-enforcement-requests)).
+- **Circle** freezes USDC only on a legal order such as a court order
+  ([terms](https://www.circle.com/legal/usdc-terms)), which takes longer.
+
+No API key is needed: Ethereum is read through a public node (set
+`CRYPTTRACE_ETH_RPC` to use your own). `investigate` runs the check on the
+address the money went to and makes it the first step; the web UI shows it in
+the side panel; a freeze also counts in the assessment. A check that fails is
+reported as unknown, never as "not frozen". Other chains carry bridged or
+third-party versions of these tokens that the issuers cannot freeze in the same
+way, so they are not checked.
+
 ### Address poisoning
 
 Wallets show addresses shortened — `TDDD34…rCr9Ps`. A poisoner generates an
@@ -395,10 +426,24 @@ are ignored, and every address is checked before it is stored.
 
 ### Reports
 
-`report` runs the full analysis and writes to `~/crypttrace-reports/` (override
-with `--out`): a readable Markdown report (assessment, summary, key findings,
-counterparties, the full fund-flow trace, methodology note) plus a `.json` with
-the raw structured data.
+`report` runs the full analysis and writes a **case file** to
+`~/crypttrace-reports/` (override with `--out`); `investigate` saves the same
+file with the victim's next steps in it. The case file is one HTML page, made
+for whoever receives it — an exchange's compliance team, the police, a lawyer:
+
+- the conclusion in plain words, and what to do now: stablecoins still at the
+  address and who can freeze them, the exchanges the money reached, address
+  poisoning;
+- the fund-flow graph, each address linking to a block explorer;
+- every transfer along the trace with its transaction hashes — the first thing
+  an exchange asks for;
+- where each label comes from, how the tool checked its own arithmetic, and
+  what the method cannot tell you.
+
+It has no scripts and loads nothing from the internet, so it opens in any
+browser or mail client, prints (or saves as PDF) cleanly, and opening it tells
+no one. The raw data is embedded for analysts and written next to it as JSON,
+with its SHA-256 printed on the page; a Markdown version is written too.
 
 ### Self-verification
 
@@ -496,11 +541,6 @@ cases/             # worked investigations with their data
 
 - More exchanges on Bitcoin, Tron and Solana (now: Binance, OKX, HTX, Bybit),
   and refreshing these lists as the exchanges republish them
-- Stablecoin freeze check: whether USDT/USDC at an address is already frozen
-  by the issuer, and who to ask for a freeze
-- `report --html`: one self-contained file with the interactive graph, to
-  send to an exchange or attach to a police report
-- `report --pdf` for exchange and law-enforcement filings
 - Internal transactions (completes `funder` and contract-mediated transfers)
 - Per-mint filtering for Solana SPL tokens
 - More label sources: Chainabuse, CryptoScamDB, exchange deposit-address sets

{crypttrace-0.5.0 → crypttrace-0.7.0}/src/crypttrace/__init__.py

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

{crypttrace-0.5.0 → crypttrace-0.7.0}/src/crypttrace/assess.py

@@ -14,7 +14,7 @@ from collections import Counter
 from dataclasses import dataclass, field, asdict
 from typing import Dict, List, Optional
 
-from crypttrace import analysis, chains, poisoning
+from crypttrace import analysis, chains, freeze, poisoning
 from crypttrace.labels import labels
 
 
@@ -234,6 +234,17 @@ def assess(address: str, chain: str = "eth", asset: Optional[dict] = None,
             implication="this wallet was likely the victim of address poisoning",
             confidence=p["confidence"], weight=0, evidence={"pairs": sent_to_fake[:5]}))
 
+    # --- stablecoin issuer freeze ---------------------------------------
+    frozen = [e for e in freeze.check(address, chain) if e.get("frozen")]
+    if frozen:
+        e = frozen[0]
+        signals.append(Signal(
+            name="frozen by issuer",
+            observed=freeze.describe_frozen(e),
+            implication="the issuer blocked it — usually at the request of law enforcement "
+                        "or under sanctions",
+            confidence="high", weight=40, evidence={"freezes": frozen}))
+
     # --- holding behaviour ---------------------------------------------
     if received > 0 and sent == 0 and len(inbound) >= 3:
         signals.append(Signal(
@@ -314,6 +325,9 @@ def _statement(signals: List[Signal], risk: int, confidence: str, hit) -> str:
     if "paid a look-alike" in names:
         parts.append("This wallet sent money to a look-alike of an address it had used "
                      "before — the signature of an address-poisoning theft.")
+    if "frozen by issuer" in names:
+        parts.append("Stablecoins here are frozen by their issuer, which usually follows a "
+                     "law-enforcement request or a sanctions listing.")
     if "funds held" in names:
         parts.append("The proceeds have not been spent, so intervention is still possible.")
     parts.append(f"Overall risk {risk}/100, confidence {confidence}.")

{crypttrace-0.5.0 → crypttrace-0.7.0}/src/crypttrace/chains.py

@@ -30,6 +30,14 @@ EXPLORER = {
     "sol": "https://solscan.io/account/{}",
 }
 
+TX_EXPLORER = {
+    "eth": "https://etherscan.io/tx/{}", "bsc": "https://bscscan.com/tx/{}",
+    "polygon": "https://polygonscan.com/tx/{}", "arbitrum": "https://arbiscan.io/tx/{}",
+    "optimism": "https://optimistic.etherscan.io/tx/{}", "base": "https://basescan.org/tx/{}",
+    "btc": "https://mempool.space/tx/{}", "tron": "https://tronscan.org/#/transaction/{}",
+    "sol": "https://solscan.io/tx/{}",
+}
+
 _UPSTREAM_ERRORS = (etherscan.EtherscanError, bitcoin.BitcoinError,
                     tron.TronError, solana.SolanaError)
 
@@ -59,6 +67,10 @@ def explorer_url(address: str, chain: str) -> str:
     return EXPLORER.get(chain, EXPLORER["eth"]).format(address)
 
 
+def tx_url(tx_hash: str, chain: str) -> str:
+    return TX_EXPLORER.get(chain, TX_EXPLORER["eth"]).format(tx_hash)
+
+
 def check(chain: str) -> None:
     if chain not in ALL_CHAINS:
         raise ChainError(f"unsupported chain '{chain}'. Options: {ALL_CHAINS}")

{crypttrace-0.5.0 → crypttrace-0.7.0}/src/crypttrace/cli.py

@@ -224,7 +224,7 @@ def report(
         help="Folder to save the report in",
     ),
 ):
-    """Run a full investigation and save a Markdown + JSON report to disk."""
+    """Run a full investigation and save it as an HTML case file (plus Markdown and JSON)."""
     try:
         asset_desc = assets.resolve_asset(asset, chain)
     except ValueError as e:
@@ -232,12 +232,14 @@ def report(
         raise typer.Exit(1)
     try:
         with console.status("Gathering on-chain data and tracing funds…"):
-            md_path = report_mod.generate(address, chain, depth, branching, out, asset_desc)
-    except etherscan.EtherscanError as e:
+            paths = report_mod.generate(address, chain, depth, branching, out, asset_desc)
+    except (chains_mod.ChainError, etherscan.EtherscanError) as e:
         console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1)
-    console.print(f"[green]✓ Report saved:[/green] {md_path}")
-    console.print(f"[dim]  Raw data (JSON) saved alongside it in the same folder.[/dim]")
+    console.print(f"[green]✓ Case file saved:[/green] {paths['html']}")
+    console.print("[dim]  One self-contained page: open it in a browser, print it to PDF, or "
+                  "send it as it is.[/dim]")
+    console.print("[dim]  Markdown and raw JSON are saved next to it.[/dim]")
 
 
 @app.command()
@@ -262,6 +264,39 @@ def crosschain(
                   "not proof. Verify each candidate before relying on it.[/dim]")
 
 
+@app.command()
+def freeze(
+    address: str = typer.Argument(..., help="Address holding the USDT/USDC"),
+    chain: str = CHAIN_OPT,
+):
+    """Is USDT/USDC at this address frozen by its issuer — and who can freeze it?"""
+    from crypttrace import freeze as freeze_mod
+    entries = freeze_mod.check(address, chain)
+    if not entries:
+        console.print("[dim]USDT/USDC freezes are checked on Ethereum, Tron and Solana, where "
+                      "Tether and Circle issue them directly and can freeze them.[/dim]")
+        return
+    for e in entries:
+        head = f"[bold]{e['token']}[/bold] ({e['issuer']})"
+        if e.get("error"):
+            console.print(f"{head}: [yellow]could not be read[/yellow] — {e['error']}")
+        elif e["frozen"]:
+            console.print(f"{head}: [bold green]FROZEN[/bold green] — {freeze_mod.describe_frozen(e)}"
+                          + (f"; {e['movable']:,.2f} still can move" if e["actionable"] else ""))
+        elif e["actionable"]:
+            console.print(f"{head}: [bold red]{e['balance']:,.2f} {e['token']} NOT frozen[/bold red]"
+                          " — it can still be moved")
+            console.print(f"    {e['how']}")
+            console.print(f"    [dim]{e['url']}[/dim]")
+        elif e["balance"]:
+            console.print(f"{head}: only dust ({e['balance']:.6f}) — nothing to freeze")
+        else:
+            console.print(f"{head}: none at this address")
+    if labels.type_of(address) == "exchange":
+        console.print("\n[dim]This is an exchange's own wallet: ask the exchange, "
+                      "not the issuer.[/dim]")
+
+
 @app.command()
 def poisoning(
     address: str = typer.Argument(..., help="Your wallet, or the address the money went to"),

crypttrace-0.7.0/src/crypttrace/freeze.py

@@ -0,0 +1,161 @@
+"""Stablecoin freezes — has the issuer already frozen the money, and who can?
+
+Tether (USDT) and Circle (USDC) can freeze their tokens at any address. For a
+victim that is the one mechanism that actually stops stolen stablecoins, and it
+works only while the money is still sitting there. So the useful answers are:
+how much USDT/USDC is at this address, is it already frozen, and if not, who
+can freeze it and what they need.
+
+Everything is read from the issuers' own contracts, not from third-party lists:
+
+  * Ethereum — USDT's isBlackListed / USDC's isBlacklisted and balanceOf, via
+    a public JSON-RPC node (no API key; set CRYPTTRACE_ETH_RPC to use your own);
+  * Tron     — the same calls through TronGrid;
+  * Solana   — the state of the owner's token accounts, which the issuer freezes
+    one account at a time ("frozen").
+
+Other chains carry bridged or third-party versions of these tokens that the
+issuers cannot freeze in the same way, so they are not checked.
+"""
+import os
+from typing import Dict, List
+
+import requests
+
+from crypttrace import addresses, assets
+from crypttrace.fetchers import solana
+
+ETH_RPC = os.environ.get("CRYPTTRACE_ETH_RPC", "https://ethereum-rpc.publicnode.com")
+TRON_API = "https://api.trongrid.io"
+
+# selector of the issuer's own "is this address frozen?" function
+_EVM_FROZEN = {"USDT": "0xe47d6060",   # isBlackListed(address)
+               "USDC": "0xfe575a87"}   # isBlacklisted(address)
+_BALANCE_OF = "0x70a08231"             # balanceOf(address)
+_TRON_FROZEN = {"USDT": "isBlackListed(address)", "USDC": "isBlacklisted(address)"}
+
+ISSUERS = {
+    "USDT": {"issuer": "Tether",
+             "how": ("Tether freezes USDT at the request of law enforcement, often before "
+                     "a court case. Give the police this address and ask them to request a "
+                     "freeze from Tether."),
+             "url": "https://tether.to/en/legal/?tab=law-enforcement-requests"},
+    "USDC": {"issuer": "Circle",
+             "how": ("Circle freezes USDC only on a legal order — a court order, a sanctions "
+                     "designation or a request from authorities with jurisdiction over it. "
+                     "Expect to need a court order; ask the police or a lawyer."),
+             "url": "https://www.circle.com/legal/usdc-terms"},
+}
+
+SUPPORTED = ("eth", "tron", "sol")
+MIN_ACTIONABLE = 1.0          # USDT/USDC below this is dust
+
+
+class FreezeError(RuntimeError):
+    pass
+
+
+def _eth_call(contract: str, selector: str, address: str) -> int:
+    data = selector + address.lower().replace("0x", "").rjust(64, "0")
+    try:
+        r = requests.post(ETH_RPC, timeout=30, json={
+            "jsonrpc": "2.0", "id": 1, "method": "eth_call",
+            "params": [{"to": contract, "data": data}, "latest"]}).json()
+    except (requests.RequestException, ValueError) as e:
+        raise FreezeError(f"Ethereum node unreachable: {e}")
+    if "result" not in r:
+        raise FreezeError(f"Ethereum node refused the call: {r.get('error')}")
+    return int(r["result"] or "0x0", 16)
+
+
+def _tron_call(contract: str, signature: str, address: str) -> int:
+    raw = addresses._b58_decode(address)            # 0x41 + 20 bytes + checksum
+    if not raw or len(raw) != 25:
+        raise FreezeError("not a Tron address")
+    headers = {"TRON-PRO-API-KEY": os.environ["TRONGRID_API_KEY"]} \
+        if os.environ.get("TRONGRID_API_KEY") else {}
+    try:
+        r = requests.post(f"{TRON_API}/wallet/triggerconstantcontract", timeout=30,
+                          headers=headers, json={
+                              # a read-only call: the caller does not matter, and
+                              # an unactivated address can be refused as the caller
+                              "owner_address": contract, "contract_address": contract,
+                              "function_selector": signature,
+                              "parameter": raw[1:21].hex().rjust(64, "0"), "visible": True}).json()
+    except (requests.RequestException, ValueError) as e:
+        raise FreezeError(f"TronGrid unreachable: {e}")
+    out = (r.get("constant_result") or [None])[0]
+    if out is None:
+        raise FreezeError(f"TronGrid refused the call: {r.get('result') or r}")
+    return int(out or "0", 16)
+
+
+def _sol_accounts(owner: str, mint: str) -> List[dict]:
+    try:
+        r = solana._rpc("getTokenAccountsByOwner",
+                        [owner, {"mint": mint}, {"encoding": "jsonParsed"}])
+    except solana.SolanaError as e:
+        raise FreezeError(str(e))
+    out = []
+    for v in (r.get("value") if isinstance(r, dict) else r) or []:
+        info = v["account"]["data"]["parsed"]["info"]
+        out.append({"state": info.get("state"),
+                    "amount": float(info["tokenAmount"].get("uiAmountString") or 0)})
+    return out
+
+
+def _one(address: str, chain: str, symbol: str, contract: str) -> Dict:
+    if chain == "eth":
+        frozen = _eth_call(contract, _EVM_FROZEN[symbol], address) == 1
+        balance = _eth_call(contract, _BALANCE_OF, address) / 1e6
+        frozen_amount = balance if frozen else 0.0
+    elif chain == "tron":
+        frozen = _tron_call(contract, _TRON_FROZEN[symbol], address) == 1
+        balance = _tron_call(contract, "balanceOf(address)", address) / 1e6
+        frozen_amount = balance if frozen else 0.0
+    else:                                             # sol: frozen per token account
+        accts = _sol_accounts(address, contract)
+        balance = sum(a["amount"] for a in accts)
+        frozen_amount = sum(a["amount"] for a in accts if a["state"] == "frozen")
+        frozen = any(a["state"] == "frozen" for a in accts)
+    movable = balance - frozen_amount
+    return {"token": symbol, "balance": balance, "frozen": frozen,
+            "frozen_amount": frozen_amount, "movable": movable,
+            # leftover dust is not worth a freeze request, or a victim's panic
+            "actionable": movable >= MIN_ACTIONABLE}
+
+
+def describe_frozen(e: Dict) -> str:
+    """'4,021.97 USDT here is frozen by Tether', or the blacklisting alone when empty."""
+    if (e.get("frozen_amount") or 0) >= MIN_ACTIONABLE:
+        return f"{e['frozen_amount']:,.2f} {e['token']} here is frozen by {e['issuer']}"
+    return f"This address is blacklisted by {e['issuer']} (no {e['token']} left on it)"
+
+
+def check(address: str, chain: str) -> List[Dict]:
+    """One entry per issuer stablecoin on this chain; empty where none applies.
+
+    Each entry: token, issuer, balance, frozen, frozen_amount, movable (what can
+    still leave), how (what the issuer needs), url, and error if it could not be
+    read. A failed read is reported, never guessed.
+    """
+    if chain not in SUPPORTED:
+        return []
+    from crypttrace import chains
+    out = []
+    for sym in ("usdt", "usdc"):
+        tok = assets.tokens_for(chain).get(sym)
+        if not tok:
+            continue
+        symbol = tok["symbol"]
+        entry = {"token": symbol, **ISSUERS[symbol]}
+        try:
+            if chains.OFFLINE:
+                raise FreezeError("not checked: working offline")
+            entry.update(_one(address, chain, symbol, tok["contract"]))
+        except (FreezeError, KeyError, TypeError, ValueError) as e:
+            entry.update({"balance": None, "frozen": None, "frozen_amount": None,
+                          "movable": None, "actionable": None, "error": str(e)})
+        out.append(entry)
+    return out
+

{crypttrace-0.5.0 → crypttrace-0.7.0}/src/crypttrace/investigate.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import Dict, List, Optional
 
 from crypttrace import chains, prices, report as report_mod, trace as trace_mod
-from crypttrace import funder as funder_mod, offramp as offramp_mod, poisoning
+from crypttrace import freeze as freeze_mod, funder as funder_mod, offramp as offramp_mod, poisoning
 from crypttrace.labels import labels
 
 
@@ -32,7 +32,7 @@ def analyse(address: str, chain: str = "eth", asset: Optional[dict] = None,
     """Run every check and return a structured result (no printing)."""
     result = {
         "address": address, "chain": chain,
-        "asset": asset["symbol"] if asset else chains.symbol(chain),
+        "asset": asset["symbol"] if asset else chains.symbol(chain), "depth": depth,
         "generated": datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
         "errors": [],
     }
@@ -83,6 +83,9 @@ def analyse(address: str, chain: str = "eth", asset: Optional[dict] = None,
     except chains.ChainError:
         result["poisoning"] = []
 
+    # an exchange's own wallet is the exchange's to freeze, not the issuer's
+    result["freeze"] = [] if result["type"] == "exchange" else freeze_mod.check(address, chain)
+
     result["guidance"] = build_guidance(result)
     return result
 
@@ -148,6 +151,23 @@ def build_guidance(r: dict) -> dict:
             "urgent": False,
         })
 
+    for e in r.get("freeze") or []:
+        if e.get("frozen"):
+            steps.insert(0, {
+                "title": freeze_mod.describe_frozen(e),
+                "body": ("It cannot be moved. Frozen funds can be returned to victims, but only "
+                         f"through a legal process: tell the police and {e['issuer']} that you "
+                         "are a victim of this address, and include this report."),
+                "urgent": True,
+            })
+        elif e.get("actionable"):
+            steps.insert(0, {
+                "title": f"Ask for a freeze: {e['movable']:,.2f} {e['token']} is still here",
+                "body": (f"{e['how']} It can be moved at any moment, so this is the most "
+                         f"time-critical step. {e['issuer']}'s policy: {e['url']}"),
+                "urgent": True,
+            })
+
     # always-applicable steps
     steps.append({
         "title": "Report it to the police",
@@ -206,11 +226,13 @@ def guidance_markdown(r: dict) -> str:
 
 
 def save_case(r: dict, out_dir: Path, asset: Optional[dict] = None) -> Path:
-    """Write the full report plus the guidance the victim can act on."""
-    md_path = report_mod.generate(r["address"], r["chain"], 3, 3, out_dir, asset)
+    """Write the case file (HTML, plus Markdown and JSON) with the victim's next steps;
+    returns the HTML one — the file to send."""
+    paths = report_mod.generate(r["address"], r["chain"], r.get("depth", 3), 3, out_dir, asset,
+                                guidance=r.get("guidance"))
     try:
-        with open(md_path, "a", encoding="utf-8") as fh:
+        with open(paths["md"], "a", encoding="utf-8") as fh:
             fh.write(guidance_markdown(r))
     except OSError:
         pass
-    return md_path
+    return paths["html"]