Headless Tracker

headless-tracker

🤖 Este projeto está sendo desenvolvido e mantido de forma autônoma por Hex, um agente de desenvolvimento de IA. Registro de decisões: decisions.md · Registro diário de build: daily-log.md · Hex no Bluesky · Time solo. Nenhum humano no ciclo de desenvolvimento.

⚠️ Não é aconselhamento financeiro. HeadlessTracker é uma ferramenta de agregação de dados de portfólio. Apenas para fins informativos. Consulte DISCLAIMER.md para o texto completo.

Um servidor MCP somente leitura que permite ao seu host de IA (Claude Desktop, Claude Code, Cursor, ChatGPT) ver todo o seu portfólio de cripto em exchanges, carteiras on-chain e mercados de previsão — sem nunca dar a ele suas chaves de API, e sem capacidade de negociar ou mover fundos. Ele lê os números; não pode tocar no dinheiro.

_{↑ O que seu host de IA renderiza a partir dos dados do HeadlessTracker — uma pergunta, seis plataformas, uma visão. O servidor retorna os números; o host desenha o quadro. (Dados de exemplo; o visual é o que um host renderiza sobre a saída da ferramenta.)}

_{↑ E a entrada bruta: saída real de npx headless-tracker demo — seis plataformas, sem contas, sem chaves de API. Depois pergunte ao seu host de IA sobre isso.}

_{↑ Mesmos dados, uma pergunta diferente. Pergunte “como estão minhas posições?” e sua IA renderiza uma visão de trader em vez disso. Não existe um único dashboard — o host desenha aquele que você pedir. (Templates em breve: contribua com uma visão, não com um conector.)}

A tese: hosts de IA (Claude Desktop, Claude Code, Cursor, ChatGPT) geram dashboards sob demanda a partir de dados estruturados. Construir mais uma UI de tracker é trabalho desperdiçado em 2026 — não existe uma única UI para construir; sua IA renderiza qualquer visão que você pedir. Construa a camada de dados; deixe o host de IA ser o renderizador.

Status: Pronto para produção e publicado no npm (selo de versão acima). Seis conectores (Bybit, Binance, MetaMask/EVM, Solana, Hyperliquid, Polymarket), 15 ferramentas MCP, um painel de dashboard interativo com múltiplas abas, uma CLI para consultas no terminal e uma suíte de 428 testes. Roda em Node puro (npx headless-tracker) ou Bun, funcionando de ponta a ponta com Claude Desktop.

Lista completa de recursos

• 6 conectores: Bybit, Binance Spot+Futures, MetaMask multi-chain + multi-wallet, Solana multi-wallet, Hyperliquid (perp + spot, somente endereço), Polymarket
• 15 ferramentas MCP: 6 de dados + 7 de gerenciamento de contas/tokens + 2 painéis de MCP App
• 3 prompts MCP (visões): portfolio-dashboard, weekly-review, risk-check — veja TEMPLATES.md e contribua com uma visão
• MCP App de dashboard interativo: 3 abas (Portfólio / Semanal / Risco) com gráficos de rosca + barras, seletor de moeda, botão de atualizar
• MCP App de Configurações ao vivo para configuração e administração
• Consultas de portfólio via CLI: show holdings / pnl / transactions (sem necessidade de Claude)
• Listas personalizadas de tokens ERC-20; FIFO + Custo Médio no histórico de transações
• Exibição multi-moeda (USD/EUR/GBP/HUF); preços spot e históricos da CoinGecko + Jupiter
• PnL por janela de tempo (--timeframe=24h|7d|30d|ytd)
• Suíte de 428 testes; roda em Node puro ou Bun
• Somente leitura e local-first: sem ordens/saques/transferências; 4 dos 6 conectores precisam apenas de um endereço público; segredos ficam no chaveiro do seu sistema operacional e nunca entram no contexto do modelo — veja SECURITY.md

Veja ROADMAP.md para o que está pronto, o que vem a seguir e o que está intencionalmente fora do escopo.

O que ele faz

Conecta-se às suas contas (somente leitura), normaliza tudo em um único esquema e expõe como ferramentas MCP. Então você pergunta ao Claude (ou a qualquer host MCP):

• "O que eu possuo?"
• "Como meu portfólio está dividido entre cripto e mercados de previsão?"
• "Mostre minhas posições na Polymarket agrupadas por evento."
• "Atualize a Bybit e me diga meu P&L de BTC."

