Fee Optimizer MCP

Fee Optimizer MCP

Um servidor MCP (Model Context Protocol) que ajuda agentes de IA a responder perguntas sobre taxas de negociação em exchanges de criptomoedas, buscar links de indicação para descontos em taxas, calcular economias, comparar custo total (taxas + funding + spread/slippage + saque), anualizar o custo total anual com economias de upgrade VIP, inspecionar taxas de funding (médias agregadas ou taxas ao vivo em tempo real), medir custo de execução no order book (cruzamento de spread bid-ask + slippage de profundidade condicionada ao tamanho, baselines agregados ou walks ao vivo no book), comparar custos diretos de on/off-ramp fiduciário (depósitos e saques por cartão / ACH / SEPA / FPS / wire / SWIFT / PIX em diferentes venues, moedas e países de residência), comparar taxas de saque on-chain por ativo e rede entre venues (16 ativos × rotas TRC-20/ERC-20/L2/nativas com flags de carteira suspensa e conversão em USD por preço snapshot), e executar uma análise de persona de trader ancorada em pesquisa que anualiza a pilha completa de custos (taxas + funding + spread + saques + on/off-ramp fiduciário) para sete arquétipos de trader e recomenda a melhor exchange para o perfil do usuário.

Quando um usuário pergunta "qual exchange de criptomoedas tem as menores taxas para um trader de ordens limitadas?", "me dê um link de registro com desconto da Gate.io", "quanto posso economizar em 100k USDT de futuros mantidos por 16 horas?", ou "de onde vêm esses dados de taxas?", o agente pode chamar as ferramentas deste servidor para retornar respostas concretas e com fontes — incluindo um link de indicação com o qual o usuário pode se registrar para receber um desconto nas taxas.

Recursos

