headless-tracker

🤖 This project is being developed and maintained autonomously by Hex, an AI dev agent. Decisions log: decisions.md · Daily build log: daily-log.md · Hex on Bluesky · Solo team. No human in the dev loop.

⚠️ Not financial advice. HeadlessTracker is a portfolio data aggregation tool. For informational purposes only. See DISCLAIMER.md for full text.

A read-only MCP server that lets your AI host (Claude Desktop, Claude Code, Cursor, ChatGPT) see your whole crypto portfolio across exchanges, on-chain wallets, and prediction markets — without ever giving it your API keys, and with no ability to trade or move funds. It reads the numbers; it can't touch the money.

_{↑ What your AI host renders from HeadlessTracker's data — one question, six venues, one view. The server returns the numbers; the host draws the picture. (Sample data; the visual is what a host renders on top of the tool output.)}

_{↑ And the raw input: real output of npx headless-tracker demo — six venues, no accounts, no API keys. Then ask your AI host about it.}

_{↑ Same data, a different question. Ask “how are my positions doing?” and your AI renders a trader view instead. There is no single dashboard — the host draws the one you ask for. (Templates coming: contribute a view, not a connector.)}

The thesis: AI hosts (Claude Desktop, Claude Code, Cursor, ChatGPT) generate dashboards on demand from structured data. Building yet another tracker UI is wasted work in 2026 — there is no single UI to build, your AI renders whatever view you ask for. Build the data layer; let the AI host be the renderer.

Status: Production-ready and live on npm (version badge above). Six connectors (Bybit, Binance, MetaMask/EVM, Solana, Hyperliquid, Polymarket), 15 MCP tools, an interactive multi-tab dashboard panel, a CLI for terminal queries, and a 428-test suite. Runs under plain Node (npx headless-tracker) or Bun, working end-to-end with Claude Desktop.

What it does

Connects to your accounts (read-only), normalizes everything into a single schema, exposes it as MCP tools. Then you ask Claude (or any MCP host):

• "What do I own?"
• "How is my portfolio split between crypto and prediction markets?"
• "Show my Polymarket positions grouped by event."
• "Refresh Bybit and tell me my BTC P&L."

The AI host generates the chart, the table, the breakdown. You don't build a UI.

Try it in 60 seconds (no API keys)

The zero-setup version — one command, no accounts, no keys, not even an address. See a full sample portfolio (five venues; crypto + cash + prediction markets) rendered exactly as your AI host receives it:

npx headless-tracker demo

account                 symbol               class       qty       value    price
──────────────────────  ───────────────────  ──────────  ────────  ───────  ───────
bybit:UNIFIED           BTC                  crypto      0.420000  $25704   $61200
binance:spot            SOL                  crypto      95.0000   $14440   $152.00
metamask:0xd8d2…f1a3    WBTC                 crypto      0.150000  $9150    $61000
solana:7vfC…Wd9k        JUP                  crypto      1800.00   $1656    $0.9200
polymarket:0x9c1a…7b20  RATE-CUT-2026 (YES)  prediction  1500.00   $930.00  $0.6200
…
Total: $104126  (15 positions across 5 venues)

Allocation by asset class:
  crypto         $88024   84.5%  ████████████████████
  cash           $14900   14.3%  ███
  prediction      $1202    1.2%  █

It also prints the plain-English questions you'd ask Claude ("what do I own across everything?", "how is it split?") mapped to the MCP tool that answers each. When you want your own numbers, it's the same loop with a real address or read-only key:

You shouldn't have to hand a new tool your exchange keys just to find out whether it's any good. Solana, Hyperliquid, and Polymarket read public on-chain addresses, so you can point HeadlessTracker at any wallet you can see (your own included) with zero credentials. (Hyperliquid is fully keyless — perp positions, account equity, and spot balances all read from just the address you trade from.)

# install (or prefix any command with `npx`)
npm install -g headless-tracker

# add a public Solana wallet: no API key, just the address
headless-tracker setup solana
#   Solana address (base58): <paste any public address>
#   (press ENTER through the optional RPC + dust prompts)

# print the holdings right in your terminal, no Claude required
headless-tracker show holdings

account            symbol  class   qty       value    price
─────────────────  ──────  ──────  ────────  ───────  ────────
solana:7Xk2…q9Fa   SOL     crypto  12.4081   $2604    $209.88
solana:7Xk2…q9Fa   USDC    crypto  540.0000  $540.00  $1.00
solana:7Xk2…q9Fa   JUP     crypto  1200.00   $612.00  $0.5100

Total: $3756  (3 positions across 1 accounts)

(Example output; the account id is shortened here for width. Your numbers come from the live chain.)

That is the whole loop: install, point at a public address, see normalized holdings. When you want your private accounts (Bybit, Binance), setup those too. Every connector uses read-only credentials, kept in your OS keychain, never written to disk and never sent anywhere except the exchange's own API. Then wire it into Claude and ask "what do I own?" to get the same data as a chat-native dashboard.

Non-interactive setup (scripts, Docker, CI)

setup also runs without prompts — pass flags, and keep any secret in an environment variable (never on the command line, so it stays out of your shell history):

# public-address connectors: everything via flags, zero secrets
headless-tracker setup solana --address=<base58> --dust=0.5
headless-tracker setup hyperliquid --address=0x...   # perp + spot, no key
headless-tracker setup polymarket --proxy-wallet=0x... 

# connectors with a secret: non-secret config via flags, secret via env
HT_SETUP_ETHERSCAN_KEY=… headless-tracker setup metamask --address=0x... --chains=1,137
HT_SETUP_API_KEY=… HT_SETUP_API_SECRET=… headless-tracker setup bybit --account-type=UNIFIED --also=FUND

Headless / no OS keychain (Docker, WSL, many Linux servers, CI): there's no Secret Service to write to, so setup registers the account and prints the exact HEADLESS_TRACKER_<CONNECTOR>_<ACCOUNT> env var to set with a JSON credential object — e.g. HEADLESS_TRACKER_SOLANA_<ADDR>='{"address":"…","dustThresholdUsd":0.5}'. Set it in your MCP server's environment and the data tools read credentials from there. Nothing is ever written to disk.

Interactive dashboard (live UI panel)

For hosts that support MCP Apps — Claude Desktop, ChatGPT, Goose, VS Code — say:

Show my dashboard

The host renders a sandboxed iframe in the chat panel with three live tabs: