API de corretora cripto: como conectar robôs com segurança

A API de uma corretora cripto é a porta de entrada para robôs: por ela, um programa consulta preços e saldo, envia e cancela ordens sem passar pelo site ou aplicativo. Para conectar um robô com segurança, você cria uma chave com o mínimo de permissões (leitura e negociação, nunca saque), restringe o acesso aos IPs do seu servidor, guarda o segredo fora do código e testa tudo em ambiente demo antes da conta real.

Em resumo: a API key identifica a conta e a secret key assina cada requisição com HMAC SHA256. Quem tem as duas pode operar no seu nome. Por isso, permissões mínimas, lista de IPs, variáveis de ambiente e revisão periódica das chaves são obrigatórias. O caso 3Commas, em 2022, mostrou o custo de chaves vazadas.

O que é uma API de corretora e o que dá para fazer com ela?

API (interface de programação de aplicações) é um conjunto de endereços que aceitam comandos em formato padronizado. Nas corretoras cripto, existem dois tipos de acesso:

Além da API REST (pedido e resposta), muitas corretoras oferecem WebSocket, que envia cotações e atualizações de ordens em tempo real. Robôs de Python para trading, alertas do TradingView por webhook, ferramentas de imposto e plataformas de copy trading usam essas conexões.

Como a corretora sabe que a ordem é sua? Assinatura HMAC

Cada requisição privada leva três elementos: a API key, um carimbo de tempo e uma assinatura. A assinatura é um HMAC, um código gerado a partir da mensagem e da secret key. A corretora recalcula o código do lado dela; se bater, a mensagem é autêntica e não foi alterada.

Na BingX, por exemplo, a documentação oficial descreve o processo assim (autenticação da API BingX):

• a API key vai no cabeçalho X-BX-APIKEY;
• os parâmetros são ordenados por nome e unidos no formato chave=valor&chave=valor;
• a assinatura é o HMAC SHA256 dessa string com a secret key, em hexadecimal minúsculo;
• o parâmetro timestamp vai em milissegundos, e o recvWindow (padrão e máximo de 5.000 ms) limita a validade da requisição.

Em Python, a assinatura se calcula com a biblioteca padrão:

import hashlib
import hmac
import os
import time

api_secret = os.environ["BINGX_SECRET_KEY"]  # nunca escreva a chave no código

params = {"symbol": "BTC-USDT", "timestamp": int(time.time() * 1000)}
texto = "&".join(f"{k}={params[k]}" for k in sorted(params))
assinatura = hmac.new(api_secret.encode(), texto.encode(), hashlib.sha256).hexdigest()

print(texto)
print(assinatura)

O carimbo de tempo e a janela curta impedem que alguém capture uma requisição e a reenvie mais tarde. Se o relógio do seu servidor estiver atrasado, as ordens são recusadas: sincronize o horário do sistema.

O jeito mais simples: biblioteca ccxt

Na prática, poucos escrevem assinaturas à mão. A biblioteca ccxt faz isso para mais de 100 corretoras com a mesma interface. Exemplo com a BingX, lendo as chaves de variáveis de ambiente:

import os
import ccxt

exchange = ccxt.bingx({
    "apiKey": os.environ["BINGX_API_KEY"],
    "secret": os.environ["BINGX_SECRET_KEY"],
})

saldo = exchange.fetch_balance()
print("USDT livre:", saldo["free"].get("USDT", 0))

# ordem limitada de compra bem abaixo do preço atual, só para testar o fluxo
ordem = exchange.create_order("BTC/USDT", "limit", "buy", 0.0001, 50_000)
print(ordem["id"], ordem["status"])
exchange.cancel_order(ordem["id"], "BTC/USDT")

Segundo o manual do ccxt, o controle de limite de requisições vem ativado por padrão, e o modo sandbox (set_sandbox_mode(True)) deve ser a primeira chamada após criar a corretora; as chaves de teste não funcionam na conta real, e vice-versa. Confira o lote mínimo e o preço permitido do par antes de enviar ordens.

Passo a passo: criar uma chave de API segura

1. Ative a autenticação em dois fatoresPrefira aplicativo autenticador a SMS.
2. Crie a chave na área de APIDê um nome que identifique o robô ou serviço.
3. Marque só o necessárioLeitura para ferramentas de imposto; leitura e negociação para robôs. Saque, nunca.
4. Restrinja por IPInforme o IP fixo do seu servidor (VPS). Chaves sem lista de IP são as mais perigosas.
5. Guarde o segredoA secret key aparece uma única vez; salve num gerenciador de senhas ou variável de ambiente.
6. Revise e apagueRemova chaves sem uso e troque as ativas periodicamente.

As boas práticas publicadas pela Binance.US seguem a mesma linha: tratar chaves como senhas, conceder só o acesso necessário, usar lista de IPs, cadastrar endereços de saque autorizados, apagar chaves sem uso e considerar trocá-las a cada 90 dias.

Grandes corretoras oferecem APIs para robôs; em 2022, a Binance orientou usuários a desativar chaves ligadas à 3Commas após o vazamento. Crédito: Boletim Bitcoin.

O caso 3Commas: o que acontece quando chaves vazam

Em dezembro de 2022, um usuário anônimo publicou cerca de 100 mil chaves de API ligadas à 3Commas, plataforma de robôs que se conectava às corretoras dos clientes. A empresa confirmou que os dados eram verdadeiros, e usuários relataram perdas de cerca de US$ 22 milhões, segundo a SiliconANGLE. O então CEO da Binance, Changpeng Zhao, recomendou que quem já tivesse colocado uma chave na 3Commas a desativasse imediatamente (The Block).

Golpistas também pedem chaves de API fingindo oferecer robôs ou gestão de carteira. Veja os padrões mais comuns em golpes com criptomoedas.

Ambiente de testes e operação do robô

Antes da conta real:

• Use o ambiente demo. Na BingX, o ambiente de simulação (VST) tem endereço de API próprio, separado do ambiente real, segundo o repositório oficial de skills da BingX. A documentação da API BingX detalha os endpoints de spot e futuros.
• Respeite limites de requisição. Excesso de chamadas gera bloqueio temporário.
• Trate erros. Ordem rejeitada, saldo insuficiente, desconexão: o robô precisa saber o que fazer em cada caso.
• Registre tudo. Cada ordem enviada, resposta recebida e motivo da decisão.
• Tenha limites no código. Tamanho máximo de ordem, perda diária máxima e um comando para cancelar tudo.

Se a ideia é usar bots prontos em vez de programar, as corretoras oferecem grid e DCA sem API; a BingX é um exemplo, com tutoriais no hub da BingX e no guia de grid bot. A lógica e os riscos de cada tipo estão em estratégias de robôs.

O vídeo abaixo mostra, em português, um robô em Python conectado à API de uma corretora, com o código explicado, um bom ponto de partida para ver as chamadas na prática.

Conectando alertas do TradingView à API

Um fluxo comum é: estratégia em Pine Script gera um alerta, o alerta envia um webhook ao seu servidor e o servidor envia a ordem pela API. Nesse desenho:

• inclua uma senha no corpo do alerta e recuse mensagens sem ela;
• valide ativo, lado e tamanho antes de repassar a ordem;
• mantenha as chaves só no servidor, nunca no texto do alerta.

Automatizar pela API dá velocidade e disciplina, mas transfere para você a responsabilidade pela segurança. Combine as práticas deste guia com gestão de risco no trading e teste com honestidade, como descrito em backtest.

Conteúdo informativo, não é recomendação de investimento.