ChainSightline

Follow the line. ChainSightline turns blockchain activity into one route you read from top to bottom: what moved, between whom, which warnings deserve a look, and exactly where the evidence ends.

• Trace a transaction or an address, and click any address to keep following the line.

• Before you send: check an address you're about to pay for lookalikes of people you've paid, token contracts, and never-used accounts.

• Wallet checkup: find your active approvals, with revoke links, and scam attempts in your history.

• Explain with AI: a plain-language summary from Kimi K3.1 Pro or any OpenRouter model, citing each stop.

• For AI agents: an MCP tool server so Claude, Cursor and other agents can run the same checks.

Try it

You need Node.js 22.12 or newer. Docker is optional.

git clone https://github.com/sjdsjadjajdjsa/chainsightline.git
cd chainsightline
npm install

In your terminal

npm run cli -- trace 0xTransactionHash   # follow a real transaction, no key needed
npm run cli -- trace 0xAddress           # recent transfers in and out (needs an Alchemy key)
npm run cli -- check 0xRecipient --from 0xYou   # check an address before you send
npm run cli -- checkup 0xYourWallet             # active approvals and scam attempts
npm run cli -- trace 0x… --explain       # add an AI explanation (OpenRouter key)
npm run cli -- trace 0x… --evidence      # add full addresses and exact amounts
npm run cli -- trace 0x… --json          # machine-readable output
npm run cli -- sample                    # the invented example route

Run npm link once to use it as chainsightline from anywhere, for example chainsightline trace 0x….

In your browser, no Docker

npm run web          # or: chainsightline web

The first run builds the site, then it opens at http://127.0.0.1:3000 in your default browser. Press Ctrl+C to stop it. Use --port 3001 if 3000 is busy and --no-open to skip the browser.

In Docker

npm start            # build, wait until healthy, open the browser
npm stop             # stop without deleting data

The container is read-only, runs as a non-root user and is reachable only from your own computer.

For AI agents (MCP)

ChainSightline runs as an MCP tool server, so AI agents can trace transactions, check recipients and run wallet checkups. Every tool is read-only.

chainsightline mcp --print-config   # prints the settings to paste into your AI app

For Claude Code, the printed claude mcp add line adds it in one step. For Claude Desktop or Cursor, paste the printed JSON into their MCP settings. Tools: trace_transaction, trace_address, check_recipient and wallet_checkup. Each returns the route as plain text plus the same data as JSON, including where the evidence ends.

Related MCP server: web3-risk-mcp

Your own keys (optional)

ChainSightline works out of the box using dRPC's free public access. Free keys of your own make it faster and unlock more:

Add them whichever way is easiest:

• In the website: click Your keys under the search box and paste. Each key is checked before it is saved.

• In the terminal: run chainsightline setup (or npm run cli -- setup). chainsightline keys shows what is set.

• In a file: put DRPC_KEY=…, ALCHEMY_API_KEY=… and OPENROUTER_API_KEY=… in a .env file in the project folder. Docker picks these up too.

You can paste either the key itself or the whole link the provider shows you. Keys stay on your computer (~/.config/chainsightline/keys.json, readable only by you), are only ever sent to the provider they belong to, and never appear in output or error messages.

How it works

flowchart LR
    A["Address or transaction"] --> B["Collect evidence<br/>dRPC or Alchemy"]
    B --> C["Normalise into stops"]
    C --> D["Explainable warnings"]
    D --> E["The route<br/>web or terminal"]
    E --> F["Optional cited<br/>AI explanation"]

    style B fill:#e3efe9,stroke:#21685c,color:#1d2928
    style A fill:#e3efe9,stroke:#21685c,color:#1d2928
    style C fill:#e3efe9,stroke:#21685c,color:#1d2928
    style D fill:#e3efe9,stroke:#21685c,color:#1d2928
    style E fill:#e3efe9,stroke:#21685c,color:#1d2928
    style F fill:#e3efe9,stroke:#21685c,color:#1d2928

