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.

⚡ Experimenta já, sem chave

Três endpoints respondem sem conta nem chave. Cola isto num terminal e vês a capitalização global e a dominância do BTC em JSON.

curl -s https://chainfolioai.com/api/v1/global

/api/v1/global · /api/v1/tax-countries · /api/v1

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",
  "accounts": [
    { "accountId": "a_…", "name": "Conta 1", "wallets": { "eth": [{ "address": "wallet_8815840fa2", "balance": "1.5", "network": "eth", "label": "Principal" }] } },
    { "accountId": "a_…", "name": "Conta 2", "wallets": { "btc": [{ "address": "wallet_86ef685f59", "balance": "0.2" }] } }
  ],
  "wallets": {
    "eth": [{ "address": "wallet_8815840fa2", "balance": "1.5", "network": "eth", "label": "Principal" }],
    "btc": [{ "address": "wallet_86ef685f59", "balance": "0.2" }]
  },
  "note": "wallets junta todas as contas; accounts separa-as."
}

GET/api/v1/pnl

Evolução do portefólio em euros: total atual e variação a 24 h, 7 d, 30 d e desde o início, sem o capital que entrou ou saiu (fluxoEur e fluxos dizem quanto ficou de fora).

Exemplo

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

Resposta

{
  "currency": "EUR",
  "totalEur": 12450.32,
  "updatedAt": "2026-09-18T06:00:00Z",
  "changes": [
    { "period": "24h", "eur": 120.5, "pct": 0.98, "fromAt": "2026-09-17T06:00:00Z" },
    { "period": "7d", "eur": -310.2, "pct": -2.43, "fromAt": "2026-09-11T06:00:00Z" },
    { "period": "30d", "eur": 890.1, "pct": 7.7, "fromAt": "2026-08-19T06:00:00Z" },
    { "period": "all", "eur": 2450.32, "pct": 24.5, "fromAt": "2026-03-02T06:00:00Z" }
  ],
  "snapshotsUsed": 128
}

GET/api/v1/realized-gains

Mais-valias realizadas (FIFO) em euros, com taxas e gás deduzidos: total, por ativo e por ano.

Parâmetros: year

Exemplo

curl "https://chainfolioai.com/api/v1/realized-gains?year=2026" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{
  "currency": "EUR",
  "method": "FIFO",
  "year": 2026,
  "realizedPnlEur": 1840.55,
  "feesEur": 62.3,
  "byAsset": [{ "asset": "BTC", "realizedPnlEur": 1500.2, "feesEur": 40.1, "quantityOpen": 0.35 }],
  "byYear": [{ "year": 2026, "realizedPnlEur": 1840.55, "sales": 12 }],
  "unmatched": {}
}

GET/api/v1/metrics

Métricas do portefólio a partir do histórico: ROI, CAGR, Sharpe, volatilidade, quedas e VaR 95%.

Exemplo

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

Resposta

{
  "currency": "EUR",
  "metrics": { "days": 210, "roi": 34.2, "cagr": 61.4, "sharpe": 1.12, "maxDrawdown": -22.6, "volatility": 48.1, "var95": -4.8 }
}

GET/api/v1/trades

Transações registadas (compras, vendas e taxas), da mais recente para a mais antiga.

Parâmetros: assetyearlimit

Exemplo

curl "https://chainfolioai.com/api/v1/trades?asset=BTC&year=2026&limit=100" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{
  "total": 84,
  "returned": 100,
  "trades": [{ "date": "2026-06-10", "type": "venda", "asset": "BTC", "quantity": 0.25, "priceEur": 58000, "totalEur": 14500, "feeEur": 12.4 }]
}

GET/api/v1/tax-estimate

Estimativa de imposto sobre mais-valias num país, na moeda desse país, com o método de custo do país e, onde a lei deixa, as perdas de anos anteriores. Opções: alternative (onde estão as moedas, em BR, PT, AR e AT) e marginalRate (onde a taxa depende do rendimento). Não é uma declaração.

Parâmetros: countryyearalternative

Exemplo

curl "https://chainfolioai.com/api/v1/tax-estimate?country=PT&year=2026&alternative=false" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{
  "country": "PT",
  "currency": "EUR",
  "costMethod": "fifo",
  "assumptions": { "alternative": false, "meaning": "Counterparty (exchange) resident in the EU/EEA or a treaty country: 365-day exclusion and swap neutrality apply." },
  "rates": { "short": 0.28, "long": 0, "longTermAfterDays": 365 },
  "sales": 12,
  "totalGain": 4200.5,
  "taxableGain": 3100.0,
  "exemptGain": 1100.5,
  "estimatedTax": 868.0
}

