EN | RU

ton-trace-targets

Local OSINT / AML tracer for TON (Gram, Jetton).

Open a wallet or transaction → mark leads → build a money-flow tree → set target addresses and automatically catch "search → target" links.

No Docker, no npm, no pip - just Python 3 and a browser.

---

Features

• Search by address (EQ… / UQ…) or transaction hash
• Transfer feed with income / expense highlighting
• Leads - manual marking of suspicious transfers
• Next hops - auto-suggestions: next hop, same sus wallet, neighboring outgoing
• Tree - hierarchy of confirmed leads + potential branches
• Target addresses - address pool with pink accent in the UI
• Auto-links - if the open wallet is linked to a target (directly or via 1 hop), the transfer immediately becomes a lead
• Target↔target links - direct transfers and common intermediaries

Data source: TonAPI.

---

Quick start

git clone <repo-url> ton-trace-targets
cd ton-trace-targets
python3 start.py

Opens http://127.0.0.1:8787.

TonAPI key (optional)

Without a key, public rate limits apply. For stable operation:

1. Get a key from @tonapi_bot
2. Run:

export TONAPI_KEY=your_token_here
python3 start.py

If port 8787 is busy, the server picks a free one automatically.

---

Usage

1. Basic wallet analysis

1. Paste address or hash into Transaction or wallet → Search
2. In the feed, click Lead on the transfer you need
3. Next hops appear on the right - add to chain or skip
4. Tree tab - view hierarchy

2. Target addresses

1. In Target addresses, enter one or more addresses comma-separated
2. Save - targets are highlighted in feed / tree
3. Open a suspicious wallet in search
4. If there is a path search → target, links automatically become leads
5. Links tab / Links button - full report (direct + via intermediary)

3. Address clicks

An address in a transfer card is clickable - opens that wallet in search.

---

Project structure

ton-trace-targets/
├── start.py          # entry point: server + browser
├── server.py         # HTTP API, TonAPI, links/leads logic
├── frontend/
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── README.md
└── .gitignore

File	Role
start.py	Runs server.main()
server.py	Stdlib HTTP server, TonAPI cache/retries, leads, suggestions, links
frontend/	UI: feed, tree, links, targets

---

API (local)

Method	Path	Description
POST	/api/search	{ "query": "EQ…|hash" } → transfers
POST	/api/leads	add lead
GET	/api/leads	list leads
DELETE	/api/leads/{id}	remove lead
GET	/api/suggestions?lead_id=	next hops
POST	/api/links	{ "addresses": [...], "source": "EQ…" } → links
POST	/api/dismiss	dismiss potential
POST	/api/reset	reset case

Lead state is in process memory (resets after server restart).
Target addresses are also cached in browser localStorage.

---

Environment variables

Variable	Default	Description
TONAPI_KEY	-	TonAPI Bearer token
TONAPI_BASE	https://tonapi.io	API base URL

---

Limitations

• Auto-link depth: direct transfer + 1 hop via intermediary
• History comes from recent TonAPI events (not full network archive)
• Mixers / privacy layers heavily reduce traceability
• Rate limit without a key may cause temporary errors - cache and retries included

---

Stack

• Python 3 (stdlib only)
• Vanilla JS + CSS
• TonAPI v2

---

License

MIT