Wallet Tracker

Fund-flow detective for Neo N3: trace transfers hop-by-hop, inspect holdings, label exchange and bridge wallets, watch addresses with live alerts.

Tools like Arkham, MetaSleuth and Breadcrumbs exist for EVM chains. Neo N3 had nothing comparable. Wallet Tracker fills that gap, fully open source under the MIT license.

Features

Trace fund flows. Start from any wallet, pick a token, and follow the money hop-by-hop through an interactive graph. Transfers are aggregated per counterparty, edges are scaled by amount, and time causality is enforced (funds cannot leave a wallet before they arrived). Fan-out caps and minimum-amount filters keep exchange-sized wallets readable. Tracing stops automatically at labeled exchanges, bridges and contracts, which is where on-chain tracing ends; a manual override lets you push through anyway.

Inspect any wallet. Current NEP-17 holdings with USD values (Flamingo price feed keyed by contract hash, CoinGecko as fallback), full transfer history with direction, counterparty and explorer links. Impostor tokens that reuse well-known symbols are flagged; mainnet really does have a fake GAS token.

Know who is who. Ships with a built-in directory of 135 verified Neo N3 addresses: the Binance hot wallet named in Neo's official statements, Upbit custody wallets, the Neo Foundation fund and all NF and NGD committee nodes, all 39 council candidates from the on-chain registry, all 22 NeoBurger agents, GhostMarket, Flamingo, the Poly Network bridge and the Neo X bridge. Every entry was verified on-chain. Signed-in users can add private names on top.

Watch wallets. Add addresses to watchlists with token, amount and direction filters. A server-side poller checks every watched address every five minutes and new transfers land in a realtime in-app activity feed, including transfers that happen while the app is closed.

Save investigations. Trace graphs persist as named case files and restore exactly where you left off.

How it works

• Chain data comes straight from public NeoGo RPC nodes (getnep17transfers, getnep17balances, invokefunction). No indexer to run: NeoGo nodes serve full per-address transfer history with pagination.
• The chain adapter (supabase/functions/_shared/neo/) is dependency-free and environment-free TypeScript, imported by both the browser app and Deno edge functions.
• The frontend is React 18 + Vite + TypeScript (strict) + Tailwind + TanStack Query, with the graph rendered by React Flow and laid out by dagre.
• Accounts, labels, watchlists, investigations and the activity feed run on Supabase: Postgres with row-level security on every table, email magic-link auth, a pg_cron-invoked edge function as the poller, and Realtime for live feed updates.
• Without Supabase configured, the app runs in chain-only mode: search, inspector and tracing all work, and account features hide automatically.

Getting started

Chain-only mode needs nothing but Node:

cd apps/web
cp .env.example .env.local   # RPC endpoints are prefilled
npm install
npm run dev                  # http://localhost:5173

Full mode additionally needs the Supabase CLI and Docker:

supabase start               # from the repo root; applies migrations + label seed
supabase status -o env       # copy API URL and anon key into apps/web/.env.local
cd apps/web && npm run gen:types

Environment variables

Variable	Where	Purpose
VITE_NEO_RPC_URLS	apps/web/.env.local	Comma-separated Neo N3 RPC endpoints, tried in order
VITE_SUPABASE_URL	apps/web/.env.local	Supabase project URL; leave empty for chain-only mode
VITE_SUPABASE_ANON_KEY	apps/web/.env.local	Supabase anon key
NEO_RPC_URLS	edge function secrets	RPC endpoints for the poller
POLLER_CONCURRENCY	edge function secrets	Addresses polled in parallel (default 5)

Development

cd apps/web
npm run test:unit            # vitest: adapter, trace engine, formatting, watch matching
npm run test:e2e             # playwright smoke suite
npm run typecheck && npm run lint

cd supabase/functions
deno check poll-watchlists/index.ts

supabase test db             # pgTAP row-level-security suites

Conventions worth knowing:

• apps/web/src/features/<name>/ holds pages, components and a queries.ts with all TanStack Query hooks. Pure logic lives in plain .ts siblings and is unit-tested.
• The shared Neo adapter must stay dependency-free and env-free (RPC URL is always a parameter) so it keeps working in both runtimes.
• supabase/db-types.gen.ts is generated and committed; CI fails on drift.
• Timestamps in getnep17transfers are UTC milliseconds and omitted ranges default to the last 7 days, so ranges are always passed explicitly. Token amounts are raw integer strings; decimals are applied with BigInt. Tokens are always keyed by contract hash, never by symbol.

Production notes

• Deploy the frontend as a static site and the supabase/ project to a hosted Supabase instance.
• Set edge function secrets: supabase secrets set --env-file supabase/.env (see supabase/.env.example).
• The pg_cron poller needs two Vault secrets in the database, functions_base_url and service_role_key; see supabase/migrations/0008_cron.sql.

Known address directory

The built-in directory lives in apps/web/src/data/knownAddresses.ts and, to our knowledge, is the first public label dataset for Neo N3. Provenance for every entry is documented in supabase/migrations/0010_famous_seed.sql and includes Neo official statements, the Neo Foundation transparency portal, the on-chain committee registry, project repositories and on-chain clustering. Corrections and additions are very welcome; please include a verifiable source.

Roadmap

• Sign in with NeoLine (SIWN) as an alternative to email
• Telegram and email alert channels
• NeoGo websocket subscriptions to replace polling
• NEP-11 (NFT) transfer support
• More labeled wallets, especially remaining exchange hot wallets

License

MIT, see LICENSE.