Genesis Arbitrage

Genesis Arbitrage · · 9 min de leitura

Limites da Genesis API: cota de chamadas, requisições por segundo, atualização dos dados e erros 429

Em resumo

  • Seu plano define a cota de chamadas por 30 dias (de 500 mil no Trial a 10 milhões no Max), o limite de requisições por segundo (de 1 a 15) e a atualização dos dados (de 60 a 5 segundos).
  • Só uma resposta 200 consome cota. Respostas 304 e erros não custam nada, mas ocupam uma vaga no limite de requisições por segundo; ao passar de um limite, o servidor devolve 429 e não cobra nada.
  • Consultar mais rápido que meta.freshness_sec não traz dados novos: seu plano recebe um snapshot novo uma vez por esse intervalo, e If-None-Match transforma as consultas extras em respostas 304 gratuitas.

Os limites da Genesis API são quatro tetos por chave: a cota de chamadas para um período de 30 dias, o rate limit em requisições por segundo, a atualização dos dados e o volume de download. Seu plano define os três primeiros; o volume de download é igual para todos: 60 MB de dados compactados a cada 10 segundos. Ao passar de qualquer limite, o servidor devolve um erro 429 e não cobra nada.

Limites por plano

PlanoChamadas por 30 diasRequisições por segundoAtualização
Trial, $20/mês500.000160 s
Start, $50/mês2.000.000230 s
Pro, $100/mês5.000.000510 s
Max, $200/mês10.000.000155 s

A atualização dos dados é o intervalo em que seu plano recebe um snapshot novo: a cada 60 segundos no Trial, a cada 5 no Max. As respostas trazem esse valor no campo meta.freshness_sec. Pagar por 3 meses economiza 10%, por 6 meses, 20%. A comparação dos planos está na página de preços da Genesis API, e as regras estão na seção Planos e limites da documentação.

O que consome a cota

Uma chamada é uma resposta 200. Respostas 304 (dados sem alteração) e erros 4xx e 5xx não consomem cota, mas contam para o limite de requisições por segundo. Uma requisição a /account/usage não consome chamada.

A cota vale para um período de 30 dias, não para um mês do calendário. O horário da renovação está no cabeçalho X-Quota-Reset, no campo period_resets_at e na linha «resets …» do seu perfil. Quando a cota acaba, o servidor responde 429 rate_limited, e Retry-After traz o número de segundos até a renovação, que podem ser dias.

Cabeçalhos de rate limit

A resposta de um endpoint de dados traz o estado dos seus limites (valores ilustrativos):

CabeçalhoExemploO que mostra
X-RateLimit-Limit5Limite de requisições por segundo do seu plano
X-RateLimit-Remaining4Requisições restantes na janela atual
X-RateLimit-Reset1785200001Horário Unix em que a janela é renovada
X-Quota-Limit5000000Cota de chamadas do período de 30 dias
X-Quota-Remaining4815799Chamadas restantes no período
X-Quota-Reset1786492800Horário Unix em que a cota é renovada
Retry-After1Segundos de espera antes de tentar de novo, em 429 e 503

A janela de requisições por segundo dura um segundo; por isso, numa resposta normal, X-RateLimit-Reset aponta para o início do segundo seguinte. A cota restante do exemplo: 5.000.000 − 184.201 = 4.815.799 chamadas, os mesmos números que /account/usage devolve.

O endpoint /account/usage

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": { … }
}
CampoTipoSignificado
planstringPlano: trial, start, pro ou max
calls_usedintChamadas usadas no período atual
calls_limitintCota de chamadas por período
rps_limitintLimite de requisições por segundo
freshness_secintAtraso dos dados, em segundos
period_resets_atintHorário Unix em que a cota é renovada

O endpoint está disponível em todos os planos e é descrito na seção Uso. Chame-o ao iniciar um bot, para conferir o plano e a cota restante antes de começar a consultar.

Erros 429: rate_limited e download_limited

RespostaQuando apareceO que fazer
429 rate_limitedMais requisições por segundo do que o plano permiteEsperar o tempo de Retry-After e espaçar as requisições
429 rate_limitedA cota do período acabouEsperar a renovação ou trocar de plano
429 rate_limitedDownload completo da análise de funding antes do permitidoPedir um recorte com coin ou enviar If-None-Match
429 download_limitedMais de 60 MB de dados compactados em 10 segundosEsperar o tempo de Retry-After e restringir a requisição com filtros

O código de status 429 Too Many Requests é definido na RFC 6585, onde Retry-After é opcional. A Genesis API o envia com todo 429, sempre em segundos.

Respostas abaixo de 64 KB não contam para o volume de download, e consultar todos os conjuntos de dados na atualização do seu plano cabe no limite com folga. Downloads completos da análise de funding sem coin têm limite próprio: /funding/analytics/summary e /funding/analytics/recent uma vez a cada 60 segundos, /funding/analytics/daily uma vez a cada 300 segundos por chave. Requisições com coin e respostas 304 não têm limite; os detalhes estão na seção Análise de funding.

