Chain Insights

Website | GitHub | npm

Chain Insights is an open-source AML investigation toolkit for AI agents and analysts. Install it from npm to screen blockchain addresses, trace role-specific fund flows, manage workspace evidence, and generate graph reports.

Graph access is configuration-driven. The package defaults to a local GraphRAG MCP endpoint for development; hosted endpoints are set explicitly with graphMcpEndpoint or CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT.

What You Can Do Today

| Tool | Use it for | | --- | --- | | aml_address_risk | Screen one address for risk, behavior, neighborhood context, and exchange exposure | | aml_trace_victim_funds | Trace victim/source funds forward to exchange deposit candidates | | aml_trace_deposit_sources | Trace backward from suspected deposit/cashout addresses to upstream sources and convergence | | aml_trace_suspect_funds | Trace suspected scammer, mule, operator, or laundering-ring funds forward to cashout topology | | exposure_profile | Explain staking or trading exposure around an account, owner, or counterparty | | exposure_quality | Score whether exposure behavior looks disciplined, fragile, lucky, or noisy | | exposure_carry | Explain carry earned or paid from staking, trading, funding, fees, emissions, or dividends | | exposure_crowding | Measure side concentration for a market, subnet, hotkey, or strategy | | exposure_exit_pressure | Explain liquidation, slippage, unstake, funding pain, or other exit pressure | | exposure_correlation | Compare accounts for possible copy, overlap, or strategy-cluster behavior | | exposure_explain | Explain a specific exposure lifecycle, trade, position, stake, rotation, or incident | | graph_query | Run one read-only GQL/Cypher query against a GraphRAG MCP graph layer | | graph_query_batch | Run related read-only graph queries as one MCP call | | usage_status | Check the caller's daily free-tier graph query allowance |

Quick Start

Install from npm:

npm install -g chain-insights

Check the CLI:

cia --version
cia update --check

Run cia update to update a global npm install from the public npmjs registry. cia init also checks for a newer npm release in interactive terminals and prompts before updating.

From a local checkout:

npm install
npm run build
npm install -g .
cia --version

Create an investigation workspace:

mkdir -p ./chain-insights-investigations
cd ./chain-insights-investigations
cia init .

Chain Insights workspaces are plain local folders. Use any editor or agent tooling you want to inspect workspace files, graph reports, artifacts, and published outputs.

Configure GraphRAG MCP Endpoint

cia uses graphMcpEndpoint for all GraphRAG MCP calls. The npm package does not hardcode a hosted endpoint. Configure the endpoint explicitly for the environment you intend to use.

Local development endpoint (default):

cia config set graphMcpEndpoint http://127.0.0.1:8012/mcp

Hosted staging endpoint for approved testers:

cia config set graphMcpEndpoint https://staging-mcp.chain-insights.ai/mcp

For now, use the staging endpoint only for tester activation. Production is not live yet.

Hosted access also needs an access mode, such as an approved access key or a prepared wallet. Keep those credentials out of README examples; setup commands live in MCP proxy. For paid access, run cia wallet ready; it checks funding and finishes one-time payment setup.

Optional one-shot override from the environment:

export CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT=https://staging-mcp.chain-insights.ai/mcp

Validation rules:

• http:// is accepted only for localhost / loopback addresses.
• Remote hosts must use https://.
• Endpoint URLs with credentials, query strings, or fragments are rejected.

Configuration precedence for graphMcpEndpoint:

1. CHAIN_INSIGHTS_GRAPH_MCP_ENDPOINT env var (GRAPH_MCP_ENDPOINT legacy alias also supported)
2. cia config set graphMcpEndpoint ... saved value
3. Local default http://127.0.0.1:8012/mcp

Check the configured endpoint and current GraphRAG MCP capabilities:

cia config get graphMcpEndpoint
cia mcp networks
cia mcp call usage_status
cia mcp tools --refresh

If network or tool discovery fails, check the endpoint and access mode first. The CLI can still initialize workspaces and continue investigation workflow without a reachable GraphRAG MCP endpoint.

Hosted GraphRAG MCP includes a small public free tier for graph_query before paid access is required. The default public free tier is 10 execution seconds per IP per UTC day. Use usage_status to see the current caller allowance. Prepared wallet users receive the daily free tier first, then paid access continues automatically after the allowance is exhausted. If you do not have a prepared wallet yet, use bounded single graph_query calls within the free tier, then prepare a wallet or use an invited tester access key when the allowance is exhausted.

Run a focused investigation in the initialized workspace:

cia init .

cia mcp trace-victim-funds \
  --network bittensor \
  --victim-addresses 5GTjfJaLpBNrgybhY24NqhDnKW9r94z72RSYLxeodxJfSkj5

Then inspect:

find reports -maxdepth 3 -type f | sort

Export Only When Sharing