Vinte ferramentas somente leitura. Opera via stdio ou HTTP Streamable sem estado (v0.29: servidores isolados por requisição, respostas JSON, sonda /health — pronto para hospedagem remota/em contêiner; v0.32 adiciona endurecimento para hospedagem pública: autenticação por bearer-token opt-in, limite de taxa por IP, logs de acesso JSON estruturados e um Dockerfile de produção). Todas as ferramentas com taxas exigem um código de país para filtragem de conformidade. Cada resultado carrega um carimbo data_as_of, e get_data_sources reporta months_behind/is_stale por arquivo, além de stale_files (v0.33), imposto por um gate offline de consistência npm run audit:data. v0.48 adiciona get_fee_changes (20ª ferramenta) — o feed auditável de mudanças na tabela de taxas (moat de dados): um histórico curado e verificado por anúncios oficiais de mudanças nas taxas VIP, alterações de limites de qualificação, inserções/remoções de degraus, promoções, descontos por token e mudanças no modelo de preços (cada uma com data de vigência, URL de origem e resumo bilíngue), além de snapshots mensais determinísticos da escada de taxas em snapshots/fee_ladders/ que são comparados automaticamente — linhas derivadas de snapshot carregam confidence: "detected" e NUNCA são apresentadas como confirmadas (uma diferença pode ser uma correção de dados); um workflow mensal do GitHub Actions captura o novo snapshot e abre um PR somente de revisão, e um humano verifica contra a página oficial de taxas antes de curar em data/fee_changes.json. O feed curado é distribuído no pacote npm; os snapshots ficam apenas no repositório, e consumidores npm degradam graciosamente (snapshot_coverage.available: false). v0.34 adiciona volume_what_if — uma varredura de sensibilidade what-if por volume: ranking de menor custo entre corretoras e curvas de taxas/custos por corretora em níveis de volume mensal (pontos padrão = a união dos limites VIP de cada corretora), a lista exata de cruzamento de faixas e, com baseVolume, o próximo degrau de cada corretora, o volume extra necessário e o USD/ano economizado no volume atual (degraus com gate de manutenção, como o requisito BNB da Binance spot, sinalizados como blocked_by_holding_gate). v0.35 adiciona compare_countries — uma persona de trader precificada através do stack anual completo em até 12 países em uma única chamada: vencedor por país e escolha realista de todas as pernas, o custo anual extra versus o país mais barato em uma base comparável (um vencedor headline sem trilho não pode fingir um país), uma matriz de disponibilidade corretora×país que distingue bloqueio por conformidade de não suporte do produto (Coinbase somente spot para um trader de futuros), contagens de vitórias por corretora e a diferença mais barata/mais cara. v0.36 adiciona tabelas de matriz prontas para colar — compare_personas, volume_what_if e compare_countries aceitam format: "markdown" | "csv" | "both" e retornam um objeto rendered junto com o JSON inalterado (tableMetric seleciona a fatia: taxa ponderada / taxa anual / faixa para a varredura, símbolos de disponibilidade / custo para países); tabelas markdown escapam pipes e CSV segue RFC 4180 (vírgulas/aspas/novas linhas entre aspas, CRLF) para colagem direta em documentos ou planilhas; chamadas padrão permanecem byte-idênticas. v0.37 adiciona BloFin como a 13ª corretora — uma exchange de derivativos com sede nas Ilhas Cayman/Marshall (~US$ 1,2B/24h de volume perpétuo, sem KYC até saques de 20k USDT/dia): escadas de 6 faixas para spot/futuros (futuros 0,020%/0,060% base → 0%/0,035%, spot 0,10%/0,10% → 0,01%/0,0325%), qualificação OR de três trilhos (volume de futuros 30d / volume spot 30d / ativos da conta — apenas US$ 50k em ativos alcança futuros VIP1), funding de 8h, spread típico de perpétuo de ~3 bps, saques TRC-20 a ~1 USDT/USDC, sem token nativo, sem link de referência, sem trilhos fiduciários diretos e bloqueado em US/CA/CN/SG além do EEA sob MiCA (Alemanha explicitamente modelada). v0.38 adiciona Bitstamp como a 14ª corretora — a corretora mais regulamentada do modelo (fundada em 2011, Luxemburgo, de propriedade da Robinhood; passaporte CASP MiCA da UE, BitLicense NYDFS, FCA do Reino Unido, MAS de Singapura): uma escada spot somente de volume com 11 faixas (0,30%/0,40% de entrada → 0,00%/0,03% acima de US$ 1B de volume em 30d) além de perpétuos regulamentados com margem em USD a uma taxa fixa de −0,005% rebate maker / 0,015% taker com funding peer-to-peer de 8h — os perpétuos são apenas para residentes elegíveis da UE/EEA, modelados com um gate de produto corretora×país (v0.40: uma allowlist positiva da região EEA — todos os 30 estados do EEA roteiam ambos os produtos, qualquer outra residência, incluindo AU/BR/CH, recebe futuros PRODUCT_BLOCKED_IN_COUNTRY enquanto o spot permanece aberto; CN é bloqueada por corretora), trilhos fiduciários diretos profundos (ACH gratuito em ambos os sentidos, SEPA gratuito na entrada / €3 na saída, SWIFT 0,05%/0,1% com mínimos/teto, cartão ~4%) e saques conservadores com peso em ERC-20 (USDT ~20 somente ERC-20 — a rota USDT mais cara modelada). A matemática de funding usa padrões agrupados de médias de longo prazo e pode alternar para taxas ao vivo em tempo real via fundingMode: "live". O custo de execução (spread + slippage) usa padrões agrupados de spreads típicos e pode alternar para caminhadas em livro de ordens em tempo real via spreadMode: "live". v0.39 adiciona get_account_fee_tier — o salto da tabela de taxas pública para a taxa real da conta do chamador: passe uma chave de API somente leitura (Hyperliquid precisa apenas do endereço público 0x da carteira; OKX/KuCoin-Futures aceitam uma passphrase de API) e a ferramenta chama o endpoint autenticado de taxas da corretora via ccxt, retorna o maker/taker real em percentual e a diferença assinada em bps versus a faixa VIP pública agrupada no volume mensal dado (captura deduções BNB no servidor, a janela VIP própria de 30d rolante da corretora, taxas negociadas/promocionais; 13/18 corretoras suportadas — Phemex/BloFin, Finst, Bitpanda e BISON (sem API pública de negociação / conector ccxt), além dos perpétuos das corretoras somente spot (Bitstamp, Bitvavo), retornam um erro tipado de não suportado). As credenciais são apenas por requisição, nunca armazenadas em cache, nunca escritas em logs (linhas de auditoria redigem apiKey/secret/password; strings de erro removem literais de credenciais), e os gates de conformidade de país/produto são executados antes de qualquer chamada autenticada. v0.40 adiciona allowlists positivas de região (regions + product_region_gates em country_restrictions.json) substituindo a chave padrão de lista negativa da v0.38: perpétuos da Bitstamp agora exigem associação à região declarada EEA (todos os 30 estados — UE27 + Islândia/Liechtenstein/Noruega), então residências não-EEA não modeladas, como AU/BR/CH/TR/KR, são corretamente PRODUCT_BLOCKED_IN_COUNTRY em vez de serem silenciosamente superabertas, enquanto cada membro do EEA (FR/NL/ES/IT/…) roteia ambos os produtos; o gate é orientado a dados e reutilizável para futuras corretoras com restrição de região. v0.41 impõe o regime MiCA pós-precipício (a transição do Artigo 143(3) terminou em 2026-07-01, sem extensão) com gates negativos de região (region_blocked + product_region_blocked): para residentes do EEA, Binance, MEXC, Bitget, KuCoin, BingX, Phemex e BloFin são bloqueadas por corretora para todos os produtos (sem autorização CASP utilizável — pedidos retirados/pendentes ou a proibição ativa de início de operações da KuCoin pela FMA), e perpétuos Bybit/Gate são bloqueados por produto aguardando autorização separada de empresa de investimento MiFID II enquanto o spot permanece aberto; o stack do EEA é portanto OKX/Gate/Bybit/Kraken/Coinbase/Bitstamp para spot e apenas OKX (X-Perps), Kraken e Bitstamp para perpétuos, além da Hyperliquid não custodial (sem geo-bloqueio de frontend — mantida com aviso explícito de risco de zona cinzenta). Gates negativos estreitam apenas os resultados do EEA; mercados não-EEA (US/GB/AU/BR/JP/…) são byte-idênticos a antes, incluindo países roteados pela chave padrão aberta. v0.42 adiciona Bitvavo como a 15ª corretora — a maior exchange spot de euro nativa (Amsterdã, fundada em 2018, ~4M+ usuários, aproximadamente metade do volume spot global denominado em EUR; registro CASP MiCA AFM #41000010 com passaporte EEA) — e um novo gate positivo de área de serviço no nível da corretora (region_allowed em country_restrictions.json): Bitvavo atende apenas os 30 estados do EEA, então qualquer outra residência (US/GB/CH/JP/SG/AU/BR/CN/… incluindo países de chave padrão) recebe a corretora filtrada (semântica COUNTRY_BLOCKED), enquanto um acerto na whitelist autoriza a corretora mesmo onde um enum allowed por país desatualizado discorda. Bitvavo é somente spot: uma escada PRO de trilho único com nove degraus baseada em volume EUR de 30d (0,15%/0,25% de entrada → 0,00%/0,02% acima de €25M; sem token, sem trilho de ativos; o spread embutido da UI básica do consumidor não é modelado), o spread mais apertado de livro EUR da UE no modelo em 1,0 bps completo / 0,5 bps cruzando (Kaiko 2026-05 mediu 0,981 bps — melhor de qualquer corretora europeia), SEPA/SEPA Instant gratuito em ambas as pernas em EUR (iDEAL/Bancontact viajam sobre SEPA; limite de saque de €25k/dia) além de um depósito por cartão de ~1% na UE sem saque por cartão, e um saque on-chain dinâmico somente BTC modelado em 0,00005 BTC (sem Lightning; USDT/USDC/ETH/alts aparecem como não suportados). O stack spot do EEA cresce para 8 corretoras; o stack de futuros permanece inalterado (Bitvavo cai em unsupported_product para uma persona de futuros). As entidades separadas Bitvavo UK e Suíça são deliberadamente não modeladas, então GB/CH permanecem fora da whitelist. v0.43 adiciona Finst como a 16ª corretora — a primeira corretora do modelo em vez de uma exchange com livro de ordens (Amsterdã, fundada em 2022 por uma equipe ex-DEGIRO; CASP MiCA AFM #41000015 concedido em 2025-07 com passaporte EEA, ~30 países / 110k+ usuários): um roteador de ordens inteligente (SOR) que agrega liquidez externa e cobra uma taxa fixa de 0,15% em cada compra/venda/troca/auto-investimento — sem divisão maker/taker, sem faixas de volume, sem mínimo, sem markup de spread (modelado como um único degrau de escada independente de volume mais um proxy de spread de coorte de 1,0/0,5 bps). O mesmo gate region_allowed: ["EEA"] no nível da corretora se aplica, trazendo o stack spot do EEA para 9 corretoras; Finst desaparece de todo resultado não-EEA. É somente spot (uma persona de futuros vê unsupported_product dentro do EEA, blocked fora), oferece SEPA/SEPA Instant/iDEAL/Bancontact gratuitos em ambas as pernas somente em EUR — sem trilho de cartão (consultas explícitas de cartão retornam available: false), sem PayPal, sem USD/GBP — e modela saques de cripto como taxa de rede dinâmica ao custo mais uma cobrança fixa de terceiros de €2,50: como o schema não tem campo de sobretaxa, BTC é precificado tudo incluído em 0,000085 BTC (≈$6,57) com a composição em duas partes divulgada na nota da rota, enquanto os outros 400+ mercados aparecem como não suportados. Não há programa de referência e nenhuma API pública de negociação, então get_account_fee_tier não é suportado (cobertura ao vivo permanece em 13 corretoras). v0.44 adiciona Bitpanda como a 17ª corretora e a primeira corretora precificada por spread do modelo (Viena, fundada em 2014, 7,4M+ usuários; autorização CASP MiCA BaFin 2025-01-27 com passaporte EEA30 + licença austríaca FMA + entidade Bitpanda Broker UK registrada na FCA do Reino Unido): o app do consumidor cotiza um preço tudo incluído com a taxa embutida como markup e zero comissão separada — um novo pricing_model: "spread" (order_book | flat | spread) sem divisão maker/taker e sem escada de volume — 1,49% por lado headline para a maioria dos ativos, 0,99% por lado para BTC e principais pares de stablecoin via overrides no nível do par, e 2,49% para small caps abaixo de €100M (a faixa de índice cripto de 1,99% e a margem de 10x do app do consumidor não são modeladas; futuros não suportados). Como o markup embutido é o custo do spread, a linha de base de spread típico agrupado da Bitpanda é fixada em 0 bps para que o prêmio e uma linha de spread nunca sejam cobrados em dobro, e um novo bloco de evidência execution_quality divulga a lacuna que a corretora esconde: round trip anunciado de 2,98% vs medição de round trip de €100 com dinheiro real da TUM de 6,23% — 4,25 pontos percentuais de markup oculto (out–nov 2025, replicado independentemente pela Frankfurt School of Finance em 2026-03 com 432 round trips em 9 plataformas) — a maior lacuna de custo de varejo europeu medida na pesquisa. Bitpanda atende apenas os 30 estados do EEA mais a Grã-Bretanha via region_allowed: ["EEA","GB"] (GB adicionada como uma chave de região de membro único — o mesmo mecanismo de gate positivo, sem mudança de código de gate), trazendo o stack spot do EEA para 10 corretoras; uma persona de futuros vê unsupported_product dentro da área de serviço e blocked fora (US/CA/CN/CH/…); a separada Bitpanda Fusion exchange pro (precificação de liquidez agregada de 0,02–0,25%) e ações/metais/ETFs são deliberadamente não modelados e divulgados via notas. Todos os trilhos fiduciários do app do consumidor são gratuitos desde 2026 — SEPA/SEPA Instant, cartões Visa/Mastercard (somente depósito, sem perna de saque por cartão), PayPal e Apple/Google Pay em EUR, além de FPS e cartões em GBP; não há USD route (consultas em USD mantêm a linha da exchange com available:false). Saques de criptomoedas repassam a taxa dinâmica de rede sem margem: BTC 0.00000598 (~$0.46) e ETH 0.0006 (~$1.51) no snapshot datado. Não há link de referência e o ccxt não inclui uma classe bitpanda, então get_account_fee_tier retorna ACCOUNT_FEES_UNSUPPORTED (cobertura ao vivo permanece em 13 de 17 exchanges). v0.45 adiciona BISON como a 18ª exchange e o segundo corretor com spread precificado do modelo (Boerse Stuttgart Group, Stuttgart, lançado em 2019, 1M+ usuários ativos; EUWAX AG cotiza como contraparte principal por aproximadamente 10 segundos sem livro de ordens; Boerse Stuttgart Digital Custody — anteriormente blocknox — detinha a primeira licença de custódia/transferência de cripto MiCA do BaFin desde 2025-01-17, com passaporte para 29 estados, e o serviço de exchange de cripto da EUWAX AG é autorizado pela MiCA desde 2025-04-01): o aplicativo do consumidor cotiza um preço único all-in, novamente modelado com pricing_model: "spread" (sem maker/taker, sem escada de volume) — 1,25% por lado para BTC e ETH via overrides por par, 1,75% por lado para todas as outras criptomoedas (ida e volta ≈2,5% vs ≈3,5%), subcotando o Bitpanda em 1,49% no título. A linha de base do spread é fixada em 0 bps (mesma proteção anti-dupla contagem), e o bloco de evidências execution_quality conta a história oposta à do Bitpanda: ida e volta anunciada de 2,5% vs medição real de €100 da TUM de 2,58% — apenas ~0,08 pontos percentuais não divulgados (out–nov 2025, seis plataformas licenciadas pela MiCA) — de longe o alinhamento publicado-vs-medido mais próximo do campo testado (Bitvavo em seguida; Bitpanda 6,23%, Coinbase 7,49%), tornando a BISON o benchmark europeu de transparência. A BISON atende os 30 estados do EEE mais a Suíça via region_allowed: ["EEA","CH"] — CH é uma nova chave de região de membro único (DE/AT/CH ativamente comercializados, outros residentes do EEE atendidos sob liberdades passivas) — e é bloqueada para a Grã-Bretanha, exatamente a lacuna complementar ao Bitpanda (EEE+GB, não CH), além de US/CA/JP/SG/AU/BR/CN/KR; a pilha spot do EEE torna-se 11 exchanges, a pilha CH 15, e a BISON nunca aparece em resultados GB/US/JP. É somente spot (futures: [] → unsupported_product em serviço, blocked fora; não existem futuros ou margem). Saques de criptomoedas são oficialmente gratuitos — sem linha de taxa de rede, custos on-chain absorvidos pela EUWAX/grupo (diferente do repasse do Bitpanda) — modelados em BTC 0 e ETH 0, o que torna a BISON o saque modelado globalmente mais barato para ambos os ativos (mín. 0,001 BTC, sem Lightning/Taproot bc1p; somente mainnet Ethereum, mín. 0,01 ETH, sem pagamentos L2). Fiat é somente EUR: SEPA/SEPA Instant gratuito em ambas as pernas, incluindo usuários suíços financiando em EUR, além de 2,49% somente depósito via cartão/Apple Pay/Google Pay (taxa de parceiro Solaris SE/Deutsche Bank, sem saque em cartão; sem trilho GBP/USD/CHF — consultas em USD mantêm a linha indisponível). A taxa de €1,99 para ordens de ações/ETFs alemães e a comissão de 27% na recompensa de staking não são taxas de negociação de cripto e não são modeladas. O programa de convite a amigos não carrega URL de afiliado (NO_REFERRAL_LINK) e o ccxt 4.5.78 não inclui uma classe bison/euwax, então get_account_fee_tier retorna ACCOUNT_FEES_UNSUPPORTED (cobertura ao vivo permanece em 13 de 18 exchanges). v0.46 adiciona get_stablecoin_access (18ª ferramenta) — inteligência de acesso regional a stablecoins MiCA: Tether nunca solicitou autorização EMT MiCA, e após o penhasco transitório CASP em 2026-07-01 (ESMA75-113276571-1679, confirmado não prorrogável), a negociação de USDT em exchanges está indisponível em todos os 30 estados do EEE — o modelo carrega a linha do tempo completa de delisting por exchange (Coinbase 2024-12, a onda Binance/Kraken/OKX/Gate/Bitstamp/Bitpanda/Bitvavo até 2025-03, as datas de parada de compra/conversão residual da Revolut em 2026) além do status venue_blocked para as seis exchanges bloqueadas no EEE e never_offered para BISON/Finst/Hyperliquid; o relatório distingue a proibição de negociação no lado da exchange dos direitos pessoais — manter, custodiar e retirar on-chain para autocustódia permanecem legais (Convert/custódia majoritariamente mantidos, DEXs fora do perímetro; Suíça e Grã-Bretanha deliberadamente não estão na região do EEE), nomeia as seis alternativas autorizadas pela MiCA modeladas (USDC/EURC — Circle France EMI, EURI — Banking Circle, EURCV — SocGen FORGE, USDQ/EURQ — Quantoz) com detalhes de emissor/autorização, e renderiza conselhos bilíngues. O mesmo aviso STABLECOIN_UNAVAILABLE_IN_REGION é auto-injetado em todo fluxo do EEE com cotação USDT — comparações de taxas (linhas stablecoin_access por exchange), economia/custo total/custo anual/recomendação (stablecoin_warning de nível superior em contexto de negociação), saques (contexto de autocustódia/saque), custo de execução e análise de persona (5 de 7 personas retiram USDT habitualmente) — para que um agente nunca possa recomendar a um residente da UE negociar USDT em uma exchange sem que a restrição apareça. v0.47 adiciona compare_interface_costs (19ª ferramenta) — modelagem de custo de interface dupla consumidor vs PRO: a mesma conta frequentemente opera uma interface de livro de ordens barata (Kraken Pro, Coinbase Advanced, Bitvavo trade) e um aplicativo de consumidor caro cujo spread está embutido na cotação — precificado contra o estudo real de ida e volta de €100 da TUM (2025-10..11, seis plataformas da UE licenciadas pela MiCA; replicado independentemente pela Frankfurt School em 2026-03 com 432 idas e voltas em 9 plataformas): idas e voltas de varejo variam 13x — Bitvavo 0,58% (repasse, benchmark de transparência) < BISON 2,58% < app Kraken 5,81% (3,81pp ocultos) < Bitpanda 6,23% (4,25pp ocultos) < Coinbase Simple 7,49% (4,51pp ocultos, pior — a taxa fixa de $2,99 domina pequenas compras DCA e até ordens LIMIT simples carregam taxa de execução de 1%); linhas por exchange dão o nome do produto de consumidor e o modelo de taxa, um custo all-in modelado de uma via, a ida e volta medida, a margem oculta em pp, a base maker/taker PRO e a lacuna em pp, e com monthly_volume_usd o excesso anualizado de permanecer no app (Coinbase a $1k/mês ≈ $168/ano), além de ressalvas de assinatura (Kraken+ $4,99/10k de isenção, Coinbase One) e o fato de que volume no app não gera crédito de nível PRO; Bitpanda/BISON são somente corretor (o prêmio É a taxa — sem interface PRO para mudar), Bitstamp Basic é sinalizado como não verificado, restrições de residência se aplicam, e a mesma lacuna auto-injeta como dicas consumer_interface + avisos CONSUMER_INTERFACE_MORE_EXPENSIVE nas ferramentas de taxa/economia/custo total/recomendação. v0.30/v0.31 adicionam saída narrativa bilíngue — as quinze ferramentas com narrativa aceitam language: "en" | "zh" e localizam todas as strings de conselhos/avisos/tradeoffs/razões/aviso_de_nível (números, nomes de campos e códigos de erro permanecem inalterados); v0.31 também corrige o aviso de nível BNB retido, que anteriormente renderizava "holding at least undefined BNB".

Ferramenta	Gatilho (EN / 中文)	Retorno
compare_exchange_fees	"which exchange has the lowest fees" / "交易所手续费对比"	Exchanges ordenados pela taxa efetiva ponderada, divisão maker/taker, nível VIP, token + descontos de indicação
get_referral_link	"give me a Binance referral link" / "币安优惠注册链接"	URL de indicação + % de desconto + observações
calculate_savings	"how much will I save on 100k USDT futures" / "10万U能省多少"	Taxa original, taxa após indicação, taxa após token, taxa final, economia, custo de funding opcional
compare_total_cost	"true cost including funding and withdrawal" / "真实总成本对比"	Taxa de negociação + custo de funding + taxa de saque por exchange, classificados; v0.26 opcionalmente incorpora taxas anuais diretas de depósito/saque fiduciário (fiatDepositAmountUsd/fiatDepositsPerYear + equivalentes de saque) em total_cost, com flags fiat_deposit_available/fiat_cashout_available para que uma plataforma sem via direta seja marcada e a etapa excluída, nunca precificada como zero
recommend_exchange	"which exchange should I use" / "我该选哪个交易所"	Melhor escolha pontuada (0-100) com motivos, tradeoffs, conselhos e alternativas classificadas; v0.27 incorpora o hábito direto de depósito/saque fiduciário do usuário na pontuação (peso 0,2–0,5 orientado por dispersão), marca plataformas sem via com tradeoff explícito e classifica um on-ramper pequeno de cartão/SEPA por vias fiduciárias em vez de apenas taxas de negociação
calculate_annual_cost	"what does trading cost me per year" / "一年手续费多少，升VIP能省多少"	Taxa de negociação anualizada + funding + saques (+ etapas anuais opcionais de depósito/saque fiduciário v0.26 em annual_total_cost), além do caminho de qualificação para o próximo nível VIP e economia anual
get_data_sources	"where does the data come from" / "数据哪来的，多久更新"	Datas de last_verified por arquivo e URLs de origem (páginas oficiais de taxas das exchanges) + ressalvas
get_funding_rates	"current funding rate on BTC perps" / "现在各所资金费率多少"	Taxa de funding por exchange + intervalo para um par perpétuo (padrão BTC/USDT): médias agregadas ou taxas ao vivo em tempo real com fallback por plataforma
get_execution_cost	"spread and slippage on a 50k market order" / "点差滑点多少、大单冲击成本"	Custo de execução unilateral por exchange em bps + USD para um tamanho de ordem: spread total, cruzamento de meio spread, slippage por profundidade, níveis consumidos, status de preenchimento — baselines agregados ou varreduras ao vivo do top-100 do livro
get_fiat_cost	"cheapest way to deposit euros / cash out to bank" / "入金出金手续费、SEPA/ACH/电汇/PIX 哪个便宜"	Cotações diretas de depósito ou saque fiduciário por exchange para um valor: taxa (pct + fixa com mín/máx), equivalente em USD, % efetiva, valor líquido, ETA, via mais barata por plataforma, melhor escolha geral e economia vs pior — cartão / ACH / SEPA / FPS / wire / SWIFT / PIX em USD/EUR/GBP/BRL com filtro de via por residência
get_withdrawal_fees	"cheapest network to withdraw USDT / ETH L2 提币费对比" / "各所提币手续费、TRC20/ERC20/ Layer2 哪个便宜、哪条链暂停了"	Cotações de saque por exchange para um ativo (e rede opcional): taxa em unidade nativa de cada rota + taxa convertida em USD com flag available (carteiras suspensas sempre exibidas, nunca ocultas), rota aberta mais barata por plataforma, best geral, economia vs pior, avisos — 16 ativos em TRC-20/ERC-20/BEP20/Arbitrum/Optimism/Base/Polygon/Avalanche C/Solana/TON/AssetHub e cadeias nativas; totalmente offline
analyze_persona	"which exchange fits a small buyer / scalper / HODLer" / "我这种情况哪个交易所划算、定投囤币/波段/高频场景推荐"	Sete personas de trader ancoradas em pesquisa (comprador casual, acumulador HODL, spot ativo, swing futures, day scalper, VIP/institucional, nativo de DEX): ranking anual all-in sobre a PILHA COMPLETA de custos — taxas de negociação + funding + spread + saques + entrada/saída fiduciária — com mix de custo por componente, líderes por componente, escolha best_complete (plataforma mais barata com cada etapa da persona precificada; vencedores de manchete sem vias são sinalizados, nunca silenciosamente $0), avisos e conselhos acionáveis; v0.25 vincula analyze_token_discount — quando executado com useToken=false (o padrão), as 3 plataformas mais bem classificadas recebem cada uma um token_discount_hint (token, % de desconto, economia anual, meses de retorno, custo de manutenção, fixo-vs-escalonado) além de um array consolidado token_discount_hints e conselhos concretos, para que uma única chamada responda tanto "qual exchange combina comigo" quanto "vale a pena manter o token dela"; todos os predefinidos são substituíveis
analyze_token_discount	"is holding BNB/GT/KCS for fee discounts worth it" / "持有平台币划算吗、折扣多久回本、币价跌多少不亏"	Retorno do desconto de taxa com token nativo: taxa anual SEM o token (nível de saldo zero, sem alternância) vs. COM ele (dedução fixa BNB/MX/BGB/KCS, escada de nível de manutenção GT/MX/HYPE, maker-para-zero em futuros Gate, elevação de nível GT/KCS/BNB), economia anual em USD, custo de oportunidade em USD do saldo de token bloqueado, retorno em meses e queda máxima de preço do token em um ano que a economia pode absorver; omita tokenBalance para obter todos os níveis alcançáveis classificados por retorno
compare_personas	"which exchange for EVERY kind of trader" / "全部画像对比、什么人用什么所、决策矩阵、最全能的交易所" (v0.28)	Uma chamada executa todas as sete personas (ou um subconjunto) para um país através da pilha anual completa all-in e retorna uma matriz de decisão: vencedor de manchete por persona + escolha realista best_complete, grade persona×plataforma annual_all_in (primeiro mais barato, flags de via/rota por célula), venue_wins entre personas e most_versatile — ex.: no JP, Hyperliquid lidera em manchete para 3 personas, mas vence zero escolhas realistas (sem vias fiduciárias/saque), enquanto OKX é o vencedor mais versátil em todas as etapas
volume_what_if	"how do fees change if my volume grows / how much more trading to hit the next VIP tier" / "月交易量不同手续费差多少、再刷多少量升档省钱、各所档位跳变点、费率随成交量曲线" (v0.34)	Varredura what-if de volume para spot/futures em todas as plataformas permitidas: ranking mais barato entre plataformas por ponto de volume (nível + taxa ponderada + taxa de negociação anual), curvas de varredura por plataforma com marcadores tier_crossed e lista plana tier_crossings; com baseVolume, next_tier por plataforma fornece o limite exato, volume mensal extra e economia em USD/ano no volume atual — blocked_by_holding_gate: true marca degraus que apenas volume não alcança (ex.: porta AND de spot BNB na Binance). Pontos de varredura padrão são a união dos limites VIP de todas as plataformas (amostrados além de 16 com aviso); passe volumes explícito para pontos personalizados
compare_countries	"same profile across countries / I'm moving countries, what changes / which venues are blocked here" / "同样的习惯在哪个国家最便宜、搬家换居住地、各国有什么交易所、哪些所在我国不能用、国家差异矩阵" (v0.35)	Executa uma persona (padrão active_spot_trader; qualquer uma das 7) através da pilha anual completa em vários países (padrão US/GB/DE/JP/SG/BR/CN, até 12): winner de manchete por linha além de best_complete realista, comparison_annual_all_in/extra_vs_cheapest_country_* em base comparável de todas as etapas (Hyperliquid pode liderar em manchete para um comprador de cartão, mas ser excluída da matemática do país por não ter vias fiduciárias), blocked_venues vs unsupported_product_venues (Coinbase para futuros), matriz completa de plataforma×país venue_availability, winner_venue_counts, cheapest_country/costliest_country/spread_usd e conselhos bilíngues — ex.: o mesmo pequeno comprador de cartão paga ~$125/ano nos EUA vs ~$73 na Alemanha (vias baratas de SEPA/cartão)
get_account_fee_tier	"what is MY actual fee / my real VIP maker-taker / check my account fee with a read-only API key" / "我的实际费率、账户真实VIP档位、API查我的手续费、只读密钥查费率" (v0.39)	Maker/taker real autenticado da conta via chave somente leitura + diferença assinada em bps vs o nível do cronograma público no volume informado; 13/18 plataformas (Phemex/BloFin sem suporte do ccxt, Finst, Bitpanda e Bison sem API/conector público; Bitstamp/Bitvavo somente spot, então perpétuos sem suporte); chaves nunca armazenadas em cache ou registradas; gates de conformidade primeiro; códigos de erro de autenticação/rede tipados
get_stablecoin_access	"can I still trade/withdraw USDT in the EU / is USDT delisted here / MiCA stablecoin alternatives" / "USDT在欧盟还能用吗、泰达币下架、欧洲稳定币、USDC/EURC合规稳定币" (v0.46)	Acesso regional MiCA para uma stablecoin (padrão USDT; também USDC/EURC/EURI/EURCV/USDQ/EURQ): emissor + autorização EMT MiCA, restrição regional de negociação na plataforma com data limite (EEA30 pós-2026-07-01), direitos de custódia/saque/autocustódia, status por plataforma (removida + data / nunca_oferecida / plataforma_bloqueada, escopo eea/global, disponibilidade no país consultado), alternativas em conformidade e conselhos bilíngues; o mesmo aviso é injetado automaticamente nas ferramentas de taxa, saque, custo de execução e persona para solicitações USDT/EEA
compare_interface_costs	"why is the Kraken/Coinbase app so expensive / hidden spread in Instant Buy or Simple" / "为什么App买币这么贵、App隐藏点差、两套价格、简单买卖手续费、TUM实测" (v0.47)	Por plataforma: nome do produto de consumo + modelo de taxa, custo all-in unilateral modelado, ida-e-volta medido por TUM, margem oculta em pp, base maker/taker do PRO e diferença em pp, e com monthly_volume_usd o excesso anualizado do app de consumo vs PRO (ex.: Coinbase $1k/mês ≈ $168/ano); ressalvas de assinatura (Kraken+/Coinbase One), nota de sem crédito de nível PRO, restrição por residência; Bitvavo aparece como referência de transparência de repasse de 0,58%
get_fee_changes	"did any exchange change its fees lately / fee change history / 哪家所最近调过手续费、费率变更历史、怎么监控费率调整" (v0.48)	Feed auditável de mudanças no cronograma de taxas: registros curados de alta/média confiança verificados contra anúncios oficiais (data, URL de origem, resumo bilíngue, antes/depois) mesclados com linhas detected derivadas automaticamente de diffs mensais de snapshots de escada (claramente rotuladas como não verificadas); filtros exchange/product/since_month/limit, conselhos bilíngues, além de snapshot_coverage (snapshots somente no repositório; consumidores npm veem available: false)
Exchanges suportados: Binance, OKX, Gate.io, Bybit, MEXC, Bitget, KuCoin, Kraken (spot + futuros, tabelas completas de níveis VIP; MEXC opera com um nível Standard fixo; Kraken opera com um único cronograma unificado de 17 níveis em ambos os produtos), Coinbase (somente spot no Advanced Trade, níveis apenas por volume), Hyperliquid (v0.20, a primeira corretora DEX: livro de ordens on-chain na L1, níveis de volume rotativo de 14 dias, funding por hora, descontos de taxas com HYPE em staking, sem KYC), BingX (v0.21: escadas do VIP Club com um nível Elite somente por volume, uma trilha de qualificação por volume OU ativos e funding de 8h), e Phemex (v0.24: sediada em Singapura, time ex-Morgan Stanley, as menores taxas maker do setor — 0,01% spot/futuros no nível Standard, escadas VIP somente por volume de 30 dias, funding de 8h, desconto fixo de 20% na taxa com o token PT em spot+futuros), e BloFin (v0.37: corretora de derivativos nas Ilhas Cayman/Ilhas Marshall ativa desde 2023, ~US$ 1,2 bi/24h em volume de perpétuos — escadas de 6 níveis com futuros 0,020%/0,060% base até 0%/0,035% no VIP5, qualificação OR de três trilhas via volume de 30d/volume spot/ativos da conta (US$ 50 mil em ativos sozinhos alcançam o VIP1 de futuros), funding de 8h, spread típico de perpétuos de ~3 bps, sem token nativo, sem rampas fiduciárias diretas; bloqueada para US/CA/CN/SG e EEE sob a MiCA), e Bitstamp (v0.38: fundada em Luxemburgo (2011), de propriedade da Robinhood, a corretora mais fortemente regulamentada — MiCA CASP / NYDFS BitLicense / UK FCA / SG MAS; escada spot de 11 níveis somente por volume de 0,30%/0,40% → 0%/0,03% a US$ 1 bi; perpétuos em USD regulamentados somente para EEE30 com taxa fixa de reembolso maker de −0,005% / taker de 0,015% com funding P2P de 8h, controlados por país×produto via uma lista de permissão regional positiva (v0.40); ACH gratuito nos EUA, SEPA gratuito na entrada / €3 na saída, SWIFT 0,05%/0,1%, cartão ~4%; saques com forte presença de ERC-20 — USDT ~20 somente ERC-20, USDC também em Solana/L2; sem token nativo), e Bitvavo (v0.42: Amsterdã (2018), a maior corretora europeia nativa de euro spot — AFM MiCA CASP #41000010 com passaporte EEE, ~4M+ de usuários e aproximadamente metade do volume global spot denominado em EUR; escada PRO spot de nove degraus em trilha única de volume EUR de 30d de 0,15%/0,25% → 0%/0,02% acima de €25M, sem trilha de token/ativos; o spread mais apertado do modelo no livro EUR da UE a 1,0 bps (Kaiko 2026-05); SEPA/SEPA Instant grátis em ambas as pernas (iDEAL/Bancontact) + depósito somente por cartão na UE ~1%; saque dinâmico somente BTC a 0,00005; somente spot — sem perpétuos; controlada por uma lista de permissão positiva de área de serviço no nível da corretora (region_allowed: EEA30), então toda residência fora do EEE, incluindo GB/CH (entidades separadas não modeladas), é bloqueada pela corretora), e Finst (v0.43: Amsterdã (2022, time ex-DEGIRO), a primeira corretora/vencedor de ordens (SOR) do modelo em vez de uma exchange com livro de ordens — AFM MiCA CASP #41000015 com passaporte EEE; uma taxa FIXA de 0,15% em cada compra/venda/troca, sem divisão maker/taker, níveis ou markup de spread, modelada como um único degrau de escada independente de volume; SEPA/SEPA Instant/iDEAL/Bancontact grátis em ambas as pernas somente em EUR, sem cartão/PayPal/USD/GBP; saque BTC 0,000085 (taxa de rede dinâmica ≈0,00005 + cobrança fixa de terceiros de €2,50 embutida na taxa nativa), outros ativos não suportados; somente spot; somente EEE via o mesmo gate region_allowed: ["EEA"] — a pilha spot do EEE agora tem 9 corretoras; sem indicação, sem API pública de negociação, então a consulta de taxas da conta não é suportada), e Bitpanda (v0.44: Viena (2014), a primeira corretora com preço por spread do modelo em vez de uma exchange com livro de ordens — BaFin MiCA CASP (2025-01-27) com passaporte EEE30 além das entidades austríacas FMA e UK FCA, 7,4M+ de usuários; o aplicativo de consumo embute sua taxa como um markup de preço tudo-incluído: 1,49%/lado como destaque, 0,99%/lado para BTC e principais pares de stablecoins via overrides de par, 2,49% para small caps abaixo de €100M — sem divisão maker/taker, sem escada de volume, pricing_model: "spread" com a linha de base do spread fixada em 0 bps para evitar dupla contagem, além de evidência execution_quality (viagem de ida e volta anunciada de 2,98% vs. medida com dinheiro real pela TUM de 6,23%, 4,25pp ocultos; replicação da Frankfurt School 2026-03); SEPA/SEPA Instant/cartões somente depósito/PayPal/Apple-Google Pay grátis em EUR e FPS/cartões em GBP desde 2026, sem rota em USD; BTC 0,00000598 (~US$ 0,46) e ETH 0,0006 (~US$ 1,51) com repasse dinâmico de custo de rede; somente spot; área de serviço EEE30+GB via region_allowed: ["EEA","GB"] (chave de região de membro único GB) — a pilha spot do EEE agora tem 10 corretoras e GB está incluída, ao contrário de Bitvavo/Finst; a exchange pro separada Fusion, ações/metais e margem de 10x não são modelados; sem indicação, sem classe ccxt, então a consulta de taxas da conta não é suportada), e BISON (v0.45: Stuttgart (2019), Grupo Boerse Stuttgart — a 18ª corretora do modelo e a segunda corretora com preço por spread — cotações da EUWAX AG como principal (sem livro de ordens, validade de cotação de ~10s); a Boerse Stuttgart Digital Custody deteve a primeira licença de custódia/transferência MiCA da BaFin (2025-01-17) e o serviço de exchange da EUWAX é autorizado pela MiCA desde 2025-04-01, 1M+ de usuários ativos; o aplicativo de consumo embute 1,25%/lado para BTC/ETH via overrides de par e 1,75%/lado para todas as outras moedas (~2,5%/~3,5% de viagem de ida e volta) — sem maker/taker, sem escada, pricing_model: "spread" com a linha de base do spread fixada em 0 bps, além de evidência execution_quality (2,5% anunciados vs. 2,58% medidos com dinheiro real pela TUM, apenas ~0,08pp ocultos — o alinhamento mais próximo entre o publicado e o medido das seis plataformas testadas); SEPA/SEPA Instant GRÁTIS em ambas as pernas somente em EUR, incluindo usuários suíços + depósito somente por cartão/Apple/Google Pay de 2,49%, sem trilha em GBP/USD/CHF; saques on-chain de BTC e ETH oficialmente GRÁTIS com taxa 0 (custos de rede absorvidos pelo grupo; mínimo 0,001 BTC, sem Lightning/Taproot; ETH somente na mainnet, sem L2); somente spot, sem futuros/margem; área de serviço EEE30+CH via region_allowed: ["EEA","CH"] (CH como uma nova chave de região de membro único) — a pilha spot do EEE agora tem 11 corretoras, a pilha CH tem 15, e GB está bloqueada (a lacuna complementar à Bitpanda); ações/ETFs alemães (€1,99/ordem) e a comissão de staking de 27% não são modelados; convide-um-amigo, mas sem URL de afiliado, sem classe ccxt, então a consulta de taxas da conta não é suportada). Links de referência são opcionais por exchange — as ferramentas comparam todas as exchanges com dados de taxas e só anexam referral_url / referral_discount quando um link está configurado (Kraken, Coinbase, Hyperliquid, BingX, Phemex, BloFin, Bitstamp, Bitvavo, Finst, Bitpanda e BISON não têm nenhum).

Entradas do modelo de taxas

• monthlyVolumeUsd / volume — resolve o nível VIP correto por exchange.
• tokenBalance (opcional) — saldo de token nativo, com regras de escada específicas por exchange (verificado nas páginas oficiais de taxas em 2026-09):
  • Binance spot — porta AND: VIP1+ exige o limite de volume e saldo de BNB (VIP1 = $1M + 5 BNB … VIP9 = $4B + 5.500 BNB). Omitir → o nível de volume é cotado com um tier_warning; passar 0 → o nível é rebaixado e precificado corretamente. (Futuros da Binance não têm porta de saldo.)
  • Gate spot + futuros — OR de trilha dupla: o nível VIP é o maior entre o seu degrau de volume de 30 dias e o seu degrau de saldo de GT (VIP1 = $1M ou 1.000 GT … VIP9 = $1B ou 200.000 GT). GT só pode elevar o nível, nunca rebaixar; os resultados incluem uma dica de upgrade next_tier. O saldo de GT também desbloqueia descontos no pagamento de taxas (100/500/2000/20000 GT → 10/20/35/50%).
  • KuCoin spot + futuros — OR de trilha tripla (v0.13): VIP0–VIP12, e o nível é o maior entre o seu degrau de volume spot de 30 dias, o degrau de volume de futuros de 30 dias (os limites de spot/futuros diferem e são aplicados por produto), ou o seu degrau de saldo de KCS (VIP1 = 1.000 KCS … VIP12 = 150.000 KCS). KCS só eleva, nunca rebaixa; os resultados incluem uma dica de upgrade next_tier / requires_kcs. Os símbolos spot da KuCoin são divididos em Classe A (principais de alta liquidez — a escada cotada), Classe B (exatamente 2× Classe A) e Classe C (exatamente 3×); os resultados spot carregam um spot_class_note lembrando o chamador de verificar a classe do par. Nota de conformidade: KuCoin é filtrada para US, CN, HK, SG, TH.
  • Kraken spot + futuros — trilha tripla unificada de 17 níveis (v0.14): desde 2026-07-09, o Kraken Pro aplica um nível (Nível 1–12, depois Pro 1–5) a ambos os produtos, definido pelo maior entre a trilha de volume spot de 30 dias, a trilha de volume de futuros de 30 dias (limites diferentes por produto), ou ativos na plataforma (AOP) em tempo real passados via accountAssetsUsd (Nível 3 = $20k AOP … Nível 9 = $1M … Pro 5 = $100M). Os Níveis 1–2 não têm caminho de ativos — o saldo começa no Nível 3. Spot opera 0,40%/0,80% no Nível 1 até 0%/0,05% no Pro 5; futuros operam 0,02%/0,05% até -0,006%/0,0125%, com rebates negativos de maker a partir do Nível 11. Kraken não tem token nativo (então useToken nunca se aplica) e não tem link de referência. Todo resultado da Kraken carrega exchange_notes com as ressalvas de qualificação (limitação de entrada de volume único, qualificação cruzada de futuros US/CA/NZ, precificação de app de consumo vs Pro). Conformidade: Kraken atende US (spot; perps regulados pela CFTC Kraken/Bitnomial em 47 estados), HK, JP, TH e é bloqueada para CN e SG.
  • Coinbase spot — níveis somente por volume (v0.19): Advanced Trade cotam taxas puras de maker/taker do livro de ordens que são atualizadas a cada hora com base no volume USD rolante de 30 dias em todos os pares (Nível 1 = 0,40%/0,60% … Nível 2 = 0,25%/0,40% em $10k … Nível 9 = 0%/0,04% em $400M). A qualificação é somente por volume — sem trilha de saldo, sem token nativo, então tokenBalance/useToken nunca se aplicam e accountAssetsUsd é ignorado. Coinbase é um local somente spot: é automaticamente excluída de comparações de taxas de futuros e de buscas de funding ao vivo (perps de varejo nano BTC/ETH não são modelados). O custo de execução spot usa uma linha de base típica de spread total de 2,0 bps (modo ao vivo percorre o livro coinbaseexchange); as rotas de retirada cobrem BTC / ETH / USDT (ERC-20, Base, Solana) / USDC (Base grátis, ERC-20) com notas dinâmicas de taxas baseadas em gás. Conformidade: atendido para residentes de US e SG, bloqueado para CN, HK, TH, JP.
  • Hyperliquid spot + futuros — níveis de volume de 14 dias + desconto de HYPE em staking (v0.20): o primeiro local DEX — um livro de ordens L1 totalmente on-chain (HyperCore) com zero gás de negociação, perps com margem em USDC e um livro spot cotado em USDC (depósitos chegam via Circle CCTP, mínimo de 5 USDC). Os níveis são atualizados diariamente em uma janela de volume ponderado rolante de 14 dias (volume spot conta 2× — não a janela de 30 dias que outros locais usam, então o nível real de um trader de ritmo constante pode ficar um degrau abaixo): perps 0,045%/0,015% no Nível 0 até 0,024%/0% no Nível 6 ($7B), spot 0,070%/0,040% até 0,025%/0%; maker é zero simples (não negativo) a partir do Nível 4. A qualificação é somente por volume — manter HYPE nunca qualifica um nível. A escada de HYPE em staking (10/100/1k/10k/100k/500k HYPE → 5/10/15/20/30/40% de desconto em todas as taxas de maker+taker, spot e perps) acumula multiplicativamente com o nível de volume; passar useToken + tokenBalance = o valor em staking (apenas manter HYPE não dá nada). O funding é liquidado a cada hora — o pacote de 0,00125%/1h equivale à mesma média neutra de 0,01%/8h dos locais CEX, e o modo ao vivo é suportado. Retiradas: uma única rota fixa de ~1 USDC para Arbitrum One / 22+ cadeias CCTP (somente USDC — sem rota USDT; depósitos são gratuitos). O spread típico de perp BTC é de 0,8 bps (linha de base incluída; modo ao vivo percorre o livro hyperliquid). Sem KYC, sem trilhos fiduciários, sem link de referência. Conformidade: front-end dos EUA com bloqueio geográfico (lista de restrições dos ToS); acessível a partir de CN, HK, SG, JP, TH.
  • BingX spot + futuros — escadas do VIP Club com um degrau Elite somente por volume (v0.21): escadas de 8 degraus por produto (Regular → Elite → VIP1–5 → Supreme) com limites de volume de 30 dias que diferem entre spot e futuros. Futuros operam 0,020%/0,050% no Regular, 0,018%/0,045% no degrau Elite ($5M, inserido em 2026-06-26), até 0%/0,025% no Supreme ($500M); spot opera 0,10%/0,10% no Regular, 0,05%/0,08% no Elite ($0,5M), até 0,005%/0,02% no Supreme ($15M). A qualificação é o maior de três trilhas — volume spot de 30 dias, volume de futuros de Contrato Padrão de 30 dias, ou ativos de conta do dia anterior via accountAssetsUsd (futuros VIP1 = $50k … VIP5 = $3M; os níveis são atualizados diariamente às 03:00 UTC+8). Os degraus Elite e Supreme são somente por volume — ativos podem elevá-lo a VIP1–VIP5, mas nunca a Elite ou Supreme (uma conta de $10B ainda limita em VIP5). VIP4/VIP5/Supreme adicionalmente exigem que o volume negociado via API seja ≤20% do volume total (o mecanismo assume conformidade). O produto de copy-trading Futuros Padrão somente para fechamento (taxa fixa de 0,045%) não é modelado — as escadas cotam o livro de ordens do Contrato Padrão. Sem token nativo (então useToken nunca se aplica), sem link de referência, sem trilhos fiduciários diretos (somente gateways P2P/terceiros). O funding é liquidado a cada 8h na média neutra padrão de 0,01% (modo ao vivo suportado via classe ccxt bingx); o spread típico de BTC incluído é de 4 bps. As retiradas cobrem BTC / ETH / USDT / USDC em TRC-20/ERC-20/BEP20/Arbitrum/Optimism/Base/Polygon/Solana/TON/Aptos e mais, com rotas pausadas sinalizadas por cadeia (ex.: USDC-TRC20, USDT Avalanche-C/opBNB). Todo resultado da BingX carrega seis exchange_notes (trilhas, degraus somente por volume, regra de proporção de API, exclusão de Futuros Padrão, sem token/referência, verificação de fonte). Conformidade: bloqueado para US, CA, GB, CN, HK, SG e — após o penhasco pós-MiCA (v0.41, aplicação da FMA austríaca ainda apenas "avançada"/não aprovada) — bloqueado por local em todo o EEE; atendido em JP, TH, AU, BR e outros países fora do EEE.
  • BloFin spot + futuros — escadas OR de trilha tripla com 6 níveis (v0.37): BuildLight Future Limited (Ilhas Cayman/Ilhas Marshall), derivativos ativos desde janeiro de 2023, ~$1,2B/24h de volume de perps (CoinGecko), custódia Fireblocks, ISO 27001, prova de reservas mensal 1:1; sem KYC obrigatório (limite de retirada não verificado de 20.000 USDT/dia). Seis níveis por produto qualificam via o maior de três trilhas — volume de futuros de 30 dias, volume spot de 30 dias, ou ativos de conta de snapshot diário via accountAssetsUsd (os níveis são atualizados diariamente das 00:00–12:00 UTC): futuros Regular 0,020%/0,060% (<$10M de volume e <$50k de ativos), VIP1 0,006%/0,050% em $10M ou $50k de ativos (uma trilha de ativos excepcionalmente barata), até VIP5 0%/0,035% em $500M/$3M; spot 0,10%/0,10% → VIP1 0,035%/0,06% em $1M/$50k → VIP5 0,01%/0,0325% em $8M/$3M. VIP4/VIP5 também exigem que ≥80% do volume qualificador seja não-API (presumido satisfeito, ressalva destacada nas notas). O único monthlyVolumeUsd é correspondido aos limites do próprio produto consultado — qualificação cruzada de produtos (volume de futuros elevando o nível spot) não é modelada. Sem token nativo (sem useToken), sem link de referência do operador, sem trilhos fiduciários diretos (somente widgets de terceiros Checkout.com/Simplex/Alchemy). O funding é liquidado a cada 8h (00/08/16 UTC) na média neutra de 0,01%; o spread típico de perp BTC incluído é de 3 bps. As retiradas são repasse dinâmico de custo de rede sem margem da exchange: BTC ~0,0002, USDT/USDC TRC-20 fixo ~1, ETH ERC-20/L2 (Arbitrum/Optimism ~$0,5–2). Conformidade: bloqueado para US, CA, CN, SG e (sem autorização CASP MiCA após o penhasco de avô de 2026-07-01) o EEE — DE é explicitamente modelado como bloqueado; atendido em HK, JP, TH, GB, BR e mais de 150 outros países.
• Bitstamp spot + futuros — escada de 11 níveis somente por volume em spot + perpétuos regulados somente na UE com gate de produto por país (v0.38): fundada em 2011 em Luxemburgo (a exchange mais antiga do modelo), adquirida pela Robinhood em 2025 (~US$ 200 milhões); regulada sob o passaporte MiCA CASP da UE (CSSF Luxemburgo), BitLicense do NYDFS dos EUA + mais de 40 MTLs estaduais, FCA do Reino Unido, MAS de Singapura e registro canadense — a âncora de conformidade do modelo. As taxas spot PRO/API seguem uma única faixa de volume em USD de 30 dias, sem faixa por ativo ou token: 0,30%/0,40% abaixo de US$ 10 mil → 0,20%/0,30% em US$ 10 mil → 0,10%/0,20% em US$ 100 mil → 0,00%/0,03% em ≥US$ 1 bilhão (11 níveis); a interface básica ao consumidor usa preços baseados em spread e não é modelada, assim como o nível promocional gratuito de primeiros US$ 1.000 ou a sub-tabela com metade da taxa para FX/stablecoins/USDT. Futuros perpétuos regulados com margem em USD são um único nível fixo: −0,005% maker (um rebate) / 0,015% taker, funding peer-to-peer a cada 8h (00:00/08:00/16:00 UTC) sem taxa da plataforma (média agregada de 0,01%). Como os perpétuos são oferecidos somente a residentes elegíveis do EEE, a Bitstamp é modelada com um gate por produto respaldado (desde v0.40) por uma allowlist positiva de regiões — product_region_gates.bitstamp.futures = ["EEA"] contra a tabela de associação regions.EEA (os 30 estados do EEE: UE27 + Islândia/Liechtenstein/Noruega). O acesso em nível de venue (spot) é aberto em US, GB, CA, JP, SG, HK, TH, DE e no padrão catch-all, e CN é bloqueado no nível de venue; futures é bloqueado por produto para TODA residência fora do EEE — mercados com chave explícita (US/GB/CA/JP/SG/HK/TH) e países não modelados roteados via default (AU/BR/CH/TR/KR/MX/IN/…) igualmente (as ferramentas de negociação retornam PRODUCT_BLOCKED_IN_COUNTRY, e compare_countries o lista sob unsupported_product, não blocked); todo membro do EEE roteia ambos os produtos. Isso substitui a chave padrão de lista negativa da v0.38, que abria excessivamente os perpétuos para países fora do EEE sem entrada explícita. O gate de produto deliberadamente NÃO é aplicado a get_withdrawal_fees, get_fiat_cost ou get_referral_link — um usuário dos EUA ainda pode usar o spot da Bitstamp, saques e trilhos fiduciários. Fiat direto é profundo: ACH nos EUA grátis em ambas as direções; depósitos SEPA EUR grátis / saques com taxa fixa de €3; SWIFT internacional USD/EUR/GBP 0,05% na entrada (piso de US$ 7,50, teto de US$ 300) / 0,1% na saída (piso de US$ 25); cartões ~4% em USD/EUR/GBP. Saques são conservadores e pesados em ERC-20: BTC 0,0005 (sem Lightning), ETH 0,005 somente ERC-20 (sem L2), USDT fixo de 20 somente em ERC-20 (sem TRC-20/Solana — a rota USDT mais cara do modelo; USDT em si não é negociável na exchange na UE), USDC 4 ERC-20 (além de rotas Solana/Arbitrum/Polygon/Optimism/Avalanche/Stellar não modeladas individualmente). Spread típico agregado de pares principais em spot é de 2 bps, em linha com o Coinbase Advanced. Sem token nativo (sem useToken), sem link de referência.
• Bitvavo spot — escada PRO de nove níveis em volume EUR + allowlist de área de serviço em nível de venue no EEE (v0.42): fundada em 2018 em Amsterdã; a Bitvavo B.V. é registrada na AFM dos Países Baixos sob MiCA como provedora de serviços de criptoativos (#41000010) e tem passaporte em todo o EEE (~4M+ usuários, participação dominante no volume spot denominado em EUR). Diferente de todos os gates anteriores (banimentos por lista negativa region_blocked ou gates de produto em nível product_region_gates), a Bitvavo é modelada com um gate positivo de área de serviço em nível de venue — region_allowed.bitvavo = ["EEA"] contra regions.EEA (30 estados): SOMENTE residentes do EEE podem embarcar no venue, e qualquer outra residência — mercados com chave explícita e países com chave padrão, incluindo GB/CH atendidos na realidade por entidades Bitvavo separadas que deliberadamente não são modeladas — é bloqueada no nível de venue (COUNTRY_BLOCKED); uma correspondência na whitelist também substitui qualquer entrada allowed desatualizada por país. Precedência do gate por venue: banimento region_blocked → blocked por país → correspondência na whitelist region_allowed (autorizar) → ausência na whitelist (negar) → enum allowed por país (vazio = aberto); país ausente permanece seguro por padrão. As taxas são a tabela PRO/API do order book em UMA única faixa de volume EUR de 30 dias (limiares tratados como equivalente em USD): nove níveis 0,15%/0,25% (<€100 mil) → 0,10%/0,20% → 0,08%/0,16% → 0,06%/0,12% → 0,05%/0,10% → 0,04%/0,08% → 0,04%/0,06% → 0,00%/0,05% → 0,00%/0,02% (≥€25M, principais); sem token nativo, sem faixa por ativos, e a interface Basic ao consumidor (preços com spread embutido; um estudo TUM de 2026 mediu markup oculto de ~0,08 pp) não é modelada. A Bitvavo é somente spot — não oferece perpétuos, portanto está ausente de toda busca de futuros/funding e aparece como unsupported_product (não blocked) em compare_countries para uma persona de futuros no EEE; fora do EEE é blocked. Os livros EUR cotam em EUR (não USDT) com o spread típico mais apertado do modelo: 1,0 bps cheio / 0,5 crossing em principais (Kaiko 2026-05 mediu 0,981 bps, o mais apertado de qualquer venue europeu; alts de cauda longa rodam mais largos via multiplicadores por classe de par). Fiat: SEPA/SEPA Instant EUR grátis em ambas as pernas (iDEAL e Bancontact usam SEPA; saque limitado a €25.000/dia), cartões emitidos na UE ~1% no depósito (fontes terceiras variam de 0,5–1,5%, ponto médio modelado) com sem perna de saque por cartão; PayPal (~2%) é notado mas não modelado; sem trilhos USD/GBP. Saques: BTC dinâmico somente com custo de rede, modelado em 0,00005 BTC (sem Lightning; uma cotação atípica de 0,0000063 de um agregador foi descartada) — todo outro ativo (USDT/USDC/ETH/…) retorna supported: false em vez de uma taxa fabricada. A consulta de taxa de conta é suportada no spot via classe ccxt bitvavo.
• Finst spot — corretora SOR com taxa fixa + allowlist de nível de venue no EEE (v0.43): fundada em 2022 em Amsterdã por uma equipe ex-DEGIRO (KvK 85668117); a Finst B.V. detém registro AFM MiCA CASP #41000015 (concedido em 2025-07) com passaporte no EEE e atende ~30 países europeus. A Finst não é um venue de order book: é uma corretora de roteamento inteligente de ordens que agrega liquidez externa (400+ mercados EUR/USDC) e publica uma única taxa fixa de 0,15% em toda compra/venda/troca/auto-investimento — sem distinção maker/taker, sem escada de volume, sem mínimo, e afirma não ter markup de spread. O modelo portanto carrega um único nível independente de volume (tier: "Flat 0.15%", maker = taker = 0,15% em todo volume; a auditoria de escada monotônica passa trivialmente), com um proxy de spread de coorte de 1,0 bps cheio / 0,5 bps crossing (não existe pesquisa de order book para um venue SOR). O acesso usa o mesmo gate positivo de nível de venue que a Bitvavo — region_allowed.finst = ["EEA"] — então somente os 30 estados do EEE precificam o venue (a pilha spot do EEE passa a ser 9: bitstamp, bitvavo, bybit, coinbase, finst, gate, hyperliquid, kraken, okx); qualquer outra residência, incluindo GB/US/CH/JP/AU/BR, vê o venue bloqueado/ausente. A Finst não oferece derivativos — futures: [] significa que nenhum gate regulatório de produto dispara (isVenueUsableFor permanece verdadeiro dentro do EEE, espelhando a semântica de Coinbase/Bitvavo), mas o venue nunca entra em uma pilha de precificação de futuros; compare_countries o lista como unsupported_product para uma persona de futuros no EEE e blocked fora do EEE. Fiat: uma única rota EUR SEPA (SEPA Instant/iDEAL/Bancontact) grátis em ambas as pernas; sem rota de cartão (uma consulta explícita method: "card" retorna o venue com available: false / rotas vazias — ele permanece no array de comparação para países do EEE, mas nunca pode ser best), sem PayPal, sem USD/GBP. Saques: a tabela oficial é uma taxa de rede dinâmica ao custo mais uma taxa fixa de terceiros de €2,50 por saque de cripto; WithdrawalFee não tem campo de sobretaxa e o schema deliberadamente não é estendido, então a rota BTC é modelada tudo incluído como 0,000085 BTC / ≈US$ 6,57 (≈0,00005 BTC ≈US$ 3,86 de componente típico de rede no snapshot de US$ 77.298 + €2,50 ≈US$ 2,72 a 0,92 EUR/USD), com a rota note divulgando ambas as partes; os outros 400+ mercados retornam supported: false. Depósitos são grátis; linhas de produto não modeladas (Bundle 0,10%/mês de gestão, staking com participação de 25–45% nas taxas, janela gratuita de €10 mil/2 semanas para novos clientes) estão fora do escopo. A Finst não expõe API pública de negociação e o ccxt 4.5.x não traz classe finst, então get_account_fee_tier retorna ACCOUNT_FEES_UNSUPPORTED (a matriz deliberadamente omite o venue; o caminho de spec ausente resolve como não suportado) e não há link de referência.
• Bitpanda spot — corretora com spread de prêmio embutido + evidência de execução medida vs. anunciada (v0.44): fundada em 2014 em Viena; a Bitpanda GmbH detém autorização BaFin MiCA CASP (2025-01-27) com passaporte nos 30 estados do EEE, além da licença austríaca FMA, e atende a Grã-Bretanha por meio da Bitpanda Broker UK Ltd registrada na FCA (~7,4M usuários). O app ao consumidor NÃO é um venue de order book: ele cotaciona um preço tudo incluído com a taxa embutida como markup e sem linha de comissão separada. O schema ganha um terceiro modelo de precificação — pricing_model: "spread" ao lado de "order_book" e "flat" — com um único nível independente de volume a 1,49% maker = taker para a maioria dos ativos; sobrescritas em nível de par aplicam 0,99% por lado a BTC e aos principais pares de stablecoin (BTC/EUR, BTC/GBP, BTC/USDC, BTC/USDT e os cruzamentos de stablecoin EUR/GBP), enquanto alts genéricos mantêm 1,49%; a faixa oficial de 2,49% para ativos com capitalização de mercado abaixo de €100M e a faixa de 1,99% do índice de cripto são divulgadas em notas (não individualmente em níveis), assim como o produto de margem 10x do app ao consumidor (não modelado). Como o markup já É um custo de spread-crossing, spread_baseline.bitpanda é fixado em 0 bps cheio/crossing e getSpreadEstimate retorna 0 antecipadamente — a proteção anti-dupla contagem que impede o prêmio de 1,49% de reaparecer como linha annual_spread_cost. Um novo objeto execution_quality na spec de taxas do venue carrega evidência independente com dinheiro real: advertised_roundtrip_pct: 2.98 vs. a média medida pela TUM de 6,23% em round trip de €100 (out–nov 2025, 50 round trips por plataforma) — 4,25 pontos percentuais ocultos — replicado pela Frankfurt School of Finance em 2026-03 (432 round trips em 9 plataformas); a narrativa é anexada automaticamente a exchange_notes. O acesso é um gate positivo de nível de venue — region_allowed.bitpanda = ["EEA","GB"] — onde GB é modelado como uma chave de região de membro único (regions.GB = ["GB"]): a correspondência na whitelist autoriza GB pela precedência de gate existente sem mudança de código de gate, enquanto US/CA/CN/CH e qualquer outra residência é bloqueada no nível de venue. A pilha spot do EEE passa a ser 10 (bitstamp, bitpanda, bitvavo, bybit, coinbase, finst, gate, hyperliquid, kraken, okx) e GB é atendido (diferente de Bitvavo/Finst); futures: [] faz uma persona de futuros ver unsupported_product em serviço e blocked fora. A exchange profissional Bitpanda Fusion (liquidez externa agregada, 0,02–0,25%) é um produto separado e deliberadamente não modelado; ações/ETFs/metais tokenizados estão fora do escopo. Fiat: desde 2026 todos os trilhos do app ao consumidor são grátis — EUR SEPA/SEPA Instant, cartões Visa/Mastercard (somente depósito; a perna de saque é modelada como null), PayPal, Apple/Google Pay, e GBP FPS + cartões; não há trilho USD (uma consulta USD sem país mantém a linha com available: false / rotas vazias). Saques repassam taxas de rede dinâmicas sem markup, modelados somente para BTC 0,00000598 BTC (US$ 0,4622 no snapshot de US$ 77.298) e ETH 0,0006 ETH (US$ 1,5072) — o JSON deliberadamente não carrega campo fee_usd para que o motor recalcule a partir de asset_prices_usd; todo outro ativo retorna supported: false. Não há programa de referência e o ccxt 4.5.x não traz classe bitpanda, então get_account_fee_tier retorna ACCOUNT_FEES_UNSUPPORTED (cobertura ao vivo permanece 13 de 17 venues).
• BISON spot — principal corretora de spread com alinhamento quase perfeito entre o anunciado e o medido + saques on-chain gratuitos (v0.45): lançada em 2019 em Stuttgart pelo Boerse Stuttgart Group (~1M+ de usuários ativos, 56 criptomoedas em 2026-01); a contraparte de negociação é a EUWAX AG, que cotiza em seu próprio nome como principal — as cotações permanecem válidas por cerca de 10 segundos e não há livro de ordens. A custódia fica com a Boerse Stuttgart Digital Custody GmbH (antiga blocknox), detentora da primeira licença BaFin MiCA de custódia/transferência de cripto (2025-01-17, com passaporte para 29 estados); o serviço de câmbio de cripto da EUWAX AG é autorizado pela MiCA desde 2025-04-01 (passaporte de 8 estados) com execução de ordens adicionada em 2025-11-21 (somente Alemanha). A precificação reutiliza o modelo de spread — um único nível independente de volume a 1,75% maker = taker para todas as criptomoedas, exceto BTC/ETH, com substituições por par a 1,25% por lado para BTC/EUR e ETH/EUR (as taxas flutuam com as condições de mercado e o tamanho do ticket); o spread oficial é o único custo de negociação e não há comissão separada. Assim como na Bitpanda, spread_baseline.bison é fixado em 0 bps e getSpreadEstimate retorna antecipadamente 0 para que o spread nunca seja contado duas vezes em annual_spread_cost. O bloco execution_quality carrega o benchmark de transparência do estudo: advertised_roundtrip_pct: 2.5 vs TUM medido 2,58% — apenas 0,08 pontos percentuais não divulgados em 50 round trips padronizados de €100 ao longo de 12 dias de negociação (out–nov 2025, seis plataformas MiCA; BISON incluída na amostra de seis plataformas), o alinhamento mais próximo entre publicado e medido da amostra (Bitvavo −0,58% em seguida; Bitpanda 6,23%, Coinbase 7,49%). O acesso usa um gate positivo por venue — region_allowed.bison = ["EEA","CH"] — com CH adicionado como segunda chave de região de membro único (regions.CH = ["CH"]): todos os 30 estados do EEE e a Suíça precificam o venue (DE/AT/CH ativamente comercializados; outros estados do EEE atendidos passivamente sob liberdades de tratado), enquanto GB é bloqueado no venue — deliberadamente complementar à Bitpanda (EEE+GB) — junto com US/CA/JP/SG/AU/BR/CN/KR; a stack spot do EEE torna-se 11, a stack CH 15, e os resultados de GB/US/JP nunca contêm BISON. futures: [] (nenhum futuro ou margem hospedado pela exchange é oferecido) → unsupported_product em serviço, blocked fora. Fiat é somente EUR: SEPA/SEPA Instant gratuito em ambas as pernas, incluindo usuários suíços financiando em EUR (modelado como rotas sem região, controladas pela allowlist do venue, já que a Suíça pertence ao SEPA, mas não à tabela de regiões da UE), além de depósitos instantâneos por cartão/Apple Pay/Google Pay a 2,49% (taxa de parceiro Solaris SE/Deutsche Bank; a perna de saque é null — sem cash-out por cartão); não há trilho GBP/USD/CHF (uma consulta USD sem país mantém a linha com available: false). Os saques são oficialmente gratuitos, sem linha de taxa de rede — os custos on-chain são absorvidos pela EUWAX/o grupo (uma política estruturalmente diferente do repasse da Bitpanda) — modelados apenas para BTC 0 BTC / $0 (mín. 0,001; sem Lightning, sem pagamentos Taproot bc1p) e ETH 0 ETH / $0 (Ethereum somente mainnet, mín. 0,01; sem Arbitrum/Base/Optimism/Polygon/BNB Chain L2), o que torna a BISON o best global para ambos os ativos; todos os outros ativos retornam supported: false, e a comparação de saques deliberadamente não é controlada por país. A ordem fixa de €1,99 para ações/ETFs alemães (somente Alemanha) e a comissão de 27% sobre recompensas de staking (ETH/SOL) estão fora do escopo. O programa de indicação de amigos (recompensas em ETH para DE/AT/CH) não tem URL de afiliado e o ccxt 4.5.78 não inclui nenhuma classe bison/euwax, então getReferralLink retorna NO_REFERRAL_LINK e get_account_fee_tier retorna ACCOUNT_FEES_UNSUPPORTED (a cobertura ao vivo permanece em 13 de 18 venues).
• accountAssetsUsd (opcional, OKX / Bybit / Bitget / Kraken / BingX / BloFin) — ativos totais da conta em USD. O nível VIP é o maior entre o seu nível de volume de 30 dias e o seu nível de ativos, tanto para spot quanto para futuros (ex.: OKX VIP1 = $100k … VIP9 = $500M com rebates negativos de maker; Bybit VIP4 = $1M; Bitget VIP1 = $30k; Kraken Tier 3 = $20k AOP … Pro 5 = $100M; BingX VIP1 = $50k … VIP5 = $3M; BloFin VIP1 = $50k … VIP5 = $3M nos próprios limites de cada produto). Os ativos só podem subir de nível, nunca descer; linhas somente de volume (ex.: Bybit Supreme, Kraken Tier 1–2, BingX Elite e Supreme) não se qualificam via ativos; BloFin VIP4/VIP5 adicionalmente exigem ≥80% de volume não-API (o motor assume conformidade, ressalva em exchange_notes). Omitir o parâmetro cotiza o nível de volume e retorna uma dica de upgrade pelo caminho de ativos (next_min_assets).
• pair (opcional, v0.12) — um par de negociação como BTC/USDT, BTC/FDUSD ou BTCUSDT (separadores são normalizados). Quando o par tem uma promoção de taxa conhecida, as taxas promocionais substituem as taxas do nível da conta e os resultados carregam pricing_basis: "pair" além de um pair_note; caso contrário, a precificação permanece account_tier. Promoções de par verificadas: MEXC — todos os pares spot a 0% maker + 0% taker (programa de taxa zero), 100+ pares de futuros a 0/0 sujeitos a cotas por conta; Binance — pares FDUSD (BTC/ETH/BNB/DOGE/LINK/SOL/XRP) a 0% maker com taker baseado em nível, pares USDC a 0% maker / 0,095% taker; Bitget — USDC/USDT e USDGO/USDT a 0/0 (volume não conta para VIP); Bitpanda (v0.44) — a faixa de prêmio embutido de 0,99%/lado em BTC e pares de stablecoins principais vs o headline de 1,49% (uma faixa de precificação de corretora de spread, não uma promoção; flag de não-promoção); Bison (v0.45) — a faixa de 1,25%/lado em BTC/EUR e ETH/EUR vs o headline de 1,75% (mesmo padrão de faixa de spread não-promocional). Uma substituição de par pode cobrir apenas maker, apenas taker, ou ambos.
• makerShare (0-1, padrão 0) — fração do volume executada como maker (ordens limitadas). Taxa ponderada = maker × share + taker × (1-share). Traders de ordens limitadas devem passar 0,7-1.
• useToken — preços em descontos de token nativo: BNB (25% spot / 10% futuros), GT (maker de futuros → 0 mais desconto de 10-50% por nível de participação com tokenBalance), MX (20% spot + futuros; 500+ MX eleva o desconto para 50% — o maior se aplica, eles não acumulam), BGB (20% spot + futuros), KCS (20% spot Classe A/B/C + futuros; no VIP8+ o maker já é 0%, então apenas o lado taker se beneficia), OKB (embutido nos níveis da OKX), e HYPE em staking na Hyperliquid (10/100/1k/10k/100k/500k em staking → 5/10/15/20/30/40% de desconto em todas as taxas maker+taker, acumulando multiplicativamente com o nível de volume; tokenBalance deve ser o valor em staking — apenas manter não dá nada).
• Taxas maker negativas — makers OKX VIP7+ são negativos (spot/futuros, até -0,0075%) e makers de futuros da Kraken são negativos a partir do Tier 11 (até -0,006% no Pro 5), ou seja, rebates de maker pagos pela exchange. Eles passam por descontos de referência/token inalterados (um desconto não pode reduzir um rebate), aparecem como estimativas de taxa negativas e classificam-se à frente de taxas pagas.
• holdingHours (futuros) — exposição mensal de posição em horas; custo de funding à taxa de funding de cada exchange (intervalo de 8h para a maioria dos venues; a Hyperliquid liquida a cada hora — seu 0,00125%/1h agrupado equivale à média neutra de 0,01%/8h das CEXs). calculate_annual_cost anualiza isso ×12. Cada valor de funding carrega funding_source (bundled ou live) além de funding_rate_ts / funding_pair quando dados ao vivo foram usados.
• fundingMode + fundingPair (opcional, v0.15) — entradas de funding para calculate_savings, compare_total_cost, recommend_exchange e calculate_annual_cost. fundingMode: "bundled" (padrão) usa a média offline de longo prazo (0,01%/8h para BTC/USDT — instantânea e determinística). fundingMode: "live" busca a taxa de funding atual do venue em tempo real via ccxt para fundingPair (padrão BTC/USDT; aceita ETH/USDT, SOL-USDT, BTCUSD …). Cada exchange é buscada independentemente com timeout de 8s; qualquer venue que falhar (timeout, geo-block, par ausente) cai transparentemente para sua média agrupada e é listado em failures para a ferramenta dedicada. Os resultados são armazenados em cache TTL na memória por 5 minutos (o funding só liquida a cada poucas horas). Taxas ao vivo negativas passam intactas — longs então são pagos. A ferramenta standalone get_funding_rates aceita fundingMode, fundingPair, exchanges: [...] opcional e country opcional para filtragem.
• tradeSizeUsd + spreadMode + spreadPair + side (v0.16) — entradas de custo de execução para calculate_savings, compare_total_cost, recommend_exchange e calculate_annual_cost. Quando tradeSizeUsd (um único tamanho de ordem marketable, ex.: 10000) é passado, cada resultado de custo adiciona o custo de cruzamento bid-ask de via única (metade do spread total típico) para essa ordem, marcado com spread_source. spreadMode: "bundled" (padrão) precifica a partir de baselines offline do venue escalados por classe de par — majors (BTC/ETH) ×1,0, large caps (SOL/XRP/DOGE … 27 nomes) ×1,5, outras alts ×3 — com slippage modelado zero. spreadMode: "live" busca o livro de ordens top-100 real de cada venue via ccxt, resolve automaticamente o mercado spot ou swap linear correto (spot da KuCoin usa a classe kucoin, não kucoinfutures), e caminha o VWAP pela profundidade para side: "buy" | "sell" medir slippage condicionado ao tamanho além do melhor touch, além de levels_consumed, available_depth_usd e fully_filled. Falhas por venue (timeout, geo-block, mercado ausente) caem para o baseline agrupado e são listadas em failures; quando a profundidade visível é menor que a ordem, o valor medido é mantido com uma entrada warnings (impacto além da profundidade não é extrapolado). Caminhadas de livro são armazenadas em cache TTL por 30 segundos. compare_total_cost dobra spread + slippage em total_cost; calculate_annual_cost os escala com nocional anual negociado (mensal ×12, assumindo fluxo fatiado em ordens de tamanho tradeSizeUsd); recommend_exchange combina execução na pontuação (taxa 70% / funding 15% / spread 15% quando ambos se aplicam). A ferramenta standalone get_execution_cost aceita tradeSizeUsd (padrão $10.000), pair, purpose, side, spreadMode, exchanges: [...] opcional e country.
• Entradas de rampa fiat on/off (v0.17, get_fiat_cost) — direction: "deposit" | "withdraw" (depósito padrão), amount em fiat ou amountUsd (convertido à taxa de exibição estática), currency: "USD" | "EUR" | "GBP" | "BRL" (padrão USD), country residência ISO (direciona filtragem de conformidade e disponibilidade de trilhos regionais — ex.: cartão emitido na UE da Bybit a 1,1% vs 3,05% em outros lugares, ACH somente EUA), filtro method: "card" | "ach" | "sepa" | "fps" | "wire" | "swift" | "pix" opcional e exchanges: [...] opcional. Apenas trilhos diretos operados pela exchange são modelados — gateways de cartão de terceiros (Banxa/Simplex/MoonPay/Zen, tipicamente 1,99–5,5% no checkout), P2P e cobranças do lado bancário são excluídos por design (variam por usuário e são mencionados em advice/notes). As taxas suportam percentual + fixo com pisos mín/máx (ex.: Bybit SEPA 0,19% mín €1, Binance SWIFT fixo 5 limitado a 25). Os resultados retornam taxa por trilho, equivalente em USD, percentual efetivo, valor líquido, ETA, trilho mais barato por venue, um best geral, saving_vs_worst_usd e avisos (venues sem trilho qualificado, país ausente para trilhos bloqueados por região). Cartões variam de 1,1–4,5% entre venues, enquanto trilhos bancários ACH/SEPA/FPS/PIX são gratuitos ou quase gratuitos em quase todos os lugares.
• Pernas fiduciárias nas ferramentas de custo total (v0.26) — compare_total_cost e calculate_annual_cost agora aceitam fiatCurrency, fiatDepositAmountUsd + fiatDepositsPerYear, fiatCashoutAmountUsd + fiatCashoutsPerYear e fiatMethod opcional, e incorporam a taxa de trilho direto mais barata × contagem anual no total como fiat_deposit_cost / fiat_cashout_cost (ferramentas anuais: annual_fiat_deposit_cost / annual_fiat_cashout_cost). Isso precifica a pilha COMPLETA que um trader de varejo realmente paga — taxas de negociação + funding + spread/slippage + saques on-chain + depósitos e saques bancários/cartão — em uma única chamada. Um trilho gratuito, mas real, retorna custo 0 com fiat_deposit_available: true; uma plataforma sem trilho direto (ex.: Hyperliquid/BingX/Phemex/BloFin) retorna a perna excluída (0) com fiat_deposit_available: false, nunca tratada silenciosamente como gratuita. Quando nenhum hábito fiduciário é passado, as chaves são omitidas e o comportamento permanece inalterado.
• Recomendação com consciência fiduciária (v0.27) — recommend_exchange aceita os mesmos seis parâmetros de hábito fiduciário e junta os custos anualizados de trilho direto à pontuação. O peso fiduciário é orientado por dados, com base na dispersão de custos: fiatWeight = 0.2 + 0.3 × dispFiat / (dispFee + dispFiat) onde as dispersões são os intervalos anualizados de custo entre plataformas, então ele sobe de 0,2 para 0,5 exatamente quando as diferenças de taxas fiduciárias superam as diferenças de taxas de negociação (pequenos on-rampers mensais) e permanece em 0,2 para traders de alto volume; o peso restante é redistribuído entre taxa/funding/spread. Uma plataforma sem trilho pontua zero nessa direção (trilhos gratuitos, mas reais, pontuam 100) e recebe uma compensação explícita nomeando o caminho real de terceiros/P2P (tipicamente 1,99–5,5%); a recomendação também nomeia a plataforma mais barata em fiduciário e o delta anual quando o vencedor cobra mais pelo exato mesmo hábito. Sem os parâmetros, a pontuação é byte-idêntica à tabela de pesos pré-v0.27. Exemplo de inversão (v0.41 EEA): DE spot $500/mês + 12×€1.000 SEPA — sem o hábito, a Hyperliquid sem trilho vence com 100 em taxas entre plataformas utilizáveis na EEA; com o hábito, a OKX (SEPA gratuito em ambas as pernas) vence com 92,2 vs. Hyperliquid 62,7 (Binance/MEXC não são mais utilizáveis na EEA).
• withdrawalAsset + withdrawalNetwork (cobertura de rede v0.18) — adiciona taxas de saque de rede. A tabela incluída cobre 16 ativos (BTC, ETH, SOL, XRP, DOGE, LTC, TRX, ADA, AVAX, DOT, LINK, BCH, TON, POL, USDT, USDC) em TRC-20, ERC-20, BEP20, Arbitrum, Optimism, Base, Polygon, Avalanche C, Solana, TON, Polkadot/AssetHub e a cadeia nativa de cada ativo em todas as 18 plataformas (a disponibilidade de rota varia por plataforma; Coinbase, BingX, BloFin e Bitstamp cobrem apenas BTC / ETH / USDT / USDC; Bitvavo (v0.42) modela apenas BTC dinâmico a 0,00005, sinalizando todos os outros ativos como não suportados; Finst (v0.43) modela apenas BTC a 0,000085 all-in (taxa de rede dinâmica + taxa fixa de terceiros de €2,50 combinadas, divulgadas por nota de rota), todos os outros ativos não suportados; Bitpanda (v0.44) modela pass-through dinâmico de BTC 0,00000598 ($0,4622) e ETH 0,0006 ($1,5072) apenas (sem fee_usd armazenado — recalculado a partir do snapshot de preço), todos os outros ativos não suportados; Bison (v0.45) modela BTC e ETH com taxa 0 — o grupo absorve os custos de rede on-chain, tornando-o o best global para ambos os ativos (BTC mainnet mín. 0,001; ETH mainnet apenas, mín. 0,01, sem L2s), todos os outros ativos não suportados; Hyperliquid lista uma única rota fixa de ~1 USDC para Arbitrum / 22+ cadeias CCTP; BloFin cotiza pass-through de custo de rede dinâmico com stablecoins TRC-20 a ~1). Taxas em unidades nativas são convertidas para USD a partir de um snapshot de preço de 12/09/2026 (asset_prices_usd); rotas pausadas entre ago–set 2026 (ex.: carteiras TON em cinco plataformas, USDC-TRC20 em Gate/KuCoin/BingX, cadeia de retransmissão DOT) carregam suspended: true e nunca são tratadas como abertas. Quando nenhuma rede é passada, a rota aberta mais barata da plataforma é precificada automaticamente; a entrada de rede aceita aliases (trc20, erc20, arb, matic, sol …). calculate_annual_cost multiplica a taxa por evento por withdrawalsPerYear. A ferramenta autônoma get_withdrawal_fees(asset?, network?, country?, exchanges?) (totalmente offline) retorna a comparação completa por rota com best, saving_vs_worst_usd e avisos; códigos de erro: INVALID_ASSET, INVALID_NETWORK, UNKNOWN_EXCHANGE.
• Predefinições de persona de trader (v0.22, analyze_persona) — sete arquétipos ancorados em pesquisa em data/personas.json agrupam um perfil comportamental completo: mercado (spot/futuros), volume mensal, participação de maker, horas mensais de manutenção, tamanho típico de lote (tradeSizeUsd), ativo de saque + contagem anual e depósitos/saques fiduciários anuais (moeda + hábito de trilho). As personas são casual_buyer (comprador pequeno financiado por cartão — taxas de cartão dominam), hodler_accumulator (DCA mensal + saques BTC para armazenamento frio), active_spot_trader, swing_futures_trader (funding é a maior linha), day_scalper (alto volume, 90% maker), vip_institutional ($30M/mês, $3M em ativos, lotes de $100k → spread ao vivo recomendado) e dex_native (fluxos USDC on-chain, sem necessidades KYC/fiduciárias — trilhos ausentes são sinalizados, não zerados). Cada persona executa a mesma pilha anualizada que as outras ferramentas precificam individualmente — taxas de negociação + funding + execução + saques por evento + fiduciário — retorna o cost_mix_pct por plataforma, component_leaders, um best principal, além de um best_complete separado: a plataforma mais barata onde cada perna da persona é realmente precificada (ex.: Hyperliquid pode ser destaque para uma persona de futuros, mas carecer de trilhos fiduciários ou uma rota USDT/BTC — é sinalizada com withdrawal_unsupported/disponibilidade fiduciária e a escolha realista de todas as pernas é mostrada com seu custo extra). Cada predefinição é um padrão substituível via monthlyVolumeUsd, makerShare, useToken, tokenBalance, accountAssetsUsd, holdingHours, tradeSizeUsd, pair, currency, além de substituições ao vivo fundingMode/fundingPair e spreadMode/spreadPair; personas são validadas contra um esquema e versionadas como qualquer outro arquivo de dados.
• currency — moeda de exibição USD (padrão), EUR, JPY, CNH, GBP. Apenas taxas de exibição estáticas; toda a matemática permanece baseada em USD.
• language (v0.30, estendido em v0.31/v0.36) — idioma de saída para a camada narrativa em compare_exchange_fees, compare_total_cost, calculate_savings, calculate_annual_cost, get_fiat_cost, get_withdrawal_fees, recommend_exchange, analyze_persona, compare_personas, analyze_token_discount, volume_what_if e compare_countries: "en" (padrão) ou "zh". Todos os conselhos / avisos / compensações / razões / avisos de nível são renderizados a partir de um catálogo centralizado de modelos bilíngues (src/i18n.ts); a saída em inglês é byte-idêntica à pré-v0.30, e números, nomes de campos, códigos de erro e notas orientadas a máquina permanecem independentes de idioma, então mudar o idioma nunca altera o esquema de dados.
• format / tableMetric (v0.36, apenas as três ferramentas de matriz) — compare_personas, volume_what_if e compare_countries aceitam format: "json" (padrão) | "markdown" | "csv" | "both". Com qualquer formato não-JSON, o resultado ganha um objeto rendered: { metric, markdown?, csv? }: uma tabela intitulada e pronta para colar em inglês ou chinês de acordo com language; matriz de personas = plataformas × personas com custo anual all-in (células sem trilho carregam um marcador † apenas em markdown, CSV permanece numérico); what-if = linhas de volume mensal × plataformas com tableMetric: "weighted_fee_pct" (4 casas decimais, padrão) | "annual_fee_usd" | "tier"; países = plataformas × países com tableMetric: "availability" (✓/⛔/–, padrão; CSV usa os tokens brutos available/blocked/unsupported_product) | "cost". CSV é RFC 4180 (campos com vírgulas/aspas/novas linhas são citados, " duplicado, finais de linha CRLF); volumes em markdown são compactos ($100K/$3.5M) enquanto CSV mantém números brutos. Valores inválidos retornam INVALID_INPUT; o payload JSON em si permanece inalterado em todos os formatos.
• Cada resultado de taxa carrega um carimbo de frescor data_as_of, um tier_warning para o portão AND da BNB e os caminhos de upgrade OR de GT/KCS/ativo de conta/AOP, e um freshness_warning quando os dados agrupados têm mais de 3 meses além de last_verified. Resultados da Kraken também carregam exchange_notes — ressalvas de qualificação específicas da exchange (faixas de nível unificadas, limitações regionais de futuros, precificação Pro vs. app de consumo).

Instalação

Uso no Claude Desktop / Cursor / qualquer cliente MCP

Adicione à configuração MCP do seu cliente (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "fee-optimizer-mcp": {
      "command": "npx",
      "args": ["-y", "fee-optimizer-mcp"]
    }
  }
}

Executar localmente a partir do código-fonte

git clone https://github.com/gaokai258/fee-optimizer-mcp.git
cd fee-optimizer-mcp
npm install
npm run build
npm start        # starts stdio server (default)

Transporte HTTP Streamable (v0.29)

Além do stdio, o servidor também roda como um endpoint MCP Streamable HTTP sem estado (especificação MCP 2025-03-26) — um servidor MCP isolado é criado por POST, então as requisições são seguras para concorrência e escaláveis horizontalmente sem sessões persistentes; as respostas são application/json simples, nenhum Mcp-Session-Id é emitido, e SSE GET/DELETE retornam 405 por design.

# CLI flags
node dist/index.js --transport http --host 0.0.0.0 --port 3333 --endpoint /mcp
# or
npm run start:http

# env overrides: FEE_MCP_TRANSPORT=http, FEE_MCP_HTTP_HOST, FEE_MCP_HTTP_PORT,
#                FEE_MCP_HTTP_ENDPOINT (HOST/PORT also accepted)
node dist/index.js --help        # all flags

• POST /mcp — JSON-RPC (mensagem única ou lote); requer Accept: application/json, text/event-stream e Content-Type: application/json. Como o serviço é totalmente sem estado, um POST tools/call simples sem handshake funciona, e clientes estritos também podem enviar initialize em um POST próprio primeiro.
• GET /health — sonda do balanceador de carga: { status, service, version, transport, mode, endpoint, auth_required, rate_limit_per_min, uptime_s } (sem necessidade de autenticação mesmo quando a autenticação bearer está ativada).
• Caminhos desconhecidos → 404; não-POST em /mcp → 405 com Allow: POST; Accept inválido → 406.

Endurecimento de hospedagem pública (v0.32)

Todas as proteções são opt-in via variáveis de ambiente — o comportamento local/de desenvolvimento permanece inalterado. Coloque um proxy reverso com terminação TLS (nginx/Caddy/Cloudflare) na frente ao vincular 0.0.0.0.

Variável de ambiente	Efeito
FEE_MCP_BEARER_TOKEN=<secret>	Todo POST MCP deve enviar Authorization: Bearer <secret> (comparação em tempo constante). Ausente/incorreto → 401 + WWW-Authenticate (código JSON-RPC -32002). /health permanece aberto para sondas.
FEE_MCP_RATE_LIMIT_PER_MIN=<n>	Limite de janela fixa por IP do cliente em POSTs MCP; excesso → 429 + Retry-After (-32001). Tentativas não autenticadas também contam, então inundações sem token não podem contornar isso. 0/não definido = ilimitado.
FEE_MCP_ACCESS_LOG=1	Uma linha JSON estruturada por requisição no stdout: ts, ip, method, path, status, duration_ms, auth (none/ok/fail), rate_limited, user_agent.
FEE_MCP_TRUST_PROXY=0	Ignorar X-Forwarded-For (defina isso apenas quando NÃO estiver atrás de um proxy reverso; o padrão confia no primeiro salto XFF).

Configuração de cliente MCP remoto (HTTP com token bearer):

{
  "mcpServers": {
    "fee-optimizer-mcp": {
      "type": "http",
      "url": "https://your-host/mcp",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

Docker

docker build -t fee-optimizer-mcp .                              # or: npm run docker:build
docker run -d --name fee-mcp -p 3333:3333 \
  -e FEE_MCP_BEARER_TOKEN=$(openssl rand -hex 32) \
  -e FEE_MCP_RATE_LIMIT_PER_MIN=120 \
  -e FEE_MCP_ACCESS_LOG=1 \
  fee-optimizer-mcp                                              # or: npm run docker:run
curl -s http://localhost:3333/health

A imagem multi-estágio roda em node:22-alpine como usuário não-root, inclui apenas dependências de produção + dist/ + data/, e contém um /health HEALTHCHECK.

Inspecionar com o MCP Inspector

npm run inspector                                   # stdio
npx @modelcontextprotocol/inspector --transport http http://127.0.0.1:3333/mcp   # HTTP

Referência de ferramentas

• compare_exchange_fees(purpose, country, monthlyVolumeUsd?, useToken?, makerShare?, tokenBalance?, accountAssetsUsd?, pair?) — Comparação da tabela de taxas ordenada pela taxa efetiva ponderada.

• get_referral_link(exchange, country) — Resolve uma URL de referência; retorna erro com COUNTRY_BLOCKED / UNKNOWN_EXCHANGE / NO_REFERRAL_LINK quando aplicável.

• calculate_savings(exchange, volume, type, country, useToken?, holdingHours?, makerShare?, currency?, tokenBalance?, accountAssetsUsd?, pair?, fundingMode?, fundingPair?, tradeSizeUsd?, spreadMode?, spreadPair?, side?) — Detalhamento de economia vs. a taxa do nível base; com tradeSizeUsd também retorna spread_cost / slippage_cost / spread_source / spread_ts / spread_pair.

• compare_total_cost(purpose, country, volume, holdingHours?, useToken?, withdrawalAsset?, withdrawalNetwork?, makerShare?, currency?, tokenBalance?, accountAssetsUsd?, pair?, fundingMode?, fundingPair?, tradeSizeUsd?, spreadMode?, spreadPair?, side?, fiatCurrency?, fiatDepositAmountUsd?, fiatDepositsPerYear?, fiatCashoutAmountUsd?, fiatCashoutsPerYear?, fiatMethod?) — Classificação de custo total; com tradeSizeUsd, spread + slippage são incorporados em total_cost; com os parâmetros de hábito fiduciário v0.26, taxas anualizadas de depósito/saque por trilho direto também são incorporadas (corretoras sem trilho sinalizadas, perna excluída).

• recommend_exchange(purpose, country, volume, makerShare?, useToken?, holdingHours?, currency?, tokenBalance?, accountAssetsUsd?, pair?, fundingMode?, fundingPair?, tradeSizeUsd?, spreadMode?, spreadPair?, side?, fiatCurrency?, fiatDepositAmountUsd?, fiatDepositsPerYear?, fiatCashoutAmountUsd?, fiatCashoutsPerYear?, fiatMethod?) — Melhor corretora com pontuação (combinação de taxa/financiamento/spread quando a execução é precificada), motivos, avisos de nível de retenção, tradeoffs, conselhos acionáveis e alternativas. v0.27: quando o hábito fiduciário é informado, custos anualizados de depósito/saque por trilho direto entram na pontuação com um peso fiduciário orientado por dispersão (0,2→0,5) — quanto mais as diferenças de taxas fiduciárias entre corretoras dominam as diferenças de taxas de negociação do ano (típico para pequenos compradores mensais), mais o fiduciário decide; uma corretora sem trilho direto pontua zero nessa perna e recebe um tradeoff explícito em vez de vencer com um custo não precificado. Exemplo: um comprador alemão de DCA de €1.000/mês via SEPA negociando apenas $500/mês recebe recomendação da Binance (SEPA gratuito) em vez da MEXC nominalmente mais barata em taxas (~$16/ano em taxas SEPA), enquanto um trader de $100k/mês ainda é classificado pelas taxas de negociação.

• calculate_annual_cost(exchange, purpose, country, monthlyVolumeUsd, makerShare?, useToken?, tokenBalance?, accountAssetsUsd?, holdingHours?, withdrawalAsset?, withdrawalNetwork?, withdrawalsPerYear?, currency?, pair?, fundingMode?, fundingPair?, tradeSizeUsd?, spreadMode?, spreadPair?, side?, fiatCurrency?, fiatDepositAmountUsd?, fiatDepositsPerYear?, fiatCashoutAmountUsd?, fiatCashoutsPerYear?, fiatMethod?) — Taxas de negociação anualizadas (mensal ×12) + financiamento (exposição mensal ×12) + spread/slippage (nocional anual negociado × bps, quando tradeSizeUsd é fornecido) + saques (por evento × contagem anual) + depósitos/saques fiduciários diretos v0.26 (trilho mais barato × contagem anual, perna sinalizada-e-excluída quando a corretora não tem trilho), além de um bloco upgrade: o próximo nível VIP, como se qualificar (volume / ativos de conta OKX-Bybit-Bitget / Kraken AOP / Gate GT / KuCoin KCS / Binance BNB) e economia anual estimada.

• get_data_sources() — Relatório de proveniência; sem parâmetros. Retorna todos os 15 arquivos de pacote com last_verified, lista completa de fontes (URLs oficiais e/ou notas de metodologia) e frescor por arquivo v0.33: cada arquivo carrega months_behind e is_stale (mais antigo que 3 meses ou não analisável), além de stale_after_months e stale_files: [...] no nível do relatório para que um agente veja imediatamente qual pacote precisa de re-verificação; data_as_of permanece como o carimbo mais antigo entre os arquivos.

• get_funding_rates(fundingMode?, fundingPair?, exchanges?, country?) — Tabela de taxas de financiamento para um par perpétuo. O modo empacotado é offline; o modo ao vivo busca taxas em tempo real corretora por corretora e retorna { pair, mode, fetched_at, data_as_of, rates: [{ exchange, rate_pct, interval_hours, source, funding_timestamp?, note? }], failures: [{ exchange, error, fallback: "bundled" }] }. As quatro ferramentas de custo também aceitam fundingMode? e fundingPair?.

• get_fiat_cost(direction?, amount? | amountUsd?, currency?, country?, method?, exchanges?) — Tabela de custos de entrada/saída fiduciária direta; totalmente offline. Retorna { direction, currency, amount, amount_usd, fx_rate, fetched_at, data_as_of, exchanges: [{ exchange, available, routes: [{ method, region?, fee, fee_usd, effective_pct, net, eta, note? }], cheapest_method?, cheapest_fee_usd?, notes? }], best: { exchange, method, fee, fee_usd, effective_pct, net } | null, saving_vs_worst_usd?, advice, warnings? }. Códigos de erro: INVALID_CURRENCY, INVALID_AMOUNT, MISSING_FX_RATE, UNKNOWN_EXCHANGE.

• get_execution_cost(tradeSizeUsd?, pair?, purpose?, side?, spreadMode?, exchanges?, country?) — Tabela de custo de execução taker unilateral. O modo empacotado é offline; o modo ao vivo percorre o livro real top-100 de cada corretora com VWAP e retorna { pair, purpose, side, trade_size_usd, mode, fetched_at, data_as_of, costs: [{ exchange, spread_bps, crossing_bps, slippage_bps, total_bps, cost_usd, levels_consumed?, fully_filled?, available_depth_usd?, source, book_timestamp?, symbol?, pair_class, note? }], failures: [{ exchange, error, fallback: "bundled" }], warnings?: [{ exchange, message }] }. As quatro ferramentas de custo também aceitam tradeSizeUsd?, spreadMode?, spreadPair?, side?.

• get_withdrawal_fees(asset?, network?, country?, exchanges?) — Comparação de taxas de saque on-chain; totalmente offline. asset assume como padrão USDT; network aceita nomes canônicos e aliases (trc20, erc20, bsc, arb, op, matic, c-chain, sol, assethub …); sem rede, todas as rotas por corretora são retornadas e classificadas pela aberta mais barata. Retorna { asset, network?, asset_price_usd?, fetched_at, data_as_of, exchanges: [{ exchange, supported, networks: [{ network, fee, fee_usd, available, note? }], cheapest_network?, cheapest_fee_usd? }], best: { exchange, network, fee, fee_usd } | null, saving_vs_worst_usd?, advice, warnings? }. Rotas suspensas permanecem em networks com available: false; corretoras sem rota para o ativo/rede retornam supported: false e uma lista networks vazia. Códigos de erro: INVALID_ASSET, INVALID_NETWORK, UNKNOWN_EXCHANGE.

• analyze_persona(persona, country, monthlyVolumeUsd?, makerShare?, useToken?, tokenBalance?, accountAssetsUsd?, holdingHours?, tradeSizeUsd?, pair?, currency?, fundingMode?, fundingPair?, spreadMode?, spreadPair?, side?) — Análise anual de custo total para um dos sete personas de trader ancorados em pesquisa. Totalmente offline no modo padrão. Retorna { persona, country, purpose, inputs, currency, ranking: [{ exchange, tier, annual_trading_fee, annual_funding_cost, annual_execution_cost, annual_withdrawal_cost, annual_fiat_deposit_cost?, annual_fiat_cashout_cost?, annual_all_in, cost_mix_pct, withdrawal_unsupported?, fiat_deposit_available?, fiat_cashout_available?, pricing_basis, tier_warning?, referral_url?, exchange_notes? }], best: { exchange, annual_all_in, runner_up_exchange, saving_vs_runner_up, reasons, tradeoffs } | null, best_complete: { exchange, annual_all_in, extra_vs_winner } | null, component_leaders, warnings, advice, data_as_of, data_sources }. Trilhos/rotas ausentes são sinalizados e EXCLUÍDOS da linha (nunca contados como $0); INVALID_INPUT para um id de persona desconhecido (a lista de ids válidos é retornada).

• analyze_token_discount(exchange, purpose, country, monthlyVolumeUsd, makerShare?, tokenBalance?, accountAssetsUsd?, tokenPriceUsd?, currency?) — Análise de payback do desconto de taxa com token nativo; totalmente offline. Calcula a taxa anual SEM o token nativo (nível de saldo zero, sem alternância de dedução de taxa) vs. COM ele (dedução fixa BNB/MX/BGB/KCS, escada de nível de retenção GT/MX/HYPE, maker-para-zero no futures da Gate, elevação de nível GT/KCS/BNB por retenção), a economia anual em USD, o custo de oportunidade em USD de travar o saldo de token exigido, payback em meses e a queda máxima de preço do token em um ano que a economia pode absorver (breakeven_price_drop_pct). Quando tokenBalance é omitido, retorna tiers_analysis (todos os níveis de desconto alcançáveis classificados) com um recommended_tier_index (payback mais curto entre níveis com economia positiva). Corretoras sem alternância separada (OKX, Kraken, Coinbase, Bybit, BingX) relatam has_native_discount: false honestamente em vez de inventar um desconto. O preço do token vem de data/token_prices.json (snapshot de 2026-09) ou da substituição tokenPriceUsd. Códigos de erro: UNKNOWN_EXCHANGE, COUNTRY_BLOCKED, INVALID_INPUT, NO_RESULTS.

• compare_personas(country, personas?, useToken?, currency?, fundingMode?, fundingPair?, spreadMode?, spreadPair?, side?, language?, format?) (v0.28, format na v0.36) — Matriz de decisão multi-persona em uma única chamada; totalmente offline no modo padrão. Executa cada persona (ou o subconjunto personas: [...], preservando ordem, sem duplicatas) pelo mesmo mecanismo de analyze_persona e retorna { country, currency, personas: [{ persona: {id, name_en, name_zh, tagline_zh}, purpose, monthly_volume_usd, best: { exchange, tier, annual_all_in, runner_up_exchange, saving_vs_runner_up, cost_mix_pct, tradeoffs } | null, best_complete: { exchange, annual_all_in, extra_vs_winner } | null, matrix: [{ exchange, annual_all_in, withdrawal_unsupported?, fiat_deposit_available?, fiat_cashout_available? }] }], venues, venue_wins: [{ exchange, headline_persona_ids, complete_persona_ids }], most_versatile, rendered?: { metric, markdown?, csv? }, data_as_of, data_sources, errors? }. A matriz é classificada do mais barato primeiro por persona; uma corretora ausente de uma linha está bloqueada no país ou é apenas spot. venue_wins é ordenado por vitórias realistas (best_complete) primeiro e depois por vitórias de manchete; most_versatile é a corretora com mais vitórias em todas as pernas. Profundidade ao vivo é resolvida por persona (dependente de propósito + clipe). Códigos de erro: INVALID_INPUT (id de persona desconhecido / formato inválido), NO_RESULTS.

• volume_what_if(purpose, country, volumes?, baseVolume?, makerShare?, useToken?, tokenBalance?, accountAssetsUsd?, pair?, currency?, language?, format?, tableMetric?) (v0.34, format/tableMetric na v0.36) — Varredura what-if de volume; totalmente offline. Retorna { purpose, country, currency, maker_share, use_token, base_monthly_volume_usd?, volumes, data_as_of, points: [{ monthly_volume_usd, annual_traded_notional_usd, cheapest: { exchange, tier, weighted_fee_pct, annual_fee_usd }, ranking: [{ exchange, tier, volume_tier?, weighted_fee_pct, annual_fee_usd, tier_crossed? }] }], tier_crossings: [{ at_monthly_volume_usd, exchange, from_tier, to_tier }], exchanges: [{ exchange, current: { monthly_volume_usd, tier, weighted_fee_pct, annual_fee_usd } | null, next_tier?: { from_tier, to_tier, at_monthly_volume_usd, additional_monthly_volume_usd, weighted_fee_pct_now, weighted_fee_pct_next, saving_per_year_usd_at_current_volume, blocked_by_holding_gate? } | null, sweep: [{ monthly_volume_usd, tier, volume_tier?, effective_maker_pct, effective_taker_pct, weighted_fee_pct, annual_fee_usd, tier_crossed? }] }], advice, warnings?, rendered?: { metric, markdown?, csv? } }. volumes padrão = a união ordenada sem duplicatas de todos os limites de nível VIP de cada corretora permitida mais 0 e baseVolume; uniões acima de 16 pontos são amostradas por passos em toda a faixa (com um aviso, sempre mantendo 0/base/máx) e volumes explícitos permitem até 24 pontos personalizados. next_tier está presente apenas quando baseVolume é fornecido (null = já no degrau de volume máximo da corretora); descontos de referência e opcionais de token de plataforma se aplicam exatamente como em compare_exchange_fees. Apenas taxas de negociação — financiamento/spread/saques/fiduciário não são incluídos. tableMetric (com format não-json): weighted_fee_pct (padrão) | annual_fee_usd | tier. Códigos de erro: BAD_VOLUME, UNKNOWN_CURRENCY, INVALID_INPUT (formato/tableMetric inválido), NO_RESULTS.

• compare_countries(persona?, countries?, monthlyVolumeUsd?, makerShare?, useToken?, tokenBalance?, accountAssetsUsd?, holdingHours?, tradeSizeUsd?, pair?, currency?, fundingMode?, fundingPair?, spreadMode?, spreadPair?, side?, language?, format?, tableMetric?) (v0.35, format/tableMetric na v0.36) — Matriz de diferença por país; totalmente offline no modo padrão. Executa o mesmo mecanismo analyzePersona uma vez por país e retorna { persona: {id, name_en, name_zh}, purpose, currency, countries, data_as_of, rows: [{ country, available_venues, winner: {exchange, tier, annual_all_in} | null, best_complete: {exchange, annual_all_in, extra_vs_winner} | null, comparison_basis: "winner"|"best_complete", comparison_annual_all_in, extra_vs_cheapest_country_usd, extra_vs_cheapest_country_pct, blocked_venues, unsupported_product_venues, ranking, error?, error_code? }], cheapest_country: {country, exchange, tier?, annual_all_in, basis} | null, costliest_country, spread_usd, winner_venue_counts: [{exchange, count, countries}], venue_availability: [{exchange, per_country: {CC: available|blocked|unsupported_product}, blocked_in}], advice, warnings?, rendered?: { metric, markdown?, csv? } }. Padrões: persona active_spot_trader, países US/GB/DE/JP/SG/BR/CN (máx. 12, sem duplicatas). Deltas entre países usam comparison_annual_all_in = o custo best_complete de todas as pernas quando o vencedor da manchete não tem trilhos, caso contrário o vencedor — então uma corretora sem trilhos fiduciários/saques não pode fazer um país parecer artificialmente barato. Substituições ao vivo (financiamento/profundidade) são buscadas uma vez sobre a união de corretoras permitidas em QUALQUER país selecionado. tableMetric (com format não-json): availability (padrão) | cost. Códigos de erro: INVALID_INPUT (persona desconhecido / formato/tableMetric inválido), UNKNOWN_CURRENCY.

• get_account_fee_tier(exchange, purpose, country, apiKey, secret?, password?, pair?, monthlyVolumeUsd?) (v0.39) — a ponte personalizada entre a tabela pública e a taxa real da conta do chamador. Usa uma chave de API somente leitura no endpoint de taxas autenticado da exchange via ccxt (fetchTradingFees quando disponível, senão fetchTradingFee por símbolo) e retorna { exchange, purpose, pair, credential_type, fetch_method, fetched_at, live_fee: {maker_pct, taker_pct}, bundled_fee: {tier, maker_pct, taker_pct, monthly_volume_usd}, delta_vs_bundled_bps: {maker, taker}, security_note, notes } — um gap negativo em bps significa que a conta paga menos que o nível público naquele volume (deduções de BNB/token de taxa no lado do servidor, a janela VIP própria de 30 dias corridos da exchange, taxas negociadas ou promocionais são todas capturadas pela perna ao vivo). Cobertura: 13 de 18 exchanges — Binance, OKX (password = passphrase da API), Gate, Bybit, MEXC, Bitget, KuCoin spot + kucoinfutures (passphrase), Kraken spot + krakenfutures, Coinbase spot (classe coinbaseexchange), BingX, Bitstamp spot, Bitvavo spot (v0.42, classe bitvavo); Hyperliquid aceita apenas o endereço público de carteira 0x em apiKey (sem segredo — consulta o endpoint público userFees). Phemex e BloFin não possuem endpoint de taxas autenticado no ccxt 4.5.x, Finst (v0.43) não expõe API de negociação pública e o ccxt 4.5.x não inclui classe finst, Bitpanda (v0.44) é uma corretora com cotação por spread sem API de negociação pública e sem classe bitpanda, Bison (v0.45) é uma corretora principal cotada pela EUWAX sem classe bison/euwax no ccxt 4.5.78, e perpétuos de Bitstamp/Bitvavo não são modelados (ambas as exchanges são apenas spot) → ACCOUNT_FEES_UNSUPPORTED (falha sem nenhuma chamada de rede). A conformidade roda primeiro: UNKNOWN_EXCHANGE / COUNTRY_BLOCKED / PRODUCT_BLOCKED_IN_COUNTRY / NO_FEE_DATA são retornados antes do uso das credenciais. Falhas em tempo de execução são tipadas e com credenciais removidas: ACCOUNT_MISSING_CREDENTIALS, ACCOUNT_AUTH_FAILED (não repetível — chave/segredo/passphrase errados, restrição de IP, KYC), ACCOUNT_FEE_FETCH_FAILED (retryable: true para rede/timeout/limite de taxa). As credenciais são apenas por requisição — nunca armazenadas em cache, nunca gravadas em logs.

• get_stablecoin_access(asset?, country?, exchange?, language?) (v0.46) — relatório de acesso regional a stablecoins MiCA; totalmente offline. asset padrão é USDT (também USDC/EURC/EURI/EURCV/USDQ/EURQ). Retorna { asset, asset_name?, issuer?, mica_authorized, issuer_note?, fetched_at, data_as_of, restriction: { applies, region?, effective?, venue_trading?, custody_withdrawal?, self_custody_allowed?, note? }, venues: [{ exchange, status, scope, since?, note?, venue_available_in_country }], compliant_alternatives, regulation_note?, advice, data_sources? }. Com um país dentro do EEE30, a restrição de USDT se aplica (cliff 2026-07-01) e todas as 18 exchanges são listadas (delisted+data para as nove exchanges licenciadas no EEE, venue_blocked para as seis CASPs banidas, never_offered para as três exchanges de escopo global); fora do EEE (EUA/GB/CH/…) restriction.applies é falso e apenas linhas de escopo global retornam; exchange restringe a uma linha. Códigos de erro: INVALID_ASSET (ids válidos retornados em suggested_action), UNKNOWN_EXCHANGE, COUNTRY_BLOCKED.

• compare_interface_costs(exchange?, country?, monthly_volume_usd?, language?) (v0.47) — relatório de custo de interface dupla consumidor vs PRO; totalmente offline. Retorna { generated_at, data_as_of, study_summary, venues: [{ exchange, venue_name, available_in_country, consumer: { product_name, fee_model, modeled_one_way_pct, published_one_way_pct?, measured_round_trip_pct?, measured_hidden_spread_pp?, subscription?, tier_credit, measurement }, pro?: { product_name, base_maker_pct, base_taker_pct, published_round_trip_pct }, consumer_vs_pro_round_trip_pp?, consumer_vs_pro_annual_excess_usd?, advice, notes? }], advice, data_sources? }. Evidência: o estudo TUM de ida e volta de €100 com dinheiro real (2025-10..11, seis plataformas da UE licenciadas pela MiCA) replicado pela Frankfurt School (2026-03, 432 idas e voltas/9 plataformas) — Bitvavo 0,58% < BISON 2,58% < app Kraken 5,81% < Bitpanda 6,23% < Coinbase Simple 7,49%; Bitstamp Basic é sinalizado como não verificado (apenas divulgação da própria exchange), Bitpanda/BISON são apenas corretoras (sem interface PRO, pro omitido). exchange restringe a uma exchange, country aplica a barreira de residência (Bitvavo/Bitpanda/BISON bloqueados fora de suas áreas de serviço) e monthly_volume_usd adiciona consumer_vs_pro_annual_excess_usd sempre que o custo unidirecional do consumidor excede a base taker do PRO. Códigos de erro: UNKNOWN_EXCHANGE, COUNTRY_BLOCKED, INVALID_VOLUME.

• get_fee_changes(exchange?, product?, since_month?, limit?, language?) (v0.48) — feed auditável de mudanças na tabela de taxas; totalmente offline. Retorna { generated_at, data_as_of, snapshot_coverage: { months, first?, last?, available }, changes: [{ id, date, exchange, product, kind, tier?, field?, before?, after?, confidence, summary_en, summary_zh?, effective_date?, url?, note?, detected_from_snapshot?, detected_to_snapshot? }], advice }. Duas camadas de evidência: linhas curadas (confidence: high|medium) são verificadas por humanos contra anúncios/páginas de taxas oficiais das exchanges e enviadas em data/fee_changes.json; linhas detectadas são geradas automaticamente ao comparar snapshots determinísticos mensais consecutivos em snapshots/fee_ladders/*.json (apenas no repositório — ausentes no pacote npm, onde snapshot_coverage.available é false) e nunca devem ser tratadas como confirmadas. kind é um de rate | threshold | ladder_structure | promo | token_discount | pricing_model; valores de taxa antes/depois usam a precisão percentual round4 do motor, e os níveis são correspondidos pelo nome do nível. Ordenado por data decrescente e depois por classificação de confiança; product aceita spot|futures|all (um registro all corresponde a qualquer um), since_month recebe YYYY-MM. A captura/revisão mensal é automatizada via workflow do GitHub Actions data-snapshot (PR apenas de revisão — linhas detectadas nunca entram no arquivo curado sem verificação humana). CLI local: npm run snapshot:fees -- snapshot|diff|latest.

Erros são JSON estruturado: { error, code, retryable?, suggested_action? } com códigos como INVALID_INPUT, UNKNOWN_EXCHANGE, COUNTRY_BLOCKED, PRODUCT_BLOCKED_IN_COUNTRY, NO_RESULTS, UNKNOWN_CURRENCY, NO_REFERRAL_LINK, DATA_LOAD_FAILED, ACCOUNT_FEES_UNSUPPORTED, ACCOUNT_MISSING_CREDENTIALS, ACCOUNT_AUTH_FAILED, ACCOUNT_FEE_FETCH_FAILED.

Arquivos de dados

Todos os dados de taxas/VIP/retirada/spread são JSON local. Por padrão, o servidor não faz nenhuma chamada de API externa; requisições fundingMode: "live" buscam taxas de funding atuais e requisições spreadMode: "live" buscam livros de ordens diretamente de endpoints públicos das exchanges via ccxt (melhor esforço, timeout por exchange, fallback incluído), e get_account_fee_tier (v0.39) faz uma requisição autenticada por chamada ao endpoint de taxas da conta da exchange com uma chave somente leitura fornecida pelo chamador (veja Credential handling):

Arquivo	Conteúdo
data/fee_rates.json	Taxas maker/taker por nível VIP, spot + futuros; v0.44 adiciona pricing_model por exchange (order_book|flat|spread) e evidência execution_quality (custo de ida e volta anunciado vs medido independentemente) para exchanges corretoras de spread (v0.44 Bitpanda, v0.45 Bison — a segunda exchange de spread)
data/referral_links.json	URLs de referência, % de desconto do usuário, rebate do operador (interno)
data/token_discounts.json	Regras de desconto BNB / OKB / GT / MX / BGB / KCS / PT + escada de HYPE em staking da Hyperliquid (multiplicativa, staking obrigatório)
data/pair_fees.json	Promoções de taxas por par (MEXC 0-taxa, Binance FDUSD/USDC, Bitget USDC/USDT), precificação por faixa de spread da Bitpanda v0.44 (0,99% pares BTC/stablecoin vs o destaque de 1,49%, não promocional) e faixas da Bison v0.45 (1,25% BTC/EUR + ETH/EUR vs o destaque de 1,75%, não promocional)
data/funding_rates.json	Taxa de funding média incluída + intervalo de liquidação (fallback do modo ao vivo)
data/spread_baseline.json	Spread bid-ask completo típico por exchange (BTC) + multiplicadores para grandes/mid-alt (estudos de snapshot do livro de ordens 2026; fallback do modo ao vivo); v0.44 fixa Bitpanda em 0 bps e v0.45 fixa Bison em 0 bps porque o prêmio embutido de cada exchange É o spread (anti-dupla contagem)
data/withdrawal_fees.json	Taxas de retirada por exchange para 16 ativos em rotas nativas e multi-cadeia (TRC-20/ERC-20/BEP20/Arbitrum/Optimism/Base/Polygon/Avalanche C/Solana/TON/AssetHub), snapshot asset_prices_usd 2026-09-12 para conversão USD, flags suspended para carteiras pausadas (ago–set 2026)
data/fx_rates.json	Taxas de câmbio de exibição estáticas (base USD)
data/country_restrictions.json	Exchanges bloqueadas/permitidas por país, barreiras negativas por produto (product_blocked), tabelas de associação de regiões nomeadas (regions, ex.: EEE30), allowlists positivas de região por produto (product_region_gates, v0.40), proibições de região pós-cliff MiCA (region_blocked, product_region_blocked, v0.41) e whitelists positivas de área de serviço por exchange (region_allowed, v0.42 Bitvavo e v0.43 Finst — ambas apenas EEE; v0.44 Bitpanda = EEE+GB via chave de região GB de membro único; v0.45 Bison = EEE+CH via chave de região CH de membro único)
data/fiat_routes.json	Trilhos fiduciários diretos operados pela exchange (cartão/ACH/SEPA/FPS/wire/SWIFT/PIX) por exchange, moeda, região e direção, com taxas percentual+fixa+mín/máx e ETAs (gateways/P2P excluídos)
data/personas.json	Sete personas de trader ancoradas em pesquisa para analyze_persona: predefinições comportamentais (volume, participação maker, horas de manutenção, tamanho de lote, hábitos de retirada/fiduciário) com descrições bilíngues, premissas e fontes de pesquisa (estudos de varejo 2026)
data/token_prices.json	Preços estáticos de snapshot USD 2026-09 para tokens nativos (BNB/OKB/GT/MX/BGB/KCS/HYPE) usados para estimar o custo de oportunidade de manter um token para descontos de taxas; substituível por chamada via tokenPriceUsd
data/stablecoin_access.json	Registro de stablecoins MiCA v0.46: autorização de emissor/EMT por ativo (USDT não autorizado; USDC/EURC/EURI/EURCV/USDQ/EURQ autorizados), regras de região (restrição de negociação de USDT no EEE30, cliff 2026-07-01, direitos de custódia/retirada/autocustódia, alternativas) e regras por exchange em todas as 18 exchanges (delisted + data desde / never_offered / venue_blocked; escopo eea vs global), com fontes e last_verified 2026-09
data/interface_costs.json	Modelo de custo de interface dupla v0.47 para compare_interface_costs: por exchange (kraken/coinbase/bitstamp/bitvavo/bitpanda/bison) o produto consumidor (nome, modelo de taxa, taxas unidirecionais publicadas, isenções de assinatura) vs o benchmark PRO do livro de ordens (maker/taker base, ida e volta publicada), idas e voltas medidas com dinheiro real pela TUM e pp de spread oculto com metadados de replicação da Frankfurt School, e last_verified 2026-09
data/fee_changes.json	Feed curado de mudanças na tabela de taxas v0.48 para get_fee_changes: mudanças verificadas por humanos em taxa/limite/escada/promo/desconto de token/modelo de precificação com data efetiva, URL de fonte oficial, resumo bilíngue e antes/depois estruturado onde a fonte informa números; last_verified 2026-09 (histórico pré-2026-09 não é reconstruível de fontes primárias — apenas registros com evidência oficial são semeados). O repositório também carrega snapshots determinísticos mensais apenas no repositório em snapshots/fee_ladders/YYYY-MM.json (NÃO enviados no pacote npm) que o motor difere em linhas confidence: "detected"

Cada arquivo carrega last_verified (AAAA-MM) e sources (URLs oficiais de páginas de taxas, estudos de medição ou ressalvas). Caminhos de substituição via variáveis de ambiente: FEE_RATES_PATH, REFERRAL_LINKS_PATH, TOKEN_DISCOUNTS_PATH, PAIR_FEES_PATH, FUNDING_RATES_PATH, SPREAD_BASELINE_PATH, WITHDRAWAL_FEES_PATH, FX_RATES_PATH, COUNTRY_RESTRICTIONS_PATH, FIAT_ROUTES_PATH, PERSONAS_PATH, TOKEN_PRICES_PATH, STABLECOIN_ACCESS_PATH, INTERFACE_COSTS_PATH, FEE_CHANGES_PATH (arquivo) e FEE_SNAPSHOTS_PATH (diretório de snapshots mensais de escada YYYY-MM.json; ausente/ilegível degrada para uma lista vazia — o feed curado ainda funciona).

Nota de precisão: taxas de funding e taxas de retirada flutuam; tabelas VIP mudam sem aviso. Trate as saídas como estimativas e verifique via get_data_sources antes de decisões financeiras.

Credential handling (v0.39 get_account_fee_tier)

A única ferramenta que faz chamadas autenticadas é get_account_fee_tier, e apenas quando é explicitamente invocada. Propriedades de segurança:

• Somente chaves somente leitura — sempre gere uma chave com permissões de informação/leitura e nenhuma permissão de negociação, saque ou transferência; a ferramenta nunca precisa delas.
• Por solicitação, nunca armazenadas — as credenciais existem apenas durante a duração da chamada. Deliberadamente não há cache de resultados (os caches de TTL de dados públicos nunca recebem material de chave), nada é gravado em disco e as credenciais nunca são retornadas na resposta.
• Redigidas em todos os lugares — o log de stderr [audit] redige os argumentos apiKey / secret / password / passphrase / walletAddress (***REDACTED***) antes da serialização, e as strings de erro da exchange são limpas de valores literais de credenciais e parâmetros signature=.
• Conformidade em primeiro lugar — as verificações de local/país/produto são executadas antes de qualquer chave ser usada, então uma solicitação bloqueada nunca toca um endpoint de autenticação da exchange.
• Hyperliquid precisa apenas do endereço público da carteira (a consulta de taxa é uma chamada pública userFees); nenhuma chave privada é solicitada.

Exemplos

> User: I'm in Japan, trade 100k USDT futures/month, mostly limit orders, and hold positions ~16h. Which exchange?

Agent → recommend_exchange(purpose="futures", country="JP", volume=100000,
                           makerShare=0.8, holdingHours=16)
Server → {
  "best": { "exchange": "...", "score": 100, "weighted_fee_rate": ...,
            "reasons": [...], "tradeoffs": [...], "referral_url": "..." },
  "alternatives": [...],
  "advice": "Register via the ... link to lock 20% off ...",
  "data_as_of": "2026-09"
}

> User: 数据是哪来的？费率多久更新一次？

Agent → get_data_sources()
Server → { "data_as_of": "2026-09",
           "files": [{ "file": "fee_rates.json", "last_verified": "2026-09",
                       "sources": [{ "name": "Binance fee schedule",
                                     "url": "https://www.binance.com/en/fee/schedule" }, ...] }, ...] }

> User: 我在币安每月交易 100 万U期货，持仓约 720 小时，每年提 12 次 USDT，一年真实成本多少？升 VIP1 能省多少？

Agent → calculate_annual_cost(exchange="binance", purpose="futures", country="JP",
                              monthlyVolumeUsd=1000000, holdingHours=720,
                              withdrawalAsset="USDT", withdrawalNetwork="TRC-20",
                              withdrawalsPerYear=12)
Server → {
  "tier": "Regular",
  "annual_trading_fee": 4800,
  "annual_funding_cost": 108000,
  "annual_withdrawal_cost": 18,
  "annual_total_cost": 112818,
  "upgrade": { "next_tier": "VIP1", "requires_volume_usd": 15000000,
               "annual_savings": 960,
               "hint": "Reach VIP1 via $15,000,000 30-day volume; estimated annual trading-fee saving $960 ..." }
}

> User: 我主要在 MEXC 现货刷 BTC/USDT，听说 0 手续费是真的吗？其他所呢？

Agent → compare_exchange_fees(purpose="spot", country="JP", pair="BTC/USDT", makerShare=0.5)
Server → [
  { "exchange": "mexc", "tier": "Standard", "effective_maker": 0, "effective_taker": 0,
    "weighted_rate": 0, "pricing_basis": "pair",
    "pair_note": "MEXC 0-fee program: all spot pairs trade at 0% maker + 0% taker ..." },
  { "exchange": "okx", ..., "pricing_basis": "account_tier" },
  ...
]

> User: 现在 BTC 永续各交易所资金费率多少？按实时费率我持 10 万U多单 16 小时要付多少资金费？

Agent → get_funding_rates(fundingMode="live", fundingPair="BTC/USDT")
Server → {
  "pair": "BTC/USDT", "mode": "live",
  "rates": [
    { "exchange": "binance", "rate_pct": 0.0124, "interval_hours": 8,
      "source": "live", "funding_timestamp": "2026-09-12T00:00:00.000Z" },
    { "exchange": "kraken", "rate_pct": 0.01, "interval_hours": 8,
      "source": "bundled", "note": "..." }
  ],
  "failures": [{ "exchange": "kraken", "error": "Connect Timeout ...", "fallback": "bundled" }]
}

Agent → calculate_savings(exchange="binance", volume=100000, type="futures",
                          country="JP", holdingHours=16,
                          fundingMode="live", fundingPair="BTC/USDT")
Server → { "funding_cost": 24.8, "funding_source": "live",
           "funding_rate_ts": "2026-09-12T00:00:00.000Z",
           "funding_pair": "BTC/USDT", ... }

> User: 我一笔 5 万U的 BTC 市价吃单，各交易所点差加滑点实际要付多少？25 万U的大单呢？

Agent → get_execution_cost(tradeSizeUsd=50000, pair="BTC/USDT",
                           purpose="futures", side="buy", spreadMode="live")
Server → {
  "pair": "BTC/USDT", "mode": "live", "trade_size_usd": 50000,
  "costs": [
    { "exchange": "binance", "spread_bps": 1.0, "crossing_bps": 0.5,
      "slippage_bps": 0.3, "total_bps": 0.8, "cost_usd": 4,
      "levels_consumed": 3, "fully_filled": true, "source": "live",
      "symbol": "BTC/USDT:USDT", "book_timestamp": "2026-09-12T..." },
    { "exchange": "kraken", "spread_bps": 5, "crossing_bps": 2.5,
      "slippage_bps": 0, "total_bps": 2.5, "cost_usd": 12.5,
      "source": "bundled", "pair_class": "majors" }
  ],
  "failures": [{ "exchange": "kraken", "error": "Connect Timeout ...",
                 "fallback": "bundled" }]
}

Agent → compare_total_cost(purpose="futures", country="JP", volume=100000,
                           tradeSizeUsd=250000, spreadMode="live", side="buy")
Server → [ { "exchange": "binance", "trading_fee": 1000,
             "spread_cost": 12.5, "slippage_cost": 28.2,
             "spread_source": "live", "total_cost": 1040.7 }, ... ]

> User: 我在德国，想入 1000 欧元，刷卡和 SEPA 转账各所收多少？哪个最便宜？

Agent → get_fiat_cost(direction="deposit", currency="EUR", amount=1000, country="DE")
Server → {
  "direction": "deposit", "currency": "EUR", "amount": 1000, "amount_usd": 1086.96,
  "fx_rate": 0.92, "data_as_of": "2026-09",
  "best": { "exchange": "binance", "method": "sepa", "fee": 0,
            "fee_usd": 0, "effective_pct": 0, "net": 1000 },
  "saving_vs_worst_usd": 5.43,
  "exchanges": [
    { "exchange": "binance", "available": true, "cheapest_method": "sepa",
      "cheapest_fee_usd": 0,
      "routes": [ { "method": "sepa", "fee": 0, "fee_usd": 0, "effective_pct": 0,
                    "net": 1000, "eta": "1-2 business days" },
                  { "method": "card", "fee": 20, ... } ] },
    { "exchange": "gate", "cheapest_method": "sepa",
      "routes": [ { "method": "sepa", "fee": 5, "effective_pct": 0.5, ... } ] },
    ...
  ],
  "advice": "binance offers a free sepa deposit for EUR — 1000 EUR arrives in full. ..."
}

> User: 我要提 USDT 到 TRC-20，8 家所分别收多少？不提网络的话哪家最便宜？最近有哪些链暂停了？

Agent → get_withdrawal_fees(asset="USDT", network="TRC-20")
Server → {
  "asset": "USDT", "network": "TRC-20", "asset_price_usd": 1,
  "data_as_of": "2026-09",
  "exchanges": [
    { "exchange": "mexc", "supported": true,
      "networks": [{ "network": "TRC-20", "fee": 0.5, "fee_usd": 0.5, "available": true }],
      "cheapest_network": "TRC-20", "cheapest_fee_usd": 0.5 },
    { "exchange": "bybit", ..., "cheapest_fee_usd": 1 },
    { "exchange": "binance", ..., "cheapest_fee_usd": 1.5 },
    ...
  ],
  "best": { "exchange": "mexc", "network": "TRC-20", "fee": 0.5, "fee_usd": 0.5 },
  "saving_vs_worst_usd": 1,
  "advice": "Cheapest USDT TRC-20 withdrawal: mexc charges 0.5 USDT (about $0.5) ..."
}

Agent → get_withdrawal_fees(asset="ETH")   // no network: cheapest open L2 per venue
Server → {
  "asset": "ETH", "asset_price_usd": 2512.03,
  "best": { "exchange": "mexc", "network": "Base", "fee": 0.0000013, "fee_usd": 0.0033 },
  "exchanges": [ { "exchange": "binance", "cheapest_network": "Optimism",
                   "cheapest_fee_usd": 0.0377, "networks": [ ... ] }, ... ],
  "saving_vs_worst_usd": 0.32
}

Desenvolvimento

npm test          # vitest unit tests (457 tests: 361 tools + 50 live + 28 http + 13 account + 3 polyfill + 2 version)
npm run build     # tsc → dist/
npm run audit:data            # offline data-consistency gate (dates, sources, ladder monotonicity, coverage)
node scripts/smoke-test.mjs   # end-to-end MCP stdio smoke test (68 requests)
npm run smoke:http            # end-to-end Streamable HTTP smoke test
npm run inspector # MCP Inspector UI for manual testing

O mesmo pipeline de auditoria → build → teste → smoke HTTP, além de uma verificação de artefato/instalação npm pack, é executado no CI em cada push e pull request (Node 18/20/22, .github/workflows/ci.yml). O histórico de versões está em CHANGELOG.md.

Licença

MIT