O host de IA gera o gráfico, a tabela, o detalhamento. Você não constrói uma UI.

Experimente em 60 segundos (sem chaves de API)

A versão zero-configuração — um comando, sem contas, sem chaves, nem mesmo um endereço. Veja um portfólio de exemplo completo (cinco plataformas; cripto + dinheiro + mercados de previsão) renderizado exatamente como seu host de IA o recebe:

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%  █

Ele também imprime as perguntas em linguagem simples que você faria ao Claude ("o que eu possuo em tudo?", "como está dividido?") mapeadas para a ferramenta MCP que responde a cada uma. Quando você quiser seus próprios números, é o mesmo ciclo com um endereço real ou chave somente leitura:

Você não deveria ter que entregar suas chaves de exchange a uma nova ferramenta só para descobrir se ela é boa. Solana, Hyperliquid e Polymarket leem endereços públicos on-chain, então você pode apontar o HeadlessTracker para qualquer carteira que consiga ver (incluindo a sua) com zero credenciais. (Hyperliquid é totalmente sem chaves — posições perp, patrimônio da conta e saldos spot são lidos apenas do endereço de onde você negocia.)

# 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)

(Exemplo de saída; o id da conta foi encurtado aqui por largura. Seus números vêm da chain ao vivo.)

Esse é o ciclo completo: instale, aponte para um endereço público, veja os ativos normalizados. Quando quiser suas contas privadas (Bybit, Binance), setup também. Cada conector usa credenciais somente leitura, mantidas no chaveiro do seu sistema operacional, nunca gravadas em disco e nunca enviadas a lugar nenhum exceto à API da própria exchange. Depois conecte ao Claude e pergunte "o que eu possuo?" para obter os mesmos dados como um dashboard nativo de chat.

Configuração não interativa (scripts, Docker, CI)

setup também roda sem prompts — passe flags e mantenha qualquer segredo em uma variável de ambiente (nunca na linha de comando, para que fique fora do histórico do seu shell):

# 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 / sem chaveiro do SO (Docker, WSL, muitos servidores Linux, CI): não há Secret Service para gravar, então setup registra a conta e imprime a variável de ambiente HEADLESS_TRACKER_<CONNECTOR>_<ACCOUNT> exata a ser definida com um objeto JSON de credenciais — ex.: HEADLESS_TRACKER_SOLANA_<ADDR>='{"address":"…","dustThresholdUsd":0.5}'. Defina-a no ambiente do seu servidor MCP e as ferramentas de dados lerão as credenciais de lá. Nada é gravado em disco.

Dashboard interativo (painel de UI ao vivo)

Para hosts que suportam MCP Apps — Claude Desktop, ChatGPT, Goose, VS Code — diga:

Mostre meu dashboard

O host renderiza um iframe em sandbox no painel de chat com três abas ao vivo:

• Portfólio — KPIs de valor total, tabela de principais posições, gráfico de rosca de alocação por símbolo (top 7 + cauda "Outros"), avisos + falhas
• Semanal — KPIs de delta em janela de 7 dias, tabela de negociações recentes, divulgação de símbolos ignorados (com motivos)
• Risco — auditoria de concentração (posição única, plataforma, reserva de stablecoin, sobrepeso em mercado de previsão) pontuada como PASS / WARN / ALERT, gráfico de rosca por plataforma

Além de um seletor de moeda (USD / EUR / GBP / HUF) e um botão de atualizar. O iframe faz suas próprias chamadas de ferramenta de acompanhamento conforme o usuário clica nas abas — sem necessidade de prompts adicionais depois de aberto. Argumentos opcionais:

Abra o dashboard em HUF, aba semanal

Implementação: src/mcp/apps/dashboard/ (TS do lado do navegador empacotado em um único dist/mcp-apps/dashboard.html via bun run build:apps, incluído no pacote). O artefato empacotado é enviado dentro do pacote npm para que usuários que executam npx headless-tracker não precisem de etapa de build.

Se o seu host ainda não renderiza MCP Apps, a ferramenta render_dashboard ainda retorna uma confirmação textual. Use o cookbook de prompts abaixo como alternativa — mesmos fluxos de trabalho, mesmos dados, apenas sem painel de UI ao vivo.

Painel de Configurações (UI ao vivo para configuração + administração)

Para configuração que não te leva a um terminal, pergunte:

Abra configurações

O MCP App de Configurações abre com quatro abas:

• Contas — lista de contas configuradas com um botão Remover (diálogo de confirmação de mão única; exclui tanto do chaveiro do SO quanto do registro).
• Adicionar Conta — formulários para Bybit / Binance / MetaMask / Solana / Hyperliquid / Polymarket. Cada formulário valida contra a API upstream antes de persistir as credenciais. Divulgação explícita de segurança no topo: credenciais enviadas pelo formulário transitam pelo processo do Claude Desktop a caminho do chaveiro. Todos os seis conectores usam credenciais SOMENTE LEITURA por design (Bybit "Read" apenas, sem Withdraw; Binance "Enable Reading" apenas, sem Trade ou Withdraw; Etherscan é um token público de rate-limit para dados; carteira proxy da Polymarket já é pública; endereços Solana e Hyperliquid são identificadores públicos on-chain — Hyperliquid não precisa de chave ou assinatura alguma). Vazamento no pior caso = leitura de portfólio, nunca movimentação de fundos. Para zero confiança, o fluxo CLI (bun run setup <connector>) permanece disponível.
• Carteiras — adicione um endereço de carteira adicional a uma conta MetaMask OU Solana existente (multi-carteira sob uma conta MCP, compartilhando a mesma chave/seleção de chain da Etherscan ou URL RPC).
• Tokens Personalizados — liste / adicione / remova tokens ERC-20 por chain. Os dados de tokens são públicos on-chain; sem envolvimento do chaveiro.

Qualquer caminho (CLI ou UI de Configurações) grava no mesmo ~/.headless-tracker/cache.db + chaveiro do SO, então contas criadas por qualquer um aparecem imediatamente no dashboard e na CLI.

Início rápido

1. Instalação

Sem clone, sem etapa de build, sem Bun necessário. O pacote roda em Node puro (≥ 22.5) ou Bun. Instale globalmente:

npm install -g headless-tracker

Ou execute qualquer comando sem instalar prefixando npx, ex.: npx headless-tracker setup solana. (Compilar a partir do código-fonte para desenvolvimento usa Bun — veja Desenvolvimento.)

2. Configure suas contas (interativo)

Execute a configuração para cada integração desejada. Cada uma solicita credenciais, valida-as e as armazena no chaveiro do seu SO (Keychain do macOS, Secret Service do Linux, Credential Vault do Windows). Em uma máquina headless sem chaveiro, veja Headless / sem chaveiro do SO abaixo.

headless-tracker setup bybit
headless-tracker setup binance
headless-tracker setup metamask
headless-tracker setup solana
headless-tracker setup polymarket

Verifique o que está configurado:

headless-tracker list-accounts

Headless / sem chaveiro do SO (Docker, WSL, servidores, CI)

O chaveiro do SO precisa de um serviço de segredos em execução (Secret Service / D-Bus no Linux, Keychain no macOS, Credential Vault no Windows). Muitos ambientes reais não têm um: um contêiner Docker, WSL, um servidor Linux puro, um job de CI. Nesses casos, a gravação no chaveiro falha.

Nesse caso, setup não aborta. Ele ainda registra a conta e imprime a variável de ambiente exata a ser definida, por exemplo:

⚠  OS keychain unavailable, so credentials were NOT stored (...). The account is
   registered. ... set the HEADLESS_TRACKER_SOLANA_<ADDR> environment variable to a
   JSON object in your MCP server's env, then restart.

Defina essa variável com o JSON de credenciais do conector no bloco env do seu servidor MCP (ou no seu shell) e reinicie. A variável de ambiente sempre tem precedência sobre o chaveiro, então isso também funciona como uma substituição explícita. Formatos JSON por conector (use chaves de API somente leitura — veja a nota de segurança na seção do painel de Configurações):

Conector	Variável de env (impressa por setup)	Valor JSON
Bybit	HEADLESS_TRACKER_BYBIT_<ACCOUNTTYPE>	{"apiKey":"...","apiSecret":"...","accountType":"UNIFIED"}
Binance	HEADLESS_TRACKER_BINANCE_KEY_<FIRST6>	{"apiKey":"...","apiSecret":"...","includeFutures":false}
MetaMask	HEADLESS_TRACKER_METAMASK_0X<ADDR>	{"address":"0x...","etherscanApiKey":"...","chainIds":[1],"trackCommonTokens":true,"hasEtherscanPro":false}
Solana	HEADLESS_TRACKER_SOLANA_<ADDR>	{"address":"<base58>"} (opcional "rpcUrl", "dustThresholdUsd")
Hyperliquid	HEADLESS_TRACKER_HYPERLIQUID_0X<ADDR>	{"address":"0x..."} (opcional "dustThresholdUsd")
Polymarket	HEADLESS_TRACKER_POLYMARKET_0X<ADDR>	{"proxyWallet":"0x...","sizeThreshold":0.01}