Normal local work happens in the workspace. Export only when you need to share, hand it off to a partner, ingest into LLM Wiki, or archive a review checkpoint.

# Use your configured workspace export flow to produce the handoff package.
published/<workspace-slug>/

Workspace-generated reports, graph JSON, graph HTML, and published bundles live under the initialized workspace. Treat those files as the durable handoff surface.

Examples

Run a direct live topology query:

cia mcp call graph_query \
  network=bittensor \
  "query=USE live_topology MATCH (n) WHERE n.address IS NOT NULL RETURN n.labels AS labels, n.address AS address LIMIT 10"

Run a batch across graph layers:

cia mcp call graph_query_batch \
  network=bittensor \
  'queries=[{"id":"count","query":"USE live_topology MATCH (n) RETURN count(n) AS count LIMIT 1"},{"id":"archive_flows","query":"USE archive_topology MATCH (src:Address)-[f:FLOWS_TO]->(dst:Address) RETURN f.period_granularity AS granularity, src.address AS source, dst.address AS target LIMIT 3"},{"id":"facts_sample","query":"USE facts MATCH (a:Address)-[:HAS_FEATURE]->(f:AddressFeature) RETURN a.address AS address, f.sent_count AS sent_count LIMIT 3"}]'

For no-wallet public free-tier usage, prefer the single-query example first. Batch calls reserve worst-case execution time and can ask for paid access even when a small free allowance remains.

Run suspect topology without requiring an incident timestamp:

cia mcp trace-suspect-funds \
  --network bittensor \
  --suspect-addresses 5... \
  --max-hops 16

How It Fits Together

Agent or CLI user
  -> Chain Insights CLI / MCP proxy
  -> local config, wallet, workspace, artifacts, reports
  -> GraphRAG MCP
  -> graph intelligence for AML workflows

Chain Insights stores investigation outputs in initialized local workspaces. GraphRAG MCP performs graph-language reads against network-specific graph layers.

Graph Access

Graph queries must choose the right read layer explicitly:

| Layer | Use it for | | --- | --- | | live_topology | Recent topology and fast traversal | | archive_topology | Historical fund-flow context | | facts | Labels, features, risk scores, assets, and enrichment |

Use graph_query_batch when related reads should share one call and one result envelope. Use explicit LIMIT and pagination in your query when you want bounded result sets. Endpoint access and authentication are configured separately; see MCP proxy.

Agent installs include chain-insights-cypher for generic layer-aware GQL/Cypher work and chain-insights-bittensor-cypher for Bittensor-specific schema notes and examples.

AML Tools

The high-level AML tools are Chain Insights workflows built around graph access and local workspace state:

• aml_address_risk starts a single-address screen with risk, behavior, neighborhood context, and exchange exposure.
• exposure_profile explains staking exposure and trading exposure with venues, instruments, position changes, public support events, and caveats when pricing or unit coverage is incomplete.
• exposure_quality, exposure_carry, exposure_crowding, exposure_exit_pressure, exposure_correlation, and exposure_explain add deterministic exposure analytics over the same generic model. They work for Bittensor staking rows now and are shaped for Hyperliquid trading rows as soon as the Hyperliquid indexer writes the shared exposure contract.
• aml_trace_victim_funds traces victim/source funds forward through intermediaries to exchange deposit candidates.
• aml_trace_deposit_sources traces backward from suspected deposit/cashout addresses to upstream sources and shared-source convergence.
• aml_trace_suspect_funds traces suspected scammer, mule, operator, or laundering-ring funds forward to cashout topology.

The three trace tools share chain-insights.trace.v1 and return compact, chainable results. Full graph/table/report artifacts remain on disk under the workspace, with pointers in the tool result and workspace evidence.

Trace traversal treats exchange hot wallets as terminal endpoints only. Tools do not expand through exchange nodes or classify them as deposit, suspect, or intermediate candidates.

When investigation output is large, tools can save compact evidence pointers and graph reports under the workspace instead of embedding large payloads in human notes.

Docs Map

| Doc | Use it for | | --- | --- | | Graph tools | GraphRAG MCP layers, graph_query, graph_query_batch, AML tool contracts, graph reports, evidence pointers | | Investigation workspaces | cia init, workspace layout, artifacts, imports, templates, sessions, reports, and visualization outputs | | MCP proxy | Stdio proxy behavior, endpoint configuration, agent installers, local tools, auth modes, Inspector validation | | Architecture | Product layers, data flow, local storage, security model, config keys | | Development | Build, test, and local install commands | | Contributing | Development workflow, pull requests, release expectations | | Debugging | Local troubleshooting, diagnostics, debug workflows |

What It Is Not

Chain Insights is not a custodial wallet, hosted case database, or replacement for analyst review. It does not write risk labels automatically. Investigation data stays in the local workspace unless the operator exports or shares it.