The problem CryptoTracker solves

1.Crypto Exchange & FinTech Deposit Screening (KYT / AML)
Centralized exchanges (e.g., Coinbase, Binance, Kraken) and payment gateways risk losing their banking licenses and incurring severe non-compliance penalties if they process proceeds from scams or hacks.
CryptoTracker detects when tainted funds arrive at known exchange deposit addresses in real time, enabling platforms to flag or freeze incoming transactions before the assets are liquidated into fiat.
2.DeFi Protocol Exploit & Post-Hack Incident Response
When a DeFi protocol or cross-chain bridge is exploited, security response teams face a race against the clock to determine where stolen liquidity is moving before it is washed through liquidity pools or off-ramped.
Automated BFS graph exploration tracks rapid multi-hop split transactions, allowing security firms and white-hat triage teams to map the attacker's trajectory in minutes rather than hours of manual block exploration.
3.Phishing & Wallet Drainer Asset Recovery for Victims
Millions of retail users lose funds annually to malicious signature drainers, romance scams, and fake dApps. Victims and private forensic firms struggle to produce concrete proof of where the funds ended up.
Generates structured forensic traces and audit dossiers proving the exact unbroken path from the victim's wallet to a specific off-ramp account, providing actionable documentation for civil claims and exchange support tickets.
4.Institutional Treasury & OTC Desk Counterparty Risk
Crypto hedge funds and institutional custodians face blacklisting or asset freezes if they accept liquidity that has indirect exposure to known fraud.
The forward haircut taint model calculates mathematically decayed contamination scores, giving risk officers objective thresholds for whether a counterparty wallet is safe to transact with.
5.Preventing "Dust-Poisoning" False Positives
Bad actors intentionally send micro-amounts ("dust") of illicit funds to innocent merchants, influencers, and services to poison their addresses and disrupt their operations under crude tracing tools.
Dust-filtering thresholds and volume-weighted decay ensure legitimate commercial addresses aren't falsely flagged or frozen.

Challenges we ran into

Sentinel (CryptoTracker) sits at an awkward meeting point: messy, live blockchain data on one side, and a Neo4j graph database, a NetworkX/LightGBM analysis engine and a GraphRAG intelligence layer on the other. Getting those pieces to cooperate taught us a lot. Three problems stand out, and all of them revolved around Neo4j and how we walked the graph.

1. The Neo4j connection that wouldn’t connect

What happened: Our /analyze-wallet FastAPI endpoint kept crashing with a 500 Internal Server Error. The logs showed ServiceUnavailable: Unable to retrieve routing information, repeated through several backoff retries before the request finally gave up.

Why it happened: Our .env file used NEO4J_URI=neo4j://127.0.0.1:7687. That neo4j:// scheme tells the Python driver to ask the database for a cluster routing table. We were running a single local Neo4j instance, not a cluster, so there was no routing table to give. The driver kept asking, and the handshake failed every time it tried to open a connection.

How we fixed it: We switched the URI to the direct Bolt protocol (bolt://127.0.0.1:7687), which skips routing discovery and talks straight to the database. We also made startup order strict: confirm the Bolt listener is live on port 7687 first, and only then launch the server with python -m uvicorn main:app --reload --env-file .env.

2. When the crawler followed the money into an exchange

What happened: Our first traversal logic in logic.py was simple. If a wallet received 20–25% or more of the outgoing funds, we flagged it as a suspicious hop and queued it for the next Etherscan crawl. That caused two problems.

Supernode explosion. Once laundered funds reached a major exchange hot wallet or a mixer like Tornado Cash, the crawler treated it as the next suspect. It then tried to pull in thousands of unrelated user withdrawals, which burned through our Etherscan API rate limits and turned the graph into an unreadable hairball.

Innocent wallets getting flagged. Ordinary retail wallets that split money across three or four normal payments looked like multi-hop laundering chains. Some of them scored above 70/100 for risk.

How we fixed it: We reworked detect_next_suspicious_wallets in logic.py and recalibrated the scoring/ pipeline (taint.py, patterns.py, offramp.py):

Circuit breakers for exchanges and mixers. Using entity resolution in normalize.py, any wallet labeled as a VASP, mixer or bridge now stops the crawl. We still record it in Neo4j as an off-ramp destination, which is exactly what an investigator needs for a subpoena, but we no longer crawl outward from it.
Dust filtering. We strip out micro-transaction “dust” before calculating total outflow, so it can’t skew the numbers.
Stricter peel-chain detection. A peel chain now has to be low fan-out (4 branches or fewer) and move 70–99.5% of the volume to the main branch (PEEL_MAIN_MIN to PEEL_MAIN_MAX).
Crash-proofing. We guarded every nx.shortest_path call with node-existence checks and handled NetworkXNoPath and NodeNotFound. We also fixed a TypeError in main.py (object of type 'bool' has no len()) caused by treating a boolean ML fraud flag as a list.
3. Connecting threat intel to the chain, and making Cypher approachable

What happened: A transaction graph on its own only tells you that one wallet sent funds to another. Investigators also wanted off-chain context, such as exploit reports and hacker group attributions, attached to those wallets. There were two obstacles. Most cybercrime investigators don’t write Cypher, so they couldn’t get answers out of Neo4j on their own. And that off-chain intel couldn’t reliably link to on-chain nodes, because a wallet written as 0xAbC... in one place and 0xabc... in another looks like two different wallets to the database.

How we fixed it:

We built a dedicated graphrag/ pipeline (schema.py, indexer.py, retriever.py, synthesizer.py). It lowercases and trims every extracted wallet address (.lower().strip()) before running Cypher MERGE, so threat intel attaches cleanly to the live Etherscan nodes already in the graph.