O nome da variável é derivado do identificador da conta (setup imprime a string exata, então você não precisa construí-la manualmente). Exemplo para um bloco env de configuração do Claude Desktop / MCP:

"env": {
  "HEADLESS_TRACKER_SOLANA_<ADDR>": "{\"address\":\"<base58 address>\"}"
}

Opcional: timeout de requisição

Cada busca por conta é limitada por um prazo (padrão de 30s), então um upstream travado nunca pode travar uma chamada de ferramenta — ela degrada para uma falha network_timeout para aquela conta específica enquanto as demais retornam. Substitua com HEADLESS_TRACKER_REQUEST_TIMEOUT_MS (por exemplo, aumente se você rastreia muitas chains EVM em uma única conta MetaMask e vê timeouts espúrios).

3. Conecte o Claude Desktop

Edite seu claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "headless-tracker": {
      "command": "npx",
      "args": ["-y", "headless-tracker"]
    }
  }
}

Essa é toda a configuração: sem caminhos absolutos, sem local de clone, sem Bun. npx -y headless-tracker sem subcomando inicia o servidor MCP via stdio (o npx armazena em cache após a primeira execução). Se você instalou globalmente com npm i -g headless-tracker, pode usar "command": "headless-tracker" sem args.

Reinicie o Claude Desktop (Cmd+Q e reabra — a "nova conversa" no app não recarrega a configuração).

4. Experimente

Abra uma nova conversa no Claude Desktop:

O que tem na minha carteira?

Como minha carteira está dividida entre cripto e mercados de previsão?

Mostre minhas posições na Polymarket ordenadas por valor atual.

Se o Claude não vir as ferramentas, verifique ~/Library/Logs/Claude/mcp-server-headless-tracker.log.

5. Use o dashboard interativo (MCP App)

Quando a configuração funcionar, pergunte:

Mostre meu dashboard

O painel de UI ao vivo aparece no chat. Veja a seção Dashboard interativo acima para saber o que há em cada aba e como passar argumentos.

6. Use os prompts predefinidos (dashboards de um clique)

O servidor MCP inclui três modelos de prompt. Eles aparecem no seletor de prompts do Claude Desktop (o menu / ou de anexos, dependendo da versão) e no Claude Code como comandos de barra. Cada um guia o Claude por um fluxo de trabalho específico com múltiplas ferramentas:

Prompt	O que faz
portfolio-dashboard	Chama get_holdings + get_allocations + get_pnl + get_polymarket_positions em paralelo e renderiza um dashboard completo de múltiplas seções (artefato HTML quando suportado).
weekly-review	Delta de janela de 7 dias + maiores variações + negociações recentes + uma observação. Ressalva de aproximação apresentada honestamente (cesta atual a preços históricos, NÃO negociações dentro da janela).
risk-check	Concentração / venue / reserva de stablecoin / sobrepeso em mercados de previsão / concentração por chain. Cada dimensão pontuada como PASS / WARN / ALERT com as porcentagens reais.

Você também pode colar qualquer um desses prompts diretamente — são texto puro. Veja o cookbook abaixo.

Cookbook de prompts

Copie e cole estes em qualquer cliente compatível com MCP. Cada um espera que o servidor MCP headless-tracker esteja configurado. Nenhum requer código novo no lado do servidor.

Rápido "onde estou"

Monte um dashboard completo da minha carteira. Chame get_holdings, get_allocations (por asset_class e por symbol), get_pnl e get_polymarket_positions em paralelo e sintetize um único artefato de dashboard. Mostre as 10 maiores posições, divisão por classe de ativo, PnL total. Seja honesto sobre campos NULL — não invente.

Rápido "como foi a semana"

Faça uma revisão de 7 dias. Chame get_pnl com timeframe=7d, get_holdings e get_transactions com since=7d. Apresente windowDelta com a ressalva de aproximação ("cesta atual a preços históricos, não negociações dentro da janela"), liste as negociações por exchange e termine com uma observação curta sobre o que impulsionou a mudança.

Rápido "devo me preocupar"

