NICC (Nansen Intelligence Command Center)

NICC is a live-only terminal intelligence suite built on top of the Nansen API. It packages four operator workflows into one CLI and launcher:

• wallet: wallet profiling, conviction, history, and comparisons
• regime: market regime detection from live smart-money, holder, perp, and DEX data
• token: token radar, holder/flow analysis, and watch mode
• signals: leader/follower detection, crowd signals, propagation graphs, and alerting

This repository is prepared for public GitHub release and Nansen hackathon submission as a production-oriented project. Demo runtime paths and fake payload fallbacks are removed.

Production guarantees

• Live-only execution: no demo mode, no fake API payloads, no forced offline watchlists
• Secrets are env-only: NICC does not persist API keys, bot tokens, chat ids, or webhooks into repo files or saved YAML config
• Safe config views: CLI status commands expose only configured: true/false for sensitive integrations
• Local caching: SQLite cache for repeat runs, regime history, signals history, launcher favorites/macros, and alert dedupe

Requirements

• Python 3.10+
• A valid NANSEN_API_KEY
• Optional alert transports:
  • TELEGRAM_BOT_TOKEN
  • TELEGRAM_CHAT_ID
  • DISCORD_WEBHOOK_URL

Install

git clone <your-repo-url> nicc
cd nicc
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

Create a local env file from the template:

cp .env.example .env

Fill only the variables you actually use:

NANSEN_API_KEY=
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
DISCORD_WEBHOOK_URL=
NICC_SMART_MONEY_ADDRESSES=
NICC_CACHE_DIR=
NANSEN_HTTP_PROXY=

.env is gitignored and should never be committed.

First-time setup

Initialize the live watchlist config:

nicc config init --preset evm-active

Inspect the safe config view:

nicc config show

Import your own watchlist preset if needed:

nicc config import path/to/watchlist.yaml --force

Launcher

Run the built-in terminal launcher:

nicc

The launcher provides:

• one-command entrypoint for all NICC workflows
• favorites and macro favorites with saved arguments
• scrollable forms and result screens
• live watch screens for regime, signals, token, and wallet
• preview/status sidebar backed by local cache

CLI commands

Wallet

nicc wallet 0x...
nicc wallet 0x... --chain all
nicc wallet 0x... --conviction
nicc wallet 0x... --history
nicc wallet 0x... --compare 0x...

Regime

nicc regime
nicc regime --history 30
nicc regime --watch

Token

nicc token 0x...
nicc token 0x... --chain all
nicc token --search AERO
nicc token 0x... --watch

Signals

nicc signals
nicc signals --leaders
nicc signals --summary --format json
nicc signals --new
nicc signals --watch

Collection

nicc collect all
nicc collect regime
nicc collect signals --quiet --format json

Watchlist

nicc watchlist show
nicc watchlist collect-candidates --chain all --tokens 4 --token-offset 0 --holders-per-token 12 --candidates 40 --probe-trade-limit 12 --probe-min-trades 3 --probe-min-median-trade-usd 1000 --pool-key evm_default
nicc watchlist collect-candidates --chain all --tokens 4 --token-offset 4 --holders-per-token 12 --candidates 40 --probe-trade-limit 12 --probe-min-trades 3 --probe-min-median-trade-usd 1000 --pool-key evm_default
nicc watchlist score --chain all --candidates 40 --top 8 --trade-limit 80 --min-median-trade-usd 1000 --pool-key evm_default --format json
nicc watchlist build --format json
nicc watchlist build --chain all --tokens 12 --holders-per-token 25 --candidates 40 --probe-trade-limit 12 --top 10 --min-median-trade-usd 1000 --save

watchlist build uses a live EVM-wide basket from Nansen token screener, token holders, and wallet trade activity to derive a reproducible smart-money watchlist. Built results can be inspected first and then persisted with --save. For larger live runs, prefer the staged flow: collect-candidates in a few token batches, then score. This is more robust against Nansen backend timeouts than one very wide pass.

Alerting

NICC supports Telegram and Discord transport checks, enable/disable toggles, smoke tests, and dedupe introspection.

nicc config alert show
nicc config alert doctor
nicc config alert doctor --channel telegram
nicc config alert enable --channel telegram
nicc config alert disable --channel discord
nicc config alert test --channel telegram
nicc config alert history --limit 10
nicc config alert last
nicc config alert reset-dedupe

Notes:

• transport status commands do not print secret values
• seed-test-record only writes a local dedupe record and does not send externally
• channels must be both configured in env and enabled in config to become ready

Watchlists and config

NICC ships with live presets in nicc/config.py:

• evm-active
• base-active
• base-rotation
• eth-core
• founder-triad

base-* presets remain only as legacy-compatible named presets; current runtime behavior is EVM-wide by default.

Current defaults are EVM-wide:

• wallet, token, and watchlist default to --chain all
• watchlist default pool key is evm_default
• regime uses a multi-chain EVM basket instead of a Base-only basket

Two configuration layers are used:

• .env for secrets and machine-local overrides
• ~/.nicc/config.yaml for non-secret preferences and watchlist/profile state

Saved config intentionally excludes:

• NANSEN_API_KEY
• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHAT_ID
• DISCORD_WEBHOOK_URL

Smoke checks

Local smoke scripts are included:

./scripts/smoke-fast.sh
./scripts/smoke-release.sh
./scripts/smoke-full.sh
./scripts/smoke-live.sh

smoke-live.sh now targets the lightweight release profile. Use smoke-full.sh only for broader manual validation because it is slower and exercises heavier live paths.

These scripts assume the local virtualenv exists at ./.venv and that NANSEN_API_KEY is configured.

Testing

Run the unit test suite:

pytest -q

CI is configured in .github/workflows/ci.yml to run tests on pushes and pull requests.

Repository hygiene before publish

The repo is prepared so that public publication should follow this checklist:

1. Verify .env stays untracked.
2. Review git status --short for any local machine artifacts outside the project.
3. Run pytest -q.
4. Run at least one live smoke command with your own Nansen key.
5. Confirm nicc config show and nicc config alert show expose only boolean readiness fields for secrets.

Project layout

nicc/
├── nicc/
│   ├── main.py
│   ├── config.py
│   ├── cache.py
│   ├── nansen_client.py
│   ├── modes/
│   └── ui/
├── scripts/
├── tests/
├── .env.example
├── .gitignore
├── CHANGELOG.md
├── README.md
└── SPEC.md