Uma API key de exchange é um par composto por API Key e API Secret. Com essa key, programas e serviços trabalham com uma conta via API: leem o saldo, abrem e fecham trades e executam outras operações permitidas para essa key sem fazer login no painel web.
Objetivo do material: descrever as restrições que uma exchange aplica a solicitações API: verificação de assinatura por API Secret, direitos da key (permissions), vinculação da fonte da solicitação a uma IP whitelist, restrições de saque por whitelist de endereços e isolamento de saldo por sub-accounts. Essas restrições reduzem o risco de que um leak do par API Key + API Secret leve ao saque de ativos ou a trades com prejuízo.
🧭 Como funciona o controle de acesso API em exchanges crypto
API keys são usadas por trading bots, terminais, serviços de relatórios e integrações internas. Uma exchange executa uma solicitação API somente depois de verificar a assinatura (API Secret), os direitos da operação (permissions), o endereço IP da fonte (IP whitelist) e o tempo da solicitação (timestamp e recvWindow). A verificação de tempo bloqueia a repetição posterior da solicitação, mesmo que a solicitação tenha sido interceptada.
O risco de API é reduzido pelas configurações da key. IP whitelist aceita solicitações apenas de endereços IP especificados. Permissions limita o conjunto de operações que a exchange executará com a key. A whitelist de endereços de saque limita a lista de destinatários. Sub-accounts separam saldo e keys entre sub-accounts, para que uma única key não tenha acesso a todos os ativos da conta.
🔍 Como uma exchange verifica uma solicitação API: assinatura, direitos, IP e tempo
Uma API key consiste em API Key (identificador da key) e API Secret (secret para assinatura). A assinatura confirma à exchange que a solicitação foi formada usando API Secret e não foi alterada no caminho.
- Formação dos parâmetros da solicitação para o API endpoint da exchange (o endereço API que aceita uma operação específica)
- A solicitação define a operação: abrir ou cancelar uma ordem, obter saldo, executar um transfer ou iniciar um saque.
- A solicitação contém uma marca temporal (timestamp) e, às vezes, uma janela de tempo permitida (recvWindow). A exchange compara esses valores com seu próprio tempo e rejeita a solicitação se ela sair do intervalo permitido.
- Assinatura dos parâmetros da solicitação via HMAC
- HMAC é uma assinatura hash gerada com uma secret key. A string de parâmetros é assinada com API Secret.
- A exchange recalcula o HMAC com os mesmos parâmetros e compara a assinatura. Uma divergência significa que o remetente não possui API Secret ou que os parâmetros foram alterados.
- Verificação das restrições da key e decisão de execução
- Permissions define quais operações são permitidas para a key (read/trade/transfer/withdraw na maioria das exchanges centralizadas, CEX).
- IP whitelist limita as fontes das solicitações. A exchange rejeita uma solicitação se o IP do remetente não estiver incluído na whitelist da key.
- Execução da operação e retorno do resultado
- Se os direitos forem insuficientes, a exchange retorna uma rejeição e não executa a operação, mesmo com uma assinatura correta.
- Se o IP não corresponder, a exchange retorna uma rejeição na etapa de autorização e não passa para uma operação de trading ou saque.
Componentes de acesso API controlados pela exchange
A exchange reduz o risco de API por três verificações em cada solicitação: assinatura via API Secret, permissions para operações e IP whitelist para a fonte da solicitação.
- API Secret é armazenado apenas em um cofre de secrets e na memória do processo que assina solicitações.
- Permissions são ativadas conforme a tarefa da key: leitura para relatórios, trading para um bot, saque apenas para pagamentos operacionais.
- IP whitelist contém apenas os IPs dos servidores que realmente enviam solicitações, para que a lista não amplie a superfície de ataque.
Se um atacante obtiver uma API Key sem API Secret, a exchange rejeitará a solicitação por assinatura inválida. Se um atacante obtiver API Key e API Secret, a exchange rejeitará a solicitação quando permissions não permitir a operação ou o IP não estiver na whitelist.
🎯 Quais perdas são possíveis via API: saque, transfers e prejuízo de trading
O dano via API depende das permissions ativadas e do saldo disponível para essa key. Uma trade-only key traz menor risco em um sub-account com pequeno saldo operacional e maior risco em um sub-account com capital principal.
Três cenários executados pela exchange via API
Perdas via API surgem por saque, transfer interno ou trades que geram prejuízo ao preço de execução.
- Saque direto: uma key com withdraw permission inicia um saque para um endereço que a exchange permitirá após suas verificações e regras de whitelist.
- Transfer interno: uma key com transfer permission move ativos entre wallets de produto ou entre sub-accounts, se a exchange permitir essas operações via API.
- Prejuízo de trading sem saque: uma key com trade permission coloca ordens em um par de baixa liquidez e executa trades a um preço pior, criando prejuízo por slippage, spread e comissões.
Withdraw permission desativada remove o saque direto. Trade permission continua sendo uma fonte de prejuízo se um saldo grande estiver armazenado na trading wallet e a key não estiver limitada por IP e por instrumentos.
Sinais após os quais uma verificação de API se torna necessária
- Apareceram ordens que não correspondem à lógica do trading system e ao cronograma de lançamento.
- Apareceram transfers entre wallets ou sub-accounts sem motivo operacional.
- Nas configurações da key apareceram novas permissions ou a IP whitelist foi removida.
- Nos logs do trading system apareceram erros de assinatura e a frequência de solicitações aumentou com o código inalterado.
🌐 IP whitelist: vinculação da key ao servidor de origem das solicitações
IP whitelist obriga a exchange a aceitar solicitações apenas de endereços IP indicados previamente. Se API Secret entrar no código, nos logs, nos backups ou em um serviço de terceiros, o atacante não conseguirá enviar uma solicitação de um IP que não esteja na whitelist.
Escolha de uma fonte estável para solicitações API
- Um VPS (servidor virtual privado) com IP público fixo é adequado para IP whitelist e para a operação contínua do trading system.
- Internet doméstica com IP dinâmico não é adequada, porque a mudança de IP causa rejeições de solicitações API até a atualização da whitelist.
Configuração de IP whitelist para uma API key
- IP whitelist inclui o IP do servidor do trading system e do servidor de backup, se o servidor de backup for realmente usado.
- Se a exchange oferecer suporte a CIDR (notação de sub-rede, por exemplo 203.0.113.10/32), define-se o menor intervalo para não ampliar a lista de fontes.
Verificação da resiliência do acesso API
- Uma API key de backup em um IP separado é usada durante migração de infraestrutura e mudança de endereço do servidor.
- O procedimento de atualização da IP whitelist é documentado com antecedência, para que a mudança de IP não coincida com a perda de controle sobre ordens.
Em infraestrutura cloud, solicitações podem sair para a internet via NAT (tradução de endereços na borda da rede). Nesse caso, o IP externo visto pela exchange pode diferir do IP do container ou da máquina virtual. Na IP whitelist, indica-se o egress IP (IP externo do tráfego de saída), caso contrário a exchange rejeitará as solicitações.
IP whitelist não protege contra comprometimento do VPS. Se o servidor for tomado, um atacante enviará solicitações do mesmo IP, portanto a proteção de acesso ao VPS e o controle de atualizações continuam fazendo parte da proteção API.
IP whitelist bloqueia solicitações de servidores externos, porque a exchange compara o IP de origem com a whitelist e rejeita a solicitação antes de executar uma operação de trading ou saque.
🔑 Permissions: quais direitos são concedidos à key para uma tarefa específica
Permissions define quais API endpoints a exchange permitirá chamar com essa key. Os nomes dos direitos dependem da exchange, mas o modelo geralmente é o mesmo: read para leitura, trade para ordens, transfer para transfers internos e withdraw para saque em blockchain.
| Tarefa | Permitir | Bloquear | Operação bloqueada |
|---|---|---|---|
| Screener/analytics | Read | Trade; Transfer; Withdraw | Colocação de ordens e movimentação de ativos |
| Trading bot | Read; Trade | Withdraw | Saque direto de fundos via API |
| Relatórios | Read | Trade; Transfer; Withdraw | Operações em caso de comprometimento do serviço de relatórios |
| Transfers operacionais | Read; Transfer | Trade; Withdraw | Operações de trading e saque em blockchain |
Read-only key para monitoramento e relatórios
Uma read-only key é usada quando o sistema precisa ler saldos, histórico de trades e status de posições, mas não pode alterar o estado da conta.
- Uma read-only key bloqueia a colocação e o cancelamento de ordens, porque a exchange rejeita trading endpoints para essa key.
- IP whitelist limita o acesso aos dados a um servidor específico e bloqueia solicitações de IPs externos em caso de leak de API Secret.
- Uma read-only key separada para relatórios separa o risco do serviço de relatórios do risco da trading key.
Uma read-only key expõe saldo e histórico, mas não permite saques nem trades, porque a exchange rejeita endpoints trade/transfer/withdraw.
Trade key para um trading system sem saque
Uma trade key é usada para colocar e cancelar ordens. Withdraw permission não é necessária para operações de trading.
- Trade permission dá acesso ao gerenciamento de ordens e posições dentro dos mercados da conta.
- Withdraw permission desativada bloqueia saques, porque a exchange rejeita withdrawal endpoints para essa key.
- IP whitelist vincula a key ao servidor do trading system e bloqueia solicitações de máquinas externas em caso de leak de API Secret.
Uma trade-only key cria risco para os fundos na trading wallet, portanto o trading sub-account geralmente mantém saldo operacional, não o capital principal.
Transfer key para movimentações internas
Uma transfer key é usada para transfers dentro da exchange: entre wallets de produto ou entre sub-accounts, se a exchange permitir essas operações via API.
- Transfer permission permite executar transfers internos que não saem para a blockchain.
- Trade permission desativada exclui trades, porque a transfer key não pode criar ordens.
- Withdraw permission desativada exclui saque em blockchain em caso de comprometimento da transfer key.
Separar transfer e trade em keys diferentes reduz o dano em caso de leak, porque uma key não dá acesso simultâneo a trades e à movimentação de ativos.
Permissions define qual operação a exchange permitirá com essa key. Permissions extras ampliam o conjunto de ações que a exchange executará com uma key comprometida, por isso os direitos são ativados apenas para um processo específico.
🏷️ Proteção de saque: whitelist de endereços, confirmações e limites
Withdraw permission permite que uma API key inicie saque de fundos do saldo da exchange para a blockchain. A proteção de saque se baseia na whitelist de endereços do destinatário, no controle de alteração da whitelist e nos limites de saque.
Em integrações de trading, withdraw permission geralmente é desativada. Ordens, cancelamentos e leitura de saldo são executados dentro da exchange e não exigem saque para a rede. Para monitoramento e relatórios, o direito read é suficiente. Para trading algorítmico, o direito trade é suficiente.
Exemplo: um trading bot opera com uma key com trade permission e sem withdraw permission. Em caso de comprometimento da key, o atacante poderá abrir e fechar trades via trading endpoints. A exchange rejeitará a solicitação de saque porque a key não tem withdraw permission.
A whitelist de endereços limita o destinatário do saque: a exchange envia fundos apenas para endereços adicionados previamente. Em muitas exchanges, adicionar um endereço à whitelist exige 2FA (autenticação de dois fatores) e confirmação por um canal separado, por exemplo email, aplicativo ou hardware key. Nesse caso, o saque para um novo endereço depende não apenas da API key, mas também do controle desses canais de confirmação.
O atraso na alteração da whitelist (security lock, hold) não ativa o endereço adicionado imediatamente. Com o atraso ativado, o saque para um novo endereço fica bloqueado durante o período de hold, portanto a adição do endereço pode ser percebida antes do primeiro saque.
A conexão API de trading bots, trade-only keys e IP whitelist é explicada no material “Ganhos com trading bots crypto”.
Limites de saque restringem a soma das perdas se um atacante obtiver uma key que passe pelas verificações de whitelist e confirmações. O limite diário é definido para valores de pagamentos operacionais regulares, não para o saldo total da conta, para que um único ciclo de saque não permita esvaziar todo o depósito.
Comprometimento do email aumenta o risco, porque em muitas exchanges confirmações de adição de endereços e redefinições de segurança dependem de email, incluindo links de confirmação e notificações sobre alteração da whitelist.
Withdraw permission sem whitelist de endereços torna o leak de API key um canal direto de saque em blockchain. Withdraw permission com whitelist de endereços e atraso na alteração da whitelist transfere o risco crítico para o comprometimento dos canais de confirmação. Limites de saque restringem a soma das perdas se as demais restrições forem contornadas.
🛡️ Sub-accounts: isolamento de saldo, keys e processos
Sub-accounts separam saldo e API keys dentro de uma exchange. Em caso de leak da key, as operações ficam limitadas aos ativos de um sub-account específico.
- Separação de storage e trading em diferentes sub-accounts
- O storage sub-account mantém o capital principal e não usa trading API keys permanentes.
- Trading sub-accounts mantêm saldos operacionais para bots e estratégias específicos.
- Controle de transfers internos via API
- Desativar transfer permission nas trading keys reduz a possibilidade de movimentar ativos em caso de leak da trading key.
- Uma transfer key dedicada é usada quando transfers internos fazem parte do processo operacional.
- Restrição de instrumentos da key quando há suporte a whitelist de pares de trading
- Whitelist de pares de trading bloqueia trades em instrumentos que não pertencem ao trading system.
- A restrição de pares reduz o risco de prejuízo em mercados de baixa liquidez.
Modelo de isolamento para vários trading systems
O modelo de isolamento separa saldo por sub-accounts e separa acesso por API keys, permissions e IP whitelist.
- Um trading system em uma exchange opera por meio de um sub-account separado e uma trade-only key vinculada ao IP do VPS.
- Relatórios são conectados com uma read-only key em um servidor separado, para que um leak no reporting não exponha a trading key.
- Transfers operacionais são executados com uma transfer key sem trade e withdraw permissions.
Em caso de leak da key do trading system, a exchange executa operações apenas dentro do saldo do seu sub-account, portanto as perdas ficam limitadas ao saldo operacional.
🗄️ Armazenamento de secrets e rotação: como API Secret vaza da infraestrutura
API Secret vaza com mais frequência não pela exchange, mas pela infraestrutura do trading system: repositórios de código, pipelines CI/CD (processos automatizados de build e deployment), logs de aplicações, dumps de bancos de dados, screenshots e backups. O gerenciamento de secrets define os locais de armazenamento do API Secret e as funções que podem acessá-lo.
API Secret não é armazenado no código da aplicação. O valor do secret é inserido na inicialização do serviço a partir de um armazenamento protegido e não é salvo nos arquivos do projeto nem no repositório. No código e na configuração permanece uma referência ao secret, não seu valor.
Exemplo: um trading bot é implantado via CI/CD. No repositório é armazenado apenas o nome do secret, e o valor do API Secret é inserido na etapa de deployment a partir de um armazenamento protegido. Em caso de leak do código e do histórico de commits, API Secret não está presente neles.
Em production, API Secret é armazenado em um secret manager — serviço que mantém secrets em formato criptografado e os fornece apenas a processos com permissão via IAM (gerenciamento de acesso por funções). Esse modelo separa production secrets de ambientes dev e serviços de teste.
As causas comportamentais de erros ao lidar com risco e plano de trading são analisadas no material “Psicologia do trader”.
A rotação de API keys reduz o risco de um leak de longa duração. A rotação inclui criar uma nova key na exchange, alternar o sistema para o novo API Secret e revogar a key antiga para que a exchange deixe de aceitar assinatura pelo secret antigo.
A alternância é planejada para um período sem posições abertas e ordens limite ativas, para que a troca de API Secret não interrompa o gerenciamento de ordens e do risco.
Regras mínimas de armazenamento de API Secret
- API Secret é armazenado em um secret manager ou em armazenamento criptografado com controle de acesso.
- API Secret não entra em Git, Docker image, CI artifacts nem backups em texto aberto.
- O production secret não é acessível a partir do ambiente dev e não é acessível a funções que não executam o trading system.
- A rotação inclui revogar a key antiga após a alternância, para que o secret antigo deixe de funcionar no lado da exchange.
Permissions, IP whitelist e whitelist de endereços protegem no lado da exchange, enquanto secret management reduz o risco de leak de API Secret do código e dos logs no lado da infraestrutura.
🧩 Terminais e bots de terceiros: como a conexão afeta o risco
Um serviço de terceiros recebe API Key e API Secret para assinar solicitações em nome da conta. Se o serviço aceita a key no painel web, API Secret é armazenado na infraestrutura do provedor. Em um incidente no provedor, o atacante poderá assinar solicitações e passar pela verificação de assinatura no lado da exchange.
✅ Sinais de risco controlado
- O serviço opera com read-only e trade-only keys e não exige withdraw permission para trading e relatórios.
- O serviço mostra um log de ações API: ordens criadas e endpoints chamados.
- O serviço oferece suporte à conexão por um sub-account separado com saldo operacional limitado.
❌ Sinais de risco elevado
- O serviço exige withdraw permission para funções que não estão relacionadas a pagamentos operacionais.
- O serviço exige desativar IP whitelist e não oferece um modelo com agente no lado do usuário e IP fixo.
- O serviço não fornece histórico de ações API, portanto a investigação depende de sinais indiretos.
Exemplo de configuração: sinais e relatórios usam uma read-only key, operações de trading usam uma trade-only key em um sub-account com saldo operacional, e saques via API ficam desativados.
Um serviço de terceiros não cancela as restrições da exchange. Sub-account, IP whitelist, permissions mínimas e withdraw permission desativada limitam o risco ao saldo operacional.
🧯 Reação a um leak da key: parar execução e registrar rastros
Quando há suspeita de leak do par API Key + API Secret, o risco se desenvolve rapidamente, porque a exchange executa operações imediatamente após verificar assinatura, direitos, IP e tempo da solicitação. A reação começa com a interrupção da autorização pela key e o registro dos rastros de operações.
- Revogação da key no lado da exchange
- Desativar ou excluir a key interrompe a aceitação de solicitações assinadas por essa API Key.
- Desativar todas as keys do sub-account é usado se a fonte do leak não foi determinada.
- Registro dos rastros de operações
- A lista de ordens abertas e o histórico de trades do período de anomalia mostram quais operações foram executadas.
- O histórico de saques e alterações da whitelist de endereços mostram tentativas de saque e preparação de endereços.
- Fechamento de canais adicionais de acesso à conta
- Alteração de senha e verificação de 2FA reduzem o risco de entrada na interface web.
- A verificação da segurança do email é necessária, porque confirmações de saque e alterações de whitelist costumam depender de email.
- Restauração do acesso operacional
- Uma nova key é criada com permissions mínimas e IP whitelist no servidor atual.
- API Secret é atualizado no secret manager para que o secret antigo deixe de ser usado.
A revogação da key interrompe a execução de ações, porque a exchange deixa de aceitar assinatura por essa API Key, mesmo que as solicitações continuem chegando.
✅ Configuração que reduz o risco de saque em caso de leak da key
O risco de saque após o leak do par API Key + API Secret diminui quando a trade key não tem withdraw permission, as solicitações são limitadas por IP whitelist e o capital principal é separado do trading sub-account.
Conjunto mínimo de parâmetros para a trade key de um trading system
- O trading system opera em um VPS com IP fixo, e esse IP é adicionado à IP whitelist da key.
- A key tem permissions read + trade e não tem withdraw permission.
- O trading sub-account contém saldo operacional, enquanto o capital principal é armazenado separadamente sem trading keys permanentes.
- API Secret é armazenado em um secret manager ou em armazenamento criptografado e não entra em repositórios nem logs.
IP whitelist, permissions mínimas, whitelist de endereços para saques raros e isolamento por sub-accounts limitam o dano ao saldo operacional e reduzem o risco de saque em blockchain por uma key comprometida.
❓ FAQ sobre segurança de API keys
Por que IP whitelist protege mesmo em caso de leak de API Secret?
A exchange compara o IP de origem da solicitação com a IP whitelist da key e rejeita a solicitação se o IP não corresponder. A assinatura HMAC pode estar correta, mas a operação não será executada porque a verificação de IP acontece no lado da exchange.
Quando withdraw permission é realmente necessária?
Withdraw permission é necessária para pagamentos operacionais automáticos em blockchain. Para trading, monitoramento e relatórios, withdraw permission não é necessária, porque esses processos usam endpoints de trading e read dentro da exchange.
Por que uma trade-only key pode levar a perdas sem saque?
Uma trade-only key permite colocar ordens. Com acesso a uma trade-only key, o atacante pode executar trades a um preço pior em um par de baixa liquidez e criar prejuízo por slippage, spread e comissões quando há saldo grande na trading wallet.
Por que usar um sub-account separado para cada trading system?
Sub-account limita o saldo disponível para a key. Em caso de leak da key do trading system, o dano é limitado aos ativos desse sub-account, porque a exchange executa operações dentro do saldo do sub-account específico.
Como rotacionar keys sem perder controle sobre as ordens?
A rotação inclui criar uma nova key, alternar o trading system para o novo API Secret e revogar a key antiga. A alternância é planejada para um período sem posições abertas e ordens limite ativas, para que a troca de key não interrompa o gerenciamento de ordens.
Como o risco é limitado ao conectar um terminal de terceiros?
O risco é limitado por uma trade-only key em um sub-account com saldo operacional, IP whitelist (se as solicitações passam por um agente no lado do usuário) e withdraw permission desativada quando o terminal não participa de saques operacionais.
🧷 Como restrições API reduzem o risco de saque e dano de trading
O risco de API depende das operações permitidas e das verificações que a exchange aplica a cada solicitação: assinatura (API Secret), permissions, IP whitelist e parâmetros de tempo da solicitação.
- Withdraw permission desativada bloqueia saque em blockchain via API, porque a exchange rejeita withdrawal endpoints para uma key sem esse direito.
- Whitelist de endereços de saque limita o destinatário, porque a exchange envia fundos apenas para endereços adicionados previamente.
- IP whitelist limita a fonte das solicitações, porque a exchange rejeita solicitações de IPs que não estão na lista da key, mesmo com assinatura correta.
- Sub-accounts limitam o volume de perdas, porque a key recebe acesso ao saldo de um sub-account específico, não a todos os ativos da conta.