1. You paste an address or transaction hash. It is checked before anything else happens.

2. ChainSightline asks a data provider for the transaction, its receipt, its block and its call trace. Your own key is used first; if it fails, dRPC's free public access takes over. For an address, Alchemy returns its 20 most recent transfers.

3. Each movement becomes a stop with a plain sentence such as "0.42 ETH left the subject", plus the two addresses colour-coded and labelled by role. ETH sent with the transaction, ETH moved between contracts inside it, token and NFT transfers, and approvals are all included. Token names are read from the token contracts. Addresses show their ENS name or a known label (exchanges, routers, major tokens) next to the hash, and amounts show their dollar value from DefiLlama.

4. Rules attach warnings to the stop they concern: unlimited and collection-wide approvals (with a link to revoke them), lookalike addresses and address poisoning, zero-value transfers planted in someone else's history, fake copies of USDT, USDC, DAI, WETH, WBTC, stETH and ETH, tokens whose names advertise websites, and transfers out of a wallet that the wallet never sent. A warning is a reason to look closer, never a verdict.

5. The route ends with what is still unknown, such as a missing call trace, hidden events, or movements beyond the first 40, so missing data never reads as safety.

6. Planned: an AI model (Kimi by default, or any compatible OpenRouter model) explains the route. Its answer must cite the evidence or it is rejected. The adapter is built and tested but not yet wired into the app.

Every stop links to Etherscan so you can check it yourself, and the address bar updates (for example ?tx=0x…) so you can copy a link that reopens the same investigation in any ChainSightline.

The website and the terminal share the same evidence format and wording, so both always tell the same story.

What leaves your computer: the transactions and addresses you look up go to your chain provider (dRPC or Alchemy), and token contract addresses with the block time go to DefiLlama for prices. Set CHAINSIGHTLINE_PRICES=off to turn prices off. When you ask for an AI explanation, the route's stops, names and warnings go to OpenRouter and the model provider, with zero-data-retention routing required by default.

Product principles

Planned architecture

flowchart TB
    UI["Next.js investigation interface"] --> API["Server API"]
    API --> DB[("PostgreSQL evidence and jobs")]
    API --> Worker["Durable TypeScript worker"]
    Worker --> History["Indexed transfer-history provider"]
    Worker --> Chain["Tracing-capable Ethereum RPC"]
    Worker --> Rules["Evidence normalizer and detection rules"]
    Worker --> AI["Configured evidence explanation provider"]
    Rules --> DB
    AI --> DB

Planned architecture; no deployed infrastructure yet.

TypeScript throughout: Next.js, React, viem, PostgreSQL, Drizzle, pg-boss, Zod and Cytoscape.js. One web application and one worker; no premature microservices.

See the full architecture for provider coverage, canonical evidence, transfer semantics, recovery and security contracts.

Roadmap

The detailed delivery roadmap tracks release gates. The concept review records strengths, weaknesses and priorities. The design system explains the visual rules.

Development

npm run dev            # live-reloading website
npm test               # unit tests for the evidence format, route wording, CLI and AI adapter
npm run typecheck
npm run test:browser   # with the site running: phone, laptop and ultrawide checks in both themes
npm run test:chain:live  # with DRPC_KEY in a local .env file: one real receipt and trace from Ethereum
CHAINSIGHTLINE_LIVE_TX=0x… npm run test:browser   # also render a real transaction in the browser

Kimi K3.1 Pro is the primary development model and the default product model. OpenRouter provides the provider-neutral transport; Kimi, OpenAI and Google models passed a small structured-output compatibility test. There is no silent fallback and privacy settings are never weakened automatically. See AI provider configuration and the smoke report. Real environment files are ignored by Git.

Security and license

Report security problems privately, as described in SECURITY.md. Contributions are welcome: see CONTRIBUTING.md.

ChainSightline is released under the MIT License. It is provided as is: it is not financial, legal or security advice, and a missing warning does not mean an address or transaction is safe.

Built with care for people who want to understand what actually happened on-chain.