Genesis Arbitrage

Genesis Arbitrage · · 12 min de leitura

Respostas e erros da Genesis API: formato JSON, ETag e 304, códigos HTTP

Em resumo

  • Uma resposta bem-sucedida da Genesis API é um envelope com success, data e meta; um erro é success: false mais um objeto error com código e mensagem.
  • Se você enviar o ETag anterior em If-None-Match, o servidor devolve 304 sem corpo quando os dados não mudaram, e um 304 não gasta cota.
  • Repita 429 e 503 após a pausa de Retry-After. Repetir não corrige 400, 401, 403, 404 nem 410: mude a requisição, a chave ou o plano.

A Genesis API responde a cada requisição em JSON, um formato de dados em texto formado por objetos chave–valor e arrays. Uma resposta bem-sucedida sempre vem no mesmo envelope com success, data e meta; um erro vem com um código de status HTTP e um objeto error. O código de status diz ao seu programa o que fazer: usar os dados, esperar Retry-After segundos e tentar de novo, ou corrigir a requisição.

Envelope da resposta: success, data e meta

Uma resposta resumida de GET /arbitrage/spot-spot, tirada da documentação (o endpoint está disponível em todos os planos):

{
  "success": true,
  "data": [
    {
      "coin": "FUEL",
      "exchange_buy": "ByBit",
      "exchange_sell": "Gate",
      "spread_pct": 0.11,
      …
    }
  ],
  "meta": {
    "count": 214,
    "updated_at": 1783802410,
    "freshness_sec": 10,
    "plan": "pro"
  }
}
CampoTipoConteúdo
successbooleantrue: a requisição deu certo, false: erro
dataarray ou objetoOs dados do endpoint
meta.countintNúmero de itens em data
meta.updated_atintHora unix em que os dados foram montados
meta.freshness_secintAtraso de entrega do seu plano, em segundos
meta.planstringSeu plano, pro no exemplo

A exceção é a análise de funding: o meta dela traz count, updated_at e schema_version, sem freshness_sec nem plan. O envelope está descrito na seção Formato de resposta da documentação, e os campos de data na página de cada endpoint.

Três convenções valem para todos os endpoints:

data: um array de linhas ou um objeto

O formato de data é indicado na descrição de cada endpoint. Em GET /arbitrage/spot-spot é um array: um item por par de arbitragem, como uma linha da tabela do site. Em GET /account/usage é um único objeto com o estado da sua chave:

curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

/account/usage está disponível em todos os planos e mostra seu plano, o uso da cota e freshness_sec: consultar com mais frequência não traz nada. Os campos estão descritos em Uso, e a primeira requisição é percorrida passo a passo no início rápido. Código que trabalha com vários endpoints deve verificar o formato de forma explícita: isinstance(data, list) em Python.

Filtros: opcionais, sem eles vem o conjunto completo

Todos os parâmetros de filtro são opcionais: uma requisição sem eles devolve o conjunto de dados completo do endpoint. Liste várias exchanges em exchange separadas por vírgula e indique uma moeda pelo ticker em coin:

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

A opção -G transforma os parâmetros -d em uma query string: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Escreva os nomes das exchanges como voltam nos campos da resposta: ByBit, Gate, MEXC. Os parâmetros dos endpoints de arbitragem estão no guia de endpoints de arbitragem.

A cota conta respostas, não linhas: uma requisição com ou sem filtros é uma chamada. Um filtro reduz o corpo da resposta e, com ele, o tráfego e o uso do limite de download. Todos os limites estão no guia de limites da Genesis API.

Compressão gzip

A Genesis API envia conjuntos completos e respostas grandes compactados em gzip quando o cliente manda o cabeçalho Accept-Encoding: gzip (RFC 9110, seção 12.5.3). Uma resposta pequena pode chegar sem compressão.

O requests do Python envia esse cabeçalho sozinho e descompacta a resposta. O curl não pede compressão sem a opção --compressed; com ela, ele pede e descompacta.

O limite de download conta os dados compactados: no máximo 60 MB a cada 10 segundos por chave, e respostas com menos de 64 KB não são contadas. Acima do limite, você recebe 429 download_limited.

ETag e 304: pule dados que não mudaram

ETag é um cabeçalho de resposta com uma etiqueta de versão dos dados. O cliente devolve essa etiqueta no cabeçalho If-None-Match. Se os dados não mudaram, o servidor responde 304 Not Modified sem corpo; se mudaram, um 200 comum com dados novos e um novo ETag.

# Conjunto completo, sem filtros: mostrar apenas os cabeçalhos da resposta
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# Repetir com o ETag da primeira resposta (valor ilustrativo)
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H 'If-None-Match: W/"5d1f0c9a"'

Um ETag vem com a resposta a uma requisição sem filtros e muda a cada novo instantâneo dos dados. A resposta a uma requisição filtrada é montada para ela e vem sem ETag; nesse caso, o próprio filtro economiza tráfego. Os ETags ajudam mais em dados de mudança lenta: o resumo da análise de funding troca de ETag mais ou menos a cada 15 minutos, e as respostas 304 não contam para o limite de download completo dele.

Uma resposta 304 não gasta cota, mas conta para o limite de requisições por segundo. Devolva a etiqueta exatamente como chegou: segundo a RFC 9110, é uma string entre aspas, e o prefixo W/ marca uma etiqueta fraca.

Códigos de erro e o que fazer

Em caso de erro, a Genesis API devolve o status HTTP correspondente e um corpo com success: false:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Requests per second limit exceeded."
  }
}

error.code é um código legível por máquina, no qual seu programa pode se basear para ramificar a lógica. error.message é a explicação para uma pessoa: no 400 traz o motivo, no 410 o endereço substituto.