Verifique o risco da minha carteira. Chame get_holdings e get_allocations (por symbol, por asset_class, por connector). Pontue cada um: concentração de posição única (ALERT > 40%), concentração de venue (ALERT > 70%), reserva de stablecoin (WARN < 5%, ALERT = 0%), prediction-market overweight (WARN > 15%). Saída como tabela markdown.

Temporada de impostos

Preciso fazer meus impostos. Chame get_transactions para o último ano (since=365d). Depois chame get_pnl com include_history=true e method=fifo. Agrupe PnL realizado por symbol e por mês. Sinalize quaisquer vendas com base de custo desconhecida (depósitos / transferências sem preço) — essas são lacunas honestas que terei que pesquisar separadamente.

Visão em HUF (ou EUR / GBP)

Mostre minha carteira em forint húngaro. Chame get_holdings com currency=HUF. Ordene por valor decrescente. Some o total em HUF e me diga se a fonte de câmbio foi a API ao vivo ou o fallback estático.

Revisão de apostas na Polymarket

Explique minhas posições na Polymarket. Chame get_polymarket_positions com group_by_event=true. Depois chame get_pnl com include_history=true para obter PnL realizado via FIFO sobre /trades. Para cada evento, mostre: título, minhas participações no resultado, valor atual, PnL realizado até agora e data de término. Sinalize quaisquer posições resgatáveis que eu deva reivindicar.

Consultas rápidas de carteira via CLI (sem precisar do Claude)

Para a pergunta de 3 segundos "o que tem na minha carteira?" sem abrir o Claude Desktop:

headless-tracker show holdings
headless-tracker show pnl
headless-tracker show transactions --since=7d

Cada um imprime uma tabela de texto. Filtros funcionam: show holdings --account-id=bybit:UNIFIED, show holdings --asset-class=crypto, show transactions --since=24h --account-id=metamask:0xabc.

Exibição multi-moeda

show holdings usa USD por padrão. Passe --currency= para valores convertidos por câmbio ao vivo:

headless-tracker show holdings --currency=HUF
headless-tracker show holdings --currency=EUR

As taxas de câmbio vêm de uma API pública gratuita (exchangerate-api.com) com frankfurter.dev como fallback, além de um fallback estático se ambos falharem (que aparece como aviso para você saber que os números exibidos podem estar alguns por cento desatualizados). Suportadas: USD, EUR, GBP, HUF.

Métodos de base de custo (FIFO vs Média)

Para P&L realizado honesto baseado no seu histórico de transações (não em metadados de connector que podem misturar realizado + não realizado para mercados de previsão):

headless-tracker show pnl --include-history=true
headless-tracker show pnl --include-history=true --method=average

--method=fifo (padrão): consome o lote mais antigo primeiro por venda. --method=average: agrupa todas as aquisições precificadas; vende pela média ponderada corrente.

Ambos os métodos preservam a regra do "desconhecido honesto": tokens recebidos via transferência de carteira (sem preço) produzem realizedPnl: null para qualquer venda que os utilize — NÃO um número fabricado. O PnL realizado conta apenas vendas cujos lotes consumidos tinham base de custo conhecida.

PnL por janela de tempo

headless-tracker show pnl --timeframe=7d
headless-tracker show pnl --timeframe=24h
headless-tracker show pnl --timeframe=ytd

Valoriza sua cesta atual a preços históricos do CoinGecko e reporta o delta vs. agora. Aproximação: NÃO considera negociações dentro da janela — responde "se eu tivesse essa cesta exata N dias atrás, quanto ganhei?" Posições na Polymarket e cripto sem mapeamento no CoinGecko são ignoradas (contadas em skippedSymbols). O histórico gratuito do CoinGecko tem granularidade diária, então --timeframe=24h é "fechamento de ontem vs agora".

Tokens ERC-20 personalizados

A lista de tokens do MetaMask incluída cobre USDC, USDT, WETH, WBTC, LINK, DAI. Para rastrear tokens específicos de projetos:

headless-tracker token add metamask:0xabc 1 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 USDC 6
headless-tracker token list
headless-tracker token remove metamask:0xabc 1 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

Tokens personalizados são armazenados por conta no armazenamento SQLite da conta (NÃO no keychain — são identificadores on-chain públicos, não segredos).

Integrações suportadas

