Genesis Arbitrage

Genesis Arbitrage · · 14 min de leitura

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 indicador stale dos livros de ofertas, o spread nas melhores cotações e um contrato comum nas duas exchanges do par.
  • Um 503 significa que não há dados, enquanto um data vazio com 200 significa 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, um null numa comparação derruba o Python, a divisão por zero em JavaScript dá Infinity e 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

  1. A chave está em GENESIS_API_KEY no servidor e em nenhum outro lugar do código, das URLs de requisição, do navegador, dos logs ou dos prompts.
  2. Toda requisição tem um timeout.
  3. 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.
  4. 400, 401, 403, 404, 410 e um Retry-After acima de um minuto param o bot com uma mensagem.
  5. A pausa entre consultas é de pelo menos meta.freshness_sec e roda em todos os caminhos do loop.
  6. A idade do snapshot é verificada antes de qualquer alerta, e nos livros de ofertas também stale e order_delta.status.
  7. «Sem dados» e «sem pares» são estados separados, e três ciclos sem dados disparam uma mensagem de falha.
  8. null é verificado contra None, os denominadores contra zero, e o horário é tratado em UTC.
  9. Um par passa pelo seu spread nas melhores cotações, um contrato comum, withdraw_enabled_buy e deposit_enabled_sell.
  10. 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:

Teste você mesmo

  1. Descubra a atualização do seu plano

    Chame /account/usage e anote freshness_sec e calls_used: essa requisição não conta como chamada.

  2. Meça a idade do snapshot

    Obtenha /arbitrage/spot-spot com fetch, imprima time.time() - meta["updated_at"] e compare com o limite de 3 × freshness_sec.

  3. Compare dois spreads

    Imprima spread_pct e quote_spread(row) de cinco linhas e conte quantos pares continuam positivos nas melhores cotações.

  4. Teste o caminho de erro

    Rode o bot com o valor de exemplo GENESIS_API_KEY=gns_live_XXXXXXXXXXXXXXXX: a resposta 401 invalid_key deve pará-lo com uma mensagem clara.

  5. Percorra a lista de verificação

    Acrescente o que faltar no seu código antes de rodar o bot 24 horas por dia.