HTTPerror.codeSignificadoO que fazer
400bad_requestParâmetros da requisição inválidos, por exemplo volume=700 em /orderbooks/execCorrija os parâmetros conforme message: a mesma requisição falhará de novo
401invalid_keyChave ausente, inválida ou revogada, ou assinatura da API expiradaVerifique o cabeçalho X-API-Key e o status da assinatura no seu perfil
403plan_restrictedO endpoint não faz parte do seu planoMude para um plano que o inclua ou remova a requisição
404not_foundEndpoint ou recurso não encontrado: conjunto de dados, seção, moeda, livro de ofertasConfira o caminho e os parâmetros na documentação
410goneO endpoint foi desativadoPasse para o endereço indicado em message
429rate_limitedLimite de requisições por segundo excedido ou cota do período esgotadaEspere Retry-After segundos e reduza o ritmo; se a cota esgotou, aguarde a renovação ou troque de plano
429download_limitedVolume de download excedido: 60 MB de dados compactados a cada 10 s por chaveEspere Retry-After, reduza o tráfego com filtros, coin e If-None-Match
500internal_errorErro internoTente de novo mais tarde; se persistir, fale com o suporte informando o X-Request-Id
503snapshot_not_readyOs dados estão sendo reconstruídos ou a fonte deles está reiniciandoTente de novo após Retry-After segundos

O cabeçalho Retry-After vem com 429 e 503 e traz o número de segundos de espera: em geral poucos segundos, mas, quando a cota do período esgota, é o tempo até a renovação da cota, que pode ser de dias. Erros 4xx e 5xx não gastam cota, mas contam para o limite de requisições por segundo, então uma nova tentativa antecipada provavelmente devolverá o mesmo erro. Termos do glossário: HTTP 429 e rate limit.

X-Request-Id: o que enviar ao suporte

Toda resposta da Genesis API, com sucesso ou não, traz um cabeçalho X-Request-Id com o identificador da requisição. Se um erro se repete ou os dados parecem errados, envie ao suporte:

Não envie sua chave. Se ela foi parar em um chat, em logs ou em código que outras pessoas podem ver, gere-a de novo no seu perfil: a chave antiga deixa de funcionar imediatamente.

Ordem de tratamento da resposta

  1. Verifique o código de status

    200: leia data e meta e guarde o ETag, se veio. 304: use os dados da resposta anterior.

  2. Trate os erros temporários

    429 e 503 com pausa curta: espere Retry-After segundos e tente de novo, no máximo três vezes seguidas. 500: tente mais tarde.

  3. Pare nos erros de requisição

    400, 401, 403, 404, 410 e um 429 com pausa de horas ou dias: corrija os parâmetros, a chave ou o plano, ou aguarde a renovação da cota.

  4. Verifique a idade dos dados

    Compare meta.updated_at com a hora atual: um bot que age sobre um instantâneo antigo vê spreads que já sumiram.

  5. Agende a próxima requisição

    Não antes de meta.freshness_sec segundos depois, com If-None-Match nas requisições sem filtros.

Uma função get_json em Python

A função reúne essas regras: guarda o último ETag de cada endereço e devolve os dados anteriores num 304, espera Retry-After em 429 e 503 e tenta de novo até três vezes, mas não espera pausas maiores que um minuto. Os demais erros lançam uma exceção com o status, a mensagem e o X-Request-Id. A chave vem da variável de ambiente GENESIS_API_KEY.

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # (caminho, parâmetros) -> (ETag, dados)


class GenesisError(Exception):
    def __init__(self, status, text):
        super().__init__(f"{status} {text}")
        self.status = status


def get_json(path, params=None):
    key = (path, tuple(sorted((params or {}).items())))
    for attempt in range(4):  # uma requisição mais até 3 novas tentativas
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = session.get(BASE + path, params=params,
                        headers=hdr, timeout=15)
        if r.status_code == 304:
            return cache[key][1]  # os dados não mudaram
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # nunca esperar horas ou dias
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "não é JSON") from None
        if r.status_code != 200 or not body.get("success"):
            err = body.get("error") or {}
            raise GenesisError(r.status_code, (
                f"{err.get('code')}: {err.get('message')}; "
                f"X-Request-Id {r.headers.get('X-Request-Id')}"))
        if "ETag" in r.headers:  # só em respostas sem filtros
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

O parâmetro timeout=15 é obrigatório: sem tempo limite, o requests espera uma resposta para sempre.

Consulta no intervalo do seu plano: o conjunto completo vem com ETag e as linhas são filtradas no código. Erros 4xx interrompem o programa; uma falha do servidor espera o próximo ciclo.

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # conjunto completo
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "pares com spread de 1% ou mais")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx: a requisição, a chave, o plano ou a cota
        print("erro do servidor, nova tentativa no próximo ciclo:", e)
    time.sleep(pause)

Perguntas e respostas

Uma resposta 304 gasta cota?

Não. Só as respostas 200 gastam cota. As respostas 304 e os erros 4xx e 5xx são gratuitos, mas contam para o limite de requisições por segundo.

O que fazer após um 410 ?

O endpoint foi desativado e o endereço substituto está em error.message. Por exemplo, GET /arbitrage/predictions foi desativado em 15 de novembro de 2026 e o message dele aponta para /predictions/arbitrage. Atualize o caminho no seu código.

Por que data está vazio sem erro?

Os filtros removeram todas as linhas: por exemplo, min_spread está acima de todos os spreads atuais. Uma resposta assim tem meta.count igual a 0; afrouxe o filtro.

Por que não há ETag na resposta?

Um ETag vem com a resposta a uma requisição sem filtros. A resposta a uma requisição com coin, exchange, min_spread ou outro filtro é montada para ela e vem sem etiqueta, então If-None-Match não se aplica.