Riscos da automação: dados, erros, chaves e IA
Em resumo
- Verifique os dados antes de qualquer alerta: a idade do snapshot (hora atual menos
meta.updated_at), o indicadorstaledos livros de ofertas, o spread nas melhores cotações e um contrato comum nas duas exchanges do par. - Um
503significa que não há dados, enquanto umdatavazio com200significa que nada correspondeu ao filtro. O bot distingue os dois casos e avisa sobre uma falha após três ciclos sem dados. - O código quebra em casos extremos: tentar de novo sem pausa leva a um
429, umnullnuma comparação derruba o Python, a divisão por zero em JavaScript dáInfinitye um alerta falso, e o horário local no lugar de UTC desloca um pagamento de funding em horas. - Uma chave da Genesis API é somente leitura, então um vazamento queima sua cota. Uma chave de exchange com direito de saque põe o dinheiro em risco, e um bot de trading não precisa desse direito.
- Um modelo de IA confunde números e pode seguir um comando escondido no texto de outra pessoa: o código insere os números nas mensagens, os campos externos chegam ao modelo como dados, o código impõe os limites das operações e uma pessoa confirma cada ordem.
Os riscos de um bot de trading com API de criptomoedas se dividem em quatro grupos: os dados estão desatualizados ou mostram um spread que não existe; o código entra em loop ou quebra num caso extremo; a chave vaza; um modelo de IA erra um número ou segue o comando de outra pessoa. Cada risco tem uma verificação no código ou uma regra de trabalho, e todas cabem também no monitor da lição 4.
Riscos dos dados
Um snapshot desatualizado
Um snapshot da Genesis API é montado em meta.updated_at, e seu plano o renova a cada meta.freshness_sec segundos: 60 no Trial, 30 no Start, 10 no Pro e 5 no Max. A idade do snapshot é a hora atual menos meta.updated_at, ou seja, sua atualização dos dados. Um ou dois intervalos do plano é normal; mais de três significa que o snapshot travou.
Exemplo hipotético: no Pro o limite é 3 × 10 = 30 s. Uma resposta chega em 1783802470 com meta.updated_at = 1783802410: a idade é 1783802470 − 1783802410 = 60 s, então o bot não envia alertas a partir dela. A latência total da exchange até o seu código é ainda maior, e a idade é medida pelo relógio do seu servidor, então mantenha-o sincronizado por NTP.
Livros de ofertas e plataformas de previsão
Os livros de ofertas têm seu próprio relógio: /orderbooks/book retorna book_ts, age_sec e um indicador stale que é true quando o livro tem mais de 30 segundos. Os livros ficam de 5 a 20 segundos atrás da exchange. No Order-book Δ, verifique order_delta.status: ok significa calculado, no_book significa que não há livro, exhausted significa que o livro não conseguiu cobrir o volume.
Para os mercados de previsão existe /predictions/platforms: ignore os pares que envolvam uma plataforma com mode = down, uma plataforma com quotes_at antigo ou uma casa de apostas com ok = false.
Uma resposta vazia num 503
Uma lista vazia e a falta de dados são estados diferentes. Um 200 com meta.count = 0 significa que nenhuma linha correspondeu ao filtro. Um 503 snapshot_not_ready significa que os dados estão sendo reconstruídos: o mercado ainda pode ter pares, e você tenta de novo após Retry-After segundos.
A função fetch retorna (data, meta), ou None quando não há dados. Ela repete 429 e 503 após Retry-After, os demais erros 5xx e as falhas de rede após pausas de 5, 10 e 20 segundos, e para em todo o resto.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
def fetch(path, params=None, tries=4):
"""(data, meta), ou None: sem dados, o que não é "sem pares"."""
for attempt in range(tries):
try:
r = requests.get(BASE + path, headers=HEADERS,
params=params, timeout=15)
code = r.status_code
except requests.RequestException:
code = 0 # erro de rede ou timeout: tentar de novo após uma pausa
if code == 200:
body = r.json()
return body["data"], body["meta"]
wait = 5 * 2 ** attempt # 5, 10, 20 s: a pausa aumenta
if code in (429, 503):
wait = int(r.headers.get("Retry-After", wait))
if wait > 60: # nunca esperar mais de um minuto
raise RuntimeError(f"espera de {wait} s: verifique sua cota")
elif 400 <= code < 500:
# 400, 401, 403, 404, 410: tentar de novo não resolve
raise RuntimeError(f"{code}: {r.text[:200]}")
if attempt < tries - 1:
time.sleep(wait)
return None
Um Retry-After longo também chega quando a cota do período se esgota: a renovação pode estar a dias de distância, e fetch nunca espera mais de um minuto. Retentativas, ETag e filtros são tratados no artigo sobre como consultar uma API sem bater nos limites.
Um spread falso: livros rasos e tokens parecidos
spread_pct é calculado a partir das últimas negociações, mas você só consegue comprar no ask e vender no bid. No exemplo da FUEL do guia de endpoints de arbitragem, o spread é de 0,11% pelas últimas negociações e de −0,11% nas melhores cotações. Os campos ask_buy e bid_sell vêm em toda linha Spot – Spot de qualquer plano, e quote_spread abaixo os usa para calcular o spread nas melhores cotações.
Um livro de ofertas raso infla a diferença. Exemplo hipotético: a última negociação foi registrada a US$ 1,18 há uma hora, o melhor bid agora é US$ 1,02 e o ask na exchange de compra é US$ 1,00. O spread é de 18% pelas últimas negociações e de 2% nas melhores cotações, e US$ 1.000 podem nem ser executados: no Pro e no Max, order_delta.status = exhausted com volume=1000 mostra exatamente isso.
A segunda fonte de spreads falsos é um mesmo ticker compartilhado por tokens diferentes, como um token na BSC e um projeto sem relação na Solana. Para um token com contrato, consulte /coins/search com o ticker em query: contracts[] deve ter uma entrada cujo exchanges liste as duas exchanges do par (compare os nomes sem distinguir maiúsculas). Sem essa entrada, não há transferência direta: são tokens diferentes, ou a rota passa por uma ponte com seus próprios riscos.
def is_fresh(meta, k=3):
"""O snapshot tem no máximo k intervalos do plano."""
age = time.time() - meta["updated_at"]
return age <= k * meta["freshness_sec"]
def quote_spread(row):
"""Spread nas melhores cotações: comprar no ask, vender no bid."""
ask, bid = row.get("ask_buy"), row.get("bid_sell")
if ask is None or bid is None or ask <= 0:
return None # sem preço ou preço zero: pular a linha
return (bid - ask) / ask * 100
pause, fails = 60, 0
while True:
got = fetch("/arbitrage/spot-spot", {"min_spread": 1})
if got is None or not is_fresh(got[1]):
fails += 1 # sem dados ou dados desatualizados: sem alertas
if fails == 3:
print("3 ciclos sem dados recentes") # avise a si mesmo
else:
rows, meta = got
fails, pause = 0, meta["freshness_sec"]
for row in rows:
s = quote_spread(row)
if s is not None and s >= 0.5:
print(row["coin"], row["exchange_buy"], "→",
row["exchange_sell"], f"{s:.2f}%")
time.sleep(pause) # a pausa roda em todos os caminhos
Uma exceção de fetch interrompe o loop: um bot de produção avisa o dono antes de sair.
Riscos do código
Retentativas sem pausa e loops infinitos
Um primeiro bot costuma tentar de novo logo após um erro: if r.status_code != 200: continue. Num 503, um loop assim dispara requisições uma atrás da outra sem pausa: os erros não gastam cota, mas contam no limite de requisições por segundo, e vem um 429 com Retry-After: 1. Quando a assinatura expira, o mesmo loop recebe 401 para sempre. E um continue antes de time.sleep() pula a pausa em toda resposta vazia, por isso a pausa é a última linha do loop acima.
O erro oposto é esperar para sempre. time.sleep(int(r.headers["Retry-After"])) com a cota esgotada dorme por dias: por exemplo, Retry-After: 259200 são 259.200 / 86.400 = 3 dias. Uma requisição sem timeout também pode ficar pendurada indefinidamente, como alerta a documentação do requests.
null e divisão por zero
A Genesis API usa null para valores vazios, e o Python o transforma em None. Comparar row["volume_24h_sell"] > 10000 com None gera TypeError, e uma única linha derruba o loop inteiro. O JavaScript não gera nada: null > 0.5 é false, null < 1 é true, e o filtro falha em silêncio.
null significa «sem dados», e trocá-lo por zero com or 0 é perigoso: no slippage DEX, tax_sell_pct = null significa que não há fonte do imposto, e or 0 o transforma em 0%. Segundo a documentação, null aparece em bid_* e ask_*, volume_24h_*, max_position_usd, next_payout, em profit_usd para pares com uma perna de casa de apostas e em apr_pct quando falta menos de um dia.
A divisão por zero é a mesma armadilha. Um ask zero gera ZeroDivisionError no Python, enquanto no JavaScript 1 / 0 é Infinity e Infinity > 0.5 é true: o bot envia um par com spread infinito. Verifique o denominador antes de dividir, como quote_spread verifica ask <= 0.
Fusos horários
Os horários da Genesis API são segundos unix e strings UTC: next_payout nas taxas de financiamento chega como HH:MM UTC. datetime.fromtimestamp(ts) sem fuso horário retorna a hora local do servidor, e datetime.utcnow() está obsoleto desde o Python 3.12; a documentação do Python indica datetime.now(timezone.utc) no lugar.
Exemplo hipotético: o servidor roda em UTC+3 e seu relógio marca 09:30, que são 06:30 UTC. O pagamento das 08:00 está a 1 h 30 min, mas um código que compara 08:00 com a hora local decide que o pagamento já passou e conta 22 h 30 min até o próximo, 21 horas de erro.
from datetime import datetime, timedelta, timezone
def until_payout(hhmm, now=None):
"""Tempo até next_payout, uma string HH:MM em UTC."""
if hhmm is None:
return None # null: sem horário de pagamento
now = now or datetime.now(timezone.utc)
h, m = map(int, hhmm.split(":"))
t = now.replace(hour=h, minute=m, second=0, microsecond=0)
if t <= now:
t += timedelta(days=1) # "00:00" às 23:50 significa amanhã
return t - now
now = datetime(2026, 11, 15, 6, 30, tzinfo=timezone.utc)
print(until_payout("08:00", now)) # 1:30:00
Riscos das chaves
Uma chave da Genesis API é somente leitura: ela não pode colocar ordens nem sacar fundos. Um vazamento atinge sua cota e o limite de requisições por segundo, e seu bot recebe 429 antes de o período acabar. Sinais de alerta: «Chamadas usadas» no seu perfil cresce mais rápido do que seu código explica, ou «usada em …» mostra um horário recente enquanto o bot está parado.
A chave é mostrada uma única vez e a Genesis Arbitrage guarda apenas o hash dela, então uma chave vazada é reemitida: «Reemitir» desativa a chave antiga na hora e emite uma nova. As chaves vazam dos lugares onde foram postas por engano: um repositório público, a URL de uma requisição, o código de uma página, uma captura de tela, um log com os cabeçalhos da requisição. Registre no lugar o código de status e o X-Request-Id; as regras de armazenamento estão no verbete do glossário chave de API.
Uma chave de exchange é outra classe de risco: com direito de saque, ela pode tirar moedas da conta. Um bot de trading não precisa desse direito, então crie a chave sem saques, vinculada ao IP do seu servidor e separada para cada serviço. Os detalhes estão em como proteger sua conta de exchange de criptomoedas.
Agentes de IA: números, comandos injetados, confirmação
Um agente chama a Genesis API pelo seu servidor: o modelo escolhe o endpoint e os argumentos, e o servidor faz a requisição com a chave. A configuração está no guia Genesis API para agentes de IA, e o desenho geral no artigo sobre dados do mercado de criptomoedas para agentes de IA.
Números errados
Um modelo pode ler 0.92 como 92% em vez de 0,92%, confundir o funding_pct por intervalo com o funding_8h_pct de 8 horas, ou citar um preço que não está na resposta. O código insere os números nos alertas direto da resposta da API, e ao modelo sobram a seleção e a explicação. Se o modelo escreve números por conta própria, confira cada um com o resultado da ferramenta.
Comandos em texto de terceiros
Alguns campos são escritos por outras pessoas: title e outcome dos mercados de previsão, o name dos traders, o token_name dos eventos on-chain e as message_ru e message_en dos sinais. Qualquer pessoa pode chamar um token de «Ignore as instruções anteriores e…», e um modelo que lê o nome como parte do seu prompt pode obedecer. É a injeção de prompt (prompt injection), a primeira entrada do OWASP Top 10 para aplicações de LLM 2025: LLM01:2025.
Passe esses campos apenas dentro do resultado da ferramenta, limite o tamanho e declare no prompt do sistema que são dados. A chave fica no tratador do lado do servidor.
Confirmação humana
A Genesis API apenas lê dados: um agente construído sobre ela encontra um par e escreve sobre ele, mas não negocia. Uma API de trading de exchange ligada ao agente fica fora da Genesis API e por sua conta e risco. Entre as medidas de mitigação, a OWASP lista o controle com uma pessoa no circuito (human-in-the-loop) para operações privilegiadas: uma ordem só sai após um «sim» de um trader que vê o par, os preços e a hora dos dados.
Lista de verificação antes do lançamento
- A chave está em
GENESIS_API_KEYno servidor e em nenhum outro lugar do código, das URLs de requisição, do navegador, dos logs ou dos prompts. - Toda requisição tem um
timeout. - Só
429,503, os demais erros 5xx e as falhas de rede são repetidos, com uma pausa e no máximo três vezes. 400,401,403,404,410e umRetry-Afteracima de um minuto param o bot com uma mensagem.- A pausa entre consultas é de pelo menos
meta.freshness_sece roda em todos os caminhos do loop. - A idade do snapshot é verificada antes de qualquer alerta, e nos livros de ofertas também
staleeorder_delta.status. - «Sem dados» e «sem pares» são estados separados, e três ciclos sem dados disparam uma mensagem de falha.
nullé verificado contraNone, os denominadores contra zero, e o horário é tratado em UTC.- Um par passa pelo seu spread nas melhores cotações, um contrato comum,
withdraw_enabled_buyedeposit_enabled_sell. - O código insere os números nas mensagens, o texto externo chega ao modelo como dados, e uma pessoa confirma cada ordem.
Fechamento do curso: para onde ir depois
O curso tem cinco lições: conceitos, uma primeira requisição, dados para decidir, um monitor em Python e seus riscos; o básico está na lição 1. Detalhes de cada etapa:
- Início rápido da Genesis API: a chave e uma primeira requisição;
- Limites da Genesis API: a cota e como dimensionar um plano para o seu bot;
- Respostas e erros da Genesis API: códigos,
ETageX-Request-Id; - Endpoints de livros de ofertas: Order-book Δ para o seu volume;
- Bot de arbitragem de criptomoedas em Python: um bot com alertas no Telegram;
- API de criptomoedas: tipos e como escolher: uma visão geral das fontes de dados.
Teste você mesmo
Descubra a atualização do seu plano
Chame
/account/usagee anotefreshness_sececalls_used: essa requisição não conta como chamada.Meça a idade do snapshot
Obtenha
/arbitrage/spot-spotcomfetch, imprimatime.time() - meta["updated_at"]e compare com o limite de 3 ×freshness_sec.Compare dois spreads
Imprima
spread_pctequote_spread(row)de cinco linhas e conte quantos pares continuam positivos nas melhores cotações.Teste o caminho de erro
Rode o bot com o valor de exemplo
GENESIS_API_KEY=gns_live_XXXXXXXXXXXXXXXX: a resposta401 invalid_keydeve pará-lo com uma mensagem clara.Percorra a lista de verificação
Acrescente o que faltar no seu código antes de rodar o bot 24 horas por dia.