GET/api/v1/tax-countriessem chave

Regimes fiscais publicados por país (taxas, prazo, isenção e lei). Público, sem chave.

Exemplo

curl "https://chainfolioai.com/api/v1/tax-countries"

Resposta

{
  "total": 21,
  "countries": [{ "code": "PT", "currency": "EUR", "shortTermRate": 0.28, "longTermRate": 0, "longTermAfterDays": 365, "law": "Lei n.º 24-D/2022, art. 5.º" }]
}

GET/api/v1/globalsem chave

Capitalização total do mercado, variação 24 h e dominância BTC/ETH. Público, sem chave.

Exemplo

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

Resposta

{ "totalMarketCapUsd": 2.31e12, "marketCapChange24h": -1.4, "btcDominance": 58.2, "ethDominance": 11.7, "source": "coingecko" }

GET/api/v1/derivatives

Derivados de um símbolo: open interest, long/short, funding, CVD, taker, put/call e score.

Parâmetros: symbol

Exemplo

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

Resposta

{ "symbol": "BTC", "score": 54, "rsi": 48.2, "components": { "longShort": 51, "taker": 49, "rsi": 48, "cvd": 65, "funding": 55, "putCall": 57 } }

GET/api/v1/price-on

Preço de fecho de um ativo numa data (UTC).

Parâmetros: symboldate

Exemplo

curl "https://chainfolioai.com/api/v1/price-on?symbol=BTC&date=2026-01-15" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{ "symbol": "BTC", "date": "2026-01-15", "usd": 61234.5 }

GET/api/v1/defi

Posições de lending lidas dos contratos: depositado, emprestado e líquido.

Exemplo

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

Resposta

{
  "currency": "USD",
  "totalNetUsd": 4120.5,
  "totalSuppliedUsd": 9800.0,
  "totalBorrowedUsd": 5679.5,
  "wallets": [{ "label": "Ledger", "netUsd": 4120.5,
    "positions": [{ "protocol": "aave-v3", "chain": "eth", "suppliedUsd": 9800, "borrowedUsd": 5679.5, "netUsd": 4120.5, "healthFactor": 1.72 }] }],
  "walletsRead": 2, "walletsSkipped": 0
}

GET/api/v1/nfts

NFTs das carteiras EVM numa rede. Não entram no total do portefólio.

Parâmetros: chain

Exemplo

curl "https://chainfolioai.com/api/v1/nfts?chain=eth" \
  -H "Authorization: Bearer $CFA_KEY"

Resposta

{ "chain": "eth", "totalNfts": 12, "wallets": [{ "label": "Principal", "total": 12, "returned": 12, "nfts": [{ "name": "…", "collection": "0x…", "tokenId": "1" }] }] }

GET/api/v1/score

Pontuação 0–100 do portefólio, tal como aparece na app.

Exemplo

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

Resposta

{ "score": 72, "max": 100, "asOf": "2026-09-18T06:00:00Z",
  "parts": [{ "id": "diversification", "label": "Diversificação", "points": 22, "max": 30 }] }

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). O Gestor IA na app tem limite próprio: até 150 mensagens/dia (Premium).

Exemplo

curl -X POST https://chainfolioai.com/api/v1/chat \
  -H "Authorization: Bearer $CFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Quanto vale o meu portefólio e como variou esta semana?"}'

Resposta

{ "reply": "Na última fotografia (hoje, 09:12) o portefólio «Principal» valia 12 340 €; em 7 dias variou +2,1 % (+254 €), sem contar o capital que entrou. O BTC está agora a … € (+1,3 % em 24 h). Não é conselho de compra/venda." }

Respostas de erro possíveis: 400 missing_message400 invalid_param405 (GET)429 chat_limit (50/dia, reinicia às 00:00 UTC; Retry-After)503 service_unavailable / ai_unavailable (a mensagem não conta)

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_pnl — a evolução do teu portefólio
get_realized_gains — as tuas mais-valias realizadas (FIFO) (argumento year)
get_metrics — as métricas do teu portefólio
get_trades — as tuas transações (argumento asset)
get_tax_estimate — a estimativa de imposto por país (argumento country)
list_tax_countries — os regimes fiscais publicados
get_global_market — o estado global do mercado
get_derivatives — os derivados de um ativo (argumento symbol)
get_price_on — o preço de um ativo numa data (argumento date)
get_defi_positions — as tuas posições DeFi (depositado, emprestado, líquido)
get_nfts — os teus NFTs (argumento chain)
get_portfolio_score — a pontuação do teu portefólio
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 por dia por conta. O contador recomeça às 00:00 UTC (Retry-After traz os segundos que faltam).
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 →