API & MCP

Acede aos teus dados do ChainFolioAI por API REST ou por MCP (Claude, Cursor…). Funcionalidade do plano Premium — no beta, os testers Premium têm acesso completo.

Autenticação

Gera uma chave em Conta → API & MCP (só aparece uma vez). Envia-a no cabeçalho de cada pedido:

Authorization: Bearer cfa_live_…

Base: https://chainfolioai.com/api/v1
Formato da chave: cfa_live_ + 40 hex · 60/min
Máximo de 5 chaves ativas por conta; revoga as antigas na Conta.
Usa a API a partir do teu backend/CLI: por CORS, chamadas diretas do browser a partir de outro domínio são bloqueadas.

Endpoints REST

Os exemplos assumem a chave na variável de ambiente CFA_KEY.

GET/api/v1sem chave

Índice de descoberta — lista os endpoints. Não exige chave.

Exemplo

curl "https://chainfolioai.com/api/v1"

Resposta

{ "name": "ChainFolioAI API", "version": "v1", "documentation": "https://chainfolioai.com/developers", "endpoints": [ /* … */ ] }

GET/api/v1/portfolio

Último snapshot do portefólio: saldos por rede, CEX, DeFi e ativos manuais (endereços pseudonimizados).

Exemplo

curl "https://chainfolioai.com/api/v1/portfolio" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{
  "updatedAt": "2026-09-05T00:00:00Z",
  "snapshotCount": 365,
  "portfolio": {
    "eth": [{ "address": "wallet_8815840fa2", "balance": "1.5", "network": "eth", "label": "Principal" }],
    "cexUsd": 1000,
    "manualEur": 500
  }
}

GET/api/v1/wallets

Carteiras e endereços ligados à conta (pseudonimizados).

Exemplo

curl "https://chainfolioai.com/api/v1/wallets" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{
  "updatedAt": "2026-09-05T00:00:00Z",
  "wallets": {
    "eth": [{ "address": "wallet_8815840fa2", "balance": "1.5", "network": "eth", "label": "Principal" }],
    "btc": [{ "address": "wallet_86ef685f59", "balance": "0.2" }]
  }
}

GET/api/v1/whales

Movimentos on-chain recentes dos endereços dados. watchlist = array JSON url-encoded de { address, chain, label }. Máx. 10 endereços; chains eth, btc e sol.

Parâmetros: watchlist

Exemplo

curl -G https://chainfolioai.com/api/v1/whales \
  -H "Authorization: Bearer $CFA_KEY" \
  --data-urlencode 'watchlist=[{"address":"0x…","chain":"eth","label":"Baleia"}]'

Resposta

{
  "movements": [{
    "address": "0x…", "label": "Baleia", "chain": "eth",
    "type": "large_transfer",            // large_transfer | accumulation | distribution | new_token
    "description": "1250.00 USDC", "usdValue": 1250, "timestamp": 1769…
  }],
  "scanned": 1,
  "timestamp": 1769…
}

Respostas de erro possíveis: 400 missing_watchlist400 invalid_watchlist400 too_many (>10)400 invalid_address400 invalid_chain

GET/api/v1/market

Top criptoativos por capitalização. limit = 1–250 (por omissão 50).

Parâmetros: limit

Exemplo

curl "https://chainfolioai.com/api/v1/market?limit=5" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{
  "coins": [{ "id": "bitcoin", "rank": 1, "symbol": "BTC", "name": "Bitcoin", "priceUsd": 64000, "marketCap": 1.29e12, "volume24h": 3.1e10, "change24h": -0.2, "change7d": 1.5 }],
  "count": 5, "source": "coingecko", "timestamp": 1769…
}

GET/api/v1/known-whales

Baleias conhecidas pré-carregadas (exchanges, fundos, figuras públicas, governos). Usa os endereços como input do /whales.

Exemplo

curl "https://chainfolioai.com/api/v1/known-whales" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{ "whales": [{ "address": "0x47ac…D503", "label": "Binance Cold Wallet", "chain": "eth" }], "count": 50 }

GET/api/v1/price

Preço, capitalização, volume e variação (24h/7d) de um criptoativo pelo símbolo. 404 se o símbolo não existir.

Parâmetros: symbol

Exemplo

curl "https://chainfolioai.com/api/v1/price?symbol=btc" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{ "symbol": "BTC", "name": "Bitcoin", "priceUsd": 64000, "marketCap": 1.29e12, "volume24h": 3.1e10, "change24h": -0.2, "change7d": 1.5, "rank": 1 }

Respostas de erro possíveis: 404 not_found

GET/api/v1/fear-greed

Índice Fear & Greed — valor atual (0–100) e últimos 8 dias. now pode ser null se a fonte falhar.

Exemplo

curl "https://chainfolioai.com/api/v1/fear-greed" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{ "now": { "value": 29, "classification": "Fear", "timestamp": 1769… }, "history": [ /* últimos 8 dias */ ] }

GET/api/v1/news

Últimas notícias de cripto (CoinDesk, CoinTelegraph). limit = 1–30.

Parâmetros: limit

Exemplo