Acesso por plano e 403 plan_restricted

PlanoO que está liberado
TrialArbitragem CEX (Spot – Spot, Spot – Futuros, Futuros – Futuros), taxas de financiamento (funding) e spread de funding, Fair – Last, CEX Pumps – Dumps, open interest, sinais de IA, busca de moedas, /account/usage
StartTudo do Trial, mais ações /arbitrage/stocks, seções on-chain /onchain/{section}, arbitragem de mercados de previsão nos modos exact e dutch, status das plataformas
Pro e MaxTodos os endpoints: DEX – Spot, DEX – Futuros, Crosschain, DEX Dumps, livros de ofertas, análise de funding, análise de mercados de previsão, smart money, negociações, traders, os modos llm e sport, swaps DEX, análise OnChain e moeda

Um endpoint fora do seu plano devolve 403, assim como uma requisição mode=sport a /predictions/arbitrage no Start:

{
  "success": false,
  "error": {
    "code": "plan_restricted",
    "message": "This endpoint is not included in your plan."
  }
}

Um 403 não consome cota. Tentar de novo não adianta: só um plano superior libera o acesso.

Como dimensionar o plano para a sua carga

Exemplo ilustrativo: um bot consulta três endpoints, /arbitrage/spot-spot, /funding/spread e /market/open-interest, a cada 10 segundos, 24 horas por dia.

O mesmo bot consultando na atualização de cada plano:

Atualização e consultaChamadas por 30 diasPlanoFração da cota
A cada 60 s129.600Trial26%
A cada 30 s259.200Start13%
A cada 10 s777.600Pro16%
A cada 5 s1.555.200Max16%

Consultar a cada 10 segundos faz sentido a partir do Pro: 777.600 / 5.000.000 = 15,552% da cota, e o limite de 5 requisições por segundo comporta o envio das três de uma vez. Se o bot aceita dados com 30 segundos de idade, o Start com consulta a cada 30 segundos custa 259.200 / 2.000.000 = 12,96% da cota.

Consultar sem chamadas desperdiçadas: ETag e Retry-After

Seu plano recebe um snapshot novo a cada meta.freshness_sec segundos, e consultar mais rápido devolve o mesmo snapshot com o mesmo meta.updated_at. Sem o cabeçalho If-None-Match, essa resposta é um 200 e uma chamada gasta. Com ele, o servidor responde 304 sem corpo: a cota fica intacta, mas uma vaga do limite por segundo é ocupada.

Um ETag não vem em toda resposta. Conjuntos de dados completos o devolvem, isto é, requisições sem filtros, como /funding/spread no exemplo abaixo. Uma resposta filtrada (coin, min_spread e outros) não tem ETag, e cada consulta custa uma chamada: filtros economizam tráfego, o ETag economiza cota. Novas tentativas e compressão são tratadas em como consultar uma API com eficiência e no guia de respostas e erros.

import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30

while True:
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    r = requests.get(URL, headers=headers, timeout=15)
    if r.status_code in (429, 500, 503):
        wait = int(r.headers.get("Retry-After", "5"))
        if wait > 600:  # a cota acabou, paramos aqui
            raise SystemExit(f"Cota esgotada, renova em {wait} s")
        time.sleep(wait)
        continue
    r.raise_for_status()  # tentar de novo não resolve 401 nem 403
    left = r.headers.get("X-Quota-Remaining")  # pode estar ausente
    if left is not None and int(left) < 10_000:
        print("Cota acabando:", left)
    if r.status_code == 200:  # com 304 os dados não mudaram
        etag = r.headers.get("ETag")
        body = r.json()
        pause = body["meta"].get("freshness_sec", pause)
        print(body["meta"]["count"], "moedas na resposta")
    time.sleep(pause)

Trocar e renovar o plano

Como obter e guardar a chave está no guia da chave da Genesis API.

Perguntas e respostas

O que acontece se a cota acabar antes da hora?

O servidor devolve 429 rate_limited com Retry-After até a cota ser renovada, e nada é cobrado. Espere o novo período ou pague um plano superior: ele vale na hora, com cota nova.

Respostas 304 e erros contam para os limites?

Não para a cota: só 200 a consome. Elas contam para o limite de requisições por segundo: respostas 304 e erros ocupam vagas na janela por segundo.

Como verificar a cota restante sem gastar uma chamada?

Leia X-Quota-Remaining numa resposta de dados ou chame /account/usage: essa requisição não consome chamada. A linha de chamadas usadas no seu perfil também mostra o consumo.

Posso contornar o limite com várias chaves?

Não. Cada conta recebe uma chave, os limites são contados por chave e trocar de endereço IP não os altera. Abrir várias contas para contornar limites viola as regras; se precisar de mais, mude para um plano superior.