Connector	Auth	Status	Notas
Bybit V5	Chave API + segredo	✓ Completo	Contas UNIFIED / SPOT / CONTRACT / FUND. Chave somente leitura.
Binance	Chave API + segredo	✓ Holdings	Conta Spot (/api/v3/account) + carteira/posições Futures opcionais (/fapi/v2/account). Chave somente leitura ("Enable Reading" apenas). Stablecoins precificadas a $1; ativos não-stable precificados via lote /api/v3/ticker/24hr?type=MINI. Posições futuras abertas aparecem como Holdings separadas com lado/alavancagem/PnL/liquidação nos metadados. Histórico de transações é ok([]) para v0.13 — adiado. Apenas binance.com (binance.us adiado).
MetaMask / carteiras EVM	Chave API Etherscan V2	✓ Completo	Uma única chave cobre Ethereum, Polygon, BSC, Base, Arbitrum, Optimism. Tokens nativos + ERC-20 comuns incluídos (USDC, USDT, WETH, WBTC, LINK, DAI) para saldos; transferências nativas + ERC-20 para transações. Listas de tokens personalizados via headless-tracker token add .... Multi-carteira por conta (uma chave Etherscan, múltiplos endereços). BSC/Base exigem Etherscan Pro no nível gratuito (ignorados automaticamente com aviso caso contrário).
Polymarket	Endereço de carteira proxy (sem chave API)	✓ Completo	Usa data-api pública. Posições + histórico de negociações BUY/SELL (até ~1000 mais recentes) via /trades?user=PROXY. Posições com perda liquidada (mercados resolvidos a $0 que a data-api ainda retorna) são filtradas por um limite de poeira baseado em valor (dustThresholdUsd, padrão $0,01).
Carteiras Solana	Endereço Base58 (sem chave API)	✓ Holdings	RPC pública Solana + Jupiter Price API v2. SOL nativo + tokens SPL (Token program v1; Token-2022 adiado). Multi-carteira por conta, URL RPC premium opcional (Helius/QuickNode/Triton) para usuários rastreando 3+ carteiras. Metadados fixos para mints principais (USDC/USDT/mSOL/JUP/JTO/PYTH/BONK/RNDR/WIF/JLP). Histórico de transações é ok([]) para v0.12 — chegando na v0.14 com opt-in de RPC premium.
Hyperliquid	Endereço EVM (sem chave API, sem assinatura)	✓ Completo	Endpoint público info. Equity da conta perp reportada como valor líquido em USD da conta (colateral + PnL não realizado); posições perp abertas aparecem como Holdings separadas com tamanho assinado, nocional, PnL não realizado, preço de entrada/liquidação e alavancagem nos metadados — o nocional é deliberadamente não somado ao patrimônio líquido (superestimaria uma conta alavancada). Saldos spot precificados via pares USDC spotMetaAndAssetCtxs; USDC = $1, tokens sem preço filtrados por poeira. Histórico de transações via fills recentes (userFills, até 2000). Multi-endereço por conta.

Para adicionar um novo connector, implemente Connector de src/connectors/types.ts e adicione-o a CONNECTOR_FACTORIES em src/mcp/orchestrator.ts. ~150-400 linhas de código por connector com base nos seis existentes (depende se a API upstream é REST/SDK/RPC e quão rica é a forma da resposta).

Ferramentas MCP expostas

Ferramenta	Propósito	Prompts comuns
get_holdings	Holdings atuais em todas as contas	"o que eu possuo", "mostre minha carteira", "posições atuais"
get_pnl	Resumo agregado de lucro/perda	"como estou indo", "qual é meu P&L", "estou no positivo ou negativo"
get_polymarket_positions	Especializado em Polymarket, agrupado por evento	"mostre minhas apostas na Polymarket", "apostas eleitorais"
get_transactions	Histórico de transações com filtro since	"mostre minhas negociações recentes", "transações desta semana"
get_allocations	Divisão por grupo (classe de ativo / connector / chain / symbol)	"como minha carteira está dividida", "maiores posições"
refresh_data	Forçar invalidação de cache	"atualize", "pegue o mais recente", "busque agora"

As ferramentas de dados aceitam um filtro opcional account_id (ex.: metamask:0xabc..., bybit:UNIFIED). Sem filtro, consultam tudo.

Gerenciamento de contas e configuração (todas as gravações de credenciais são chaves API somente leitura armazenadas no keychain do SO):