curl "https://chainfolioai.com/api/v1/news?limit=10" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{ "news": [{ "title": "…", "url": "https://…", "source": "CoinDesk", "publishedAt": "2026-09-05T…" }], "count": 10 }

GET/api/v1/btc-blocks

Blocos Bitcoin recentes (altura, nº de transações, taxa mediana, pool, timestamp) e taxas recomendadas da mempool.

Exemplo

curl "https://chainfolioai.com/api/v1/btc-blocks" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{
  "blocks": [{ "height": 958892, "txCount": 4448, "medianFee": 2, "pool": "Foundry USA", "timestamp": 1769… }],
  "fees": { "fastestFee": 3, "halfHourFee": 2, "hourFee": 2, "economyFee": 1, "minimumFee": 1 },
  "timestamp": 1769…
}

GET/api/v1/fire

Anos até à independência financeira (regra dos 4%). Valores por omissão: 2000 / 500 / 7 / 3 / 30 / 0. Se o retorno real for ≤ 0, yearsToFire vem null com uma note.

Parâmetros: monthlyExpensesmonthlyInvestmentannualReturninflationcurrentAgecurrentPortfolio

Exemplo

curl "https://chainfolioai.com/api/v1/fire?monthlyExpenses=2000&monthlyInvestment=500&annualReturn=7&inflation=3&currentAge=30&currentPortfolio=0" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{ "fireTarget": 600000, "realReturnPct": 4, "yearsToFire": 41, "retirementAge": 71, "retirementYear": 2067 }
// se annualReturn ≤ inflation: { "yearsToFire": null, "note": "…" }

POST/api/v1/chat

Assistente de IA sobre o teu portefólio real. Não dá ordens de compra/venda. message até 1000 caracteres; máx. 50 mensagens/dia por conta (partilhado com o MCP).

Exemplo

curl -X POST https://chainfolioai.com/api/v1/chat \
  -H "Authorization: Bearer $CFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Como está diversificado o meu portefólio?"}'

Resposta

{ "reply": "O teu portefólio está concentrado em… (análise). Não é conselho de compra/venda." }

Respostas de erro possíveis: 400 missing_message405 (GET)429 chat_limit (50/dia)503 ai_unavailable

MCP (Claude, Cursor…)

O servidor MCP vive em https://chainfolioai.com/api/mcp (Streamable HTTP), autenticado pela mesma chave no cabeçalho Authorization. Liga-o como servidor MCP remoto e ganhas estas ferramentas:

get_portfolio — o teu portefólio
get_wallets — as tuas carteiras
get_whale_activity — movimentos de endereços (argumento watchlist)
get_market — top criptoativos (argumento limit)
list_known_whales — baleias conhecidas pré-carregadas
get_asset — preço de um ativo (argumento symbol)
get_fear_greed — índice Fear & Greed
get_news — últimas notícias (argumento limit)
get_btc_blocks — blocos Bitcoin + taxas
get_fire — anos até à independência financeira
ask_ai — pergunta à IA sobre o teu portefólio (máx. 50/dia; no REST o campo chama-se message) (argumento question)

⚠️ No MCP, qualquer falha de autenticação (chave inválida, conta sem Premium ou limite excedido) aparece como 401 — o protocolo não distingue 403/429. Confirma o teu plano e o limite na Conta.

Claude Code / Claude Desktop

claude mcp add --transport http chainfolioai https://chainfolioai.com/api/mcp \
  --header "Authorization: Bearer cfa_live_…"

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "chainfolioai": {
      "url": "https://chainfolioai.com/api/mcp",
      "headers": { "Authorization": "Bearer cfa_live_…" }
    }
  }
}

Erros e limites

Todos os erros devolvem JSON no formato { "error": "code", "message": "…" }

HTTP	error	Quando
400	missing_* / invalid_* / too_many	Parâmetros inválidos (ex.: watchlist mal formada, message em falta).
401	invalid_key	Chave em falta, inválida ou revogada.
403	premium_required	A conta não tem Premium ativo.
404	not_found	Símbolo desconhecido em /price.
405	—	Método errado (ex.: GET em /chat).
429	rate_limited	Mais de 60 pedidos por minuto por chave — respeita o cabeçalho Retry-After (60 s).
429	chat_limit	Mais de 50 mensagens de IA em 24 h por conta (Retry-After: 86400).
503	service_unavailable / ai_unavailable	Serviço ou fornecedor de IA temporariamente indisponível — tenta de novo.

Versão: v1 é estável; alterações incompatíveis só numa futura v2 no caminho. Campos novos podem ser acrescentados sem aviso.

Segurança e privacidade

Os endereços das tuas carteiras nunca saem inteiros em /portfolio e /wallets — são substituídos por um pseudónimo estável, ex.: wallet_8815840fa2. Em /whales e /known-whales os endereços são os que tu envias ou públicos.
Todas as respostas usam Cache-Control: no-store.
As chaves guardam-se como hash; podes revogá-las a qualquer momento na tua conta.
/portfolio e /wallets devolvem os dados do dono da chave — um bot multi-utilizador precisa de uma chave por pessoa.
A IA descreve e analisa; nunca dá instruções de compra ou venda.

Gerir as minhas chaves →