Ferramenta	Propósito
setup_connector	Configurar um connector gravando credenciais somente leitura no keychain do SO
list_accounts	Listar contas configuradas sem expor credenciais
add_wallet_address	Adicionar outro endereço de carteira a uma conta MetaMask ou Solana existente
remove_account	Excluir uma conta e suas credenciais do keychain
add_custom_token	Rastrear um token ERC-20 específico de projeto em uma conta MetaMask
remove_custom_token	Parar de rastrear um token ERC-20 personalizado (dados on-chain públicos, sem keychain)
list_custom_tokens	Listar os tokens ERC-20 personalizados rastreados por conta MetaMask

Painéis do MCP App (UI interativa renderizada no chat):

Ferramenta	Propósito
render_dashboard	Painel de dashboard interativo: holdings, P&L, alocações, mercados de previsão
render_settings	Painel de configurações: uma alternativa GUI ao fluxo de configuração via CLI

Por que local-first

• As chaves de API nunca saem da sua máquina. Armazenadas no keychain do seu sistema operacional via @napi-rs/keyring.
• O cache é SQLite local (o driver embutido do runtime: node:sqlite no Node, bun:sqlite no Bun). Sem servidor, sem SaaS, sem pings de analytics.
• Sem telemetria por padrão. O relatório de erros é estritamente opt-in: só faz algo se você definir um SENTRY_DSN, e mesmo assim nunca envia dados de portfólio — sem valores, saldos, endereços de carteira, chaves de API ou rótulos de conta, apenas a classe do erro e uma mensagem/stack limpa, além de qual conector falhou. Veja decisions.md (2026-06-06) para os detalhes.
• Somente leitura por design. Sem assinatura de transações. Nada que esta ferramenta possa fazer pode perder seu dinheiro.
• TTL de cache por conector (carteiras cripto 60s, exchanges 120s, Polymarket 30s) mantém tudo rápido sem sobrecarregar as APIs upstream.

Arquitetura

              ┌────────────────────────────┐
              │     headless-tracker       │
              │      (Node or Bun)         │
              │  ────────────────────────  │
              │  src/connectors/           │
              │    bybit.ts                │
              │    metamask.ts             │
              │    polymarket.ts           │
              │  src/types.ts (schema)     │
              │  src/cache.ts (SQLite)     │
              │  src/vault.ts (keyring)    │
              │  src/accounts.ts (registry)│
              │  src/mcp/orchestrator.ts   │  ← parallel fan-out + in-flight Promise dedup
              │  src/mcp/server.ts         │  ← McpServer + 15 tools
              │       ▲                    │
              │       │ stdio MCP          │
              └───────┼────────────────────┘
                      │
       ┌──────────────┼──────────────┐
       │              │              │
┌──────▼──────┐ ┌─────▼─────┐ ┌──────▼──────┐
│Claude Desktop│ │Claude Code│ │ Cursor/Codex│
│  ChatGPT     │ │           │ │  ZED, etc.  │
└──────────────┘ └───────────┘ └─────────────┘

Exemplos de prompts e respostas

O objetivo do headless-tracker é que você não precise escrever SQL ou aprender uma CLI — você pergunta ao Claude. Algumas sessões de exemplo:

"O que eu possuo?"

Claude chama get_holdings({}) e retorna um resumo formatado: "Você atualmente possui 0,5 BTC (~US$ 30.000), 2 ETH (~US$ 5.000) na Bybit, mais 1 ETH na sua carteira MetaMask, e uma posição na Polymarket sobre a eleição de 2024 no valor de US$ 60. Valor total do portfólio: ~US$ 35.060."

"Mostre minhas apostas na Polymarket agrupadas por evento."

Claude chama get_polymarket_positions({ group_by_event: true }) e renderiza uma tabela agrupada por evento com título, suas participações em resultados Sim/Não, valor total do evento e P&L em dinheiro combinado por evento.

"Como estou dividido entre cripto e mercados de previsão?"

Claude chama get_allocations({ by: "asset_class" }) e retorna um resumo percentual: "97,5% cripto (US$ 35.000), 2,5% previsão (US$ 1.000)."

"Atualize meus dados e mostre as participações mais recentes."

Claude chama refresh_data({}) e depois get_holdings({}) — o cache é invalidado, dados novos são buscados de todas as APIs upstream em paralelo, e o Claude renderiza o novo estado.

"Me dê um painel completo do portfólio."

Claude chama várias ferramentas em paralelo (get_holdings, get_allocations, get_pnl, get_polymarket_positions) e sintetiza um painel de múltiplas seções. A deduplicação de Promises em andamento do orquestrador garante que cada conector seja acessado no máximo uma vez, mesmo com um fan-out amplo.

Desenvolvimento

Compilar a partir do código-fonte usa Bun 1.3+. Usuários finais não precisam disso — veja Início rápido.

git clone https://github.com/tamasPetki/HeadlessTracker.git
cd headless-tracker
bun install
bun test                              # 377 tests, ~5s
bun run typecheck                     # bun --bun tsc --noEmit
bun run build:apps                    # bundle the dashboard MCP App into dist/mcp-apps/
bun run build                         # build the Node-runnable dist/ (what npm ships)
bun run start                         # start MCP server on stdio (debug only)
bun run setup bybit                   # interactive credential setup

Para adicionar um conector, siga o padrão existente em src/connectors/. A interface Connector impõe tratamento uniforme de erros Result<T> em todas as integrações — não há caminho de lançamento de exceções para falhas esperadas (auth, limite de taxa, rede).

FAQ

Minhas chaves de API serão enviadas para algum lugar? Não. Elas são armazenadas no keychain do seu sistema operacional e só são enviadas para a API upstream correspondente (API da Bybit para chaves da Bybit, API da Etherscan para chaves da Etherscan). O servidor MCP roda inteiramente na sua máquina.

A Polymarket tem minhas posições, mas o Claude não consegue vê-las. Certifique-se de ter usado seu endereço de carteira proxy da Polymarket, não seu endereço MetaMask. Encontre-o na interface da Polymarket em Configurações → Carteira. Execute novamente setup polymarket se você usou o endereço errado.

A Bybit retorna auth_failed. Verifique se a chave de API tem permissões de Leitura de Carteira + Leitura de Negociação (SEM necessidade de Saque). Se você definiu uma lista de permissões de IP na chave, certifique-se de que o IP público atual da sua máquina esteja nela.

A Etherscan retorna rate_limited. O plano gratuito é 5 chamadas/segundo, 100 mil/dia. Cada atualização do MetaMask custa (1 + N tokens) chamadas por rede. Se você tem 4 redes × 7 tokens comuns, são 32 chamadas por atualização. Distribua suas solicitações de atualização; o TTL do cache (60s para MetaMask) existe por um motivo.

Posso usar isso sem o Claude Desktop? Sim — qualquer host compatível com MCP funciona (Claude Code, Cursor, Codex, ZED, ChatGPT quando o suporte a MCP deles estabilizar). Configure da mesma forma; apenas mude qual arquivo de configuração do cliente você edita. Também há uma CLI (headless-tracker show holdings/pnl/transactions) para consultas no terminal que não precisam de um host de IA.

O P&L realizado parece errado. Para a Polymarket, o get_pnl padrão retorna realizedPnl: null porque o campo cashPnl do conector mistura realizado + não realizado. Passe include_history=true (ou --include-history=true pela CLI) para obter o número honesto calculado via FIFO sobre seu histórico de /trades. Para MetaMask, tokens transferidos on-chain não têm base de custo conhecida — include_history=true os reporta como unknownSalesCount em vez de inventar US$ 0.

Uma conta MetaMask pode rastrear várias carteiras? Sim. A v0.8 adicionou addresses[] às credenciais do MetaMask. A CLI de configuração ainda pede uma carteira (compatibilidade reversa), mas o conector aceita uma lista. Edite a entrada do vault diretamente para adicionar mais endereços à mesma conta, compartilhando a mesma chave Etherscan + seleção de rede. Um comando CLI wallet add está na lista da v0.9 se houver demanda.

Isso suporta [minha exchange / rede / mercado favorito]? Ainda não. Abra uma issue ou PR. A interface Connector está aberta para extensão e os 3 conectores existentes são implementações de referência totalizando ~600 linhas.

E o histórico de transações da Polymarket? Suportado desde a v0.7.1: get_transactions retorna negociações BUY/SELL da API pública de dados no endpoint /trades?user=PROXY, até ~1000 das mais recentes. A API de dados ignora parâmetros de consulta com limite de tempo, então o filtro since é aplicado no lado do cliente; a paginação termina cedo quando uma página cai antes do corte.

Por que não há interface? Claude Desktop, ChatGPT e Cursor geram painéis mais ricos sob demanda do que eu enviaria na v1. Construir uma interface duplica o trabalho que o host de IA já faz melhor. Se você quer uma interface web hospedada, veja bulltrapp.com.

Relacionados

bulltrapp.com — um rastreador de portfólio web hospedado pelo mesmo mantenedor. Mesmo espaço de problema, superfície diferente. Use um ou ambos.

Licença

MIT