Genesis Arbitrage

Genesis Arbitrage · · 11 min de leitura

Sua primeira requisição à API: HTTP, cabeçalhos e JSON

Em resumo

  • Uma requisição HTTP a uma API consiste em um método, um endereço formado pela URL base, o caminho e os parâmetros, e cabeçalhos. A chave da Genesis API vai apenas no cabeçalho X-API-Key.
  • O código de status indica o próximo passo: 200 significa ler os dados, 304 que nada mudou, 401 e 403 que é preciso verificar a chave e o plano, 429 e 503 que é preciso esperar Retry-After segundos.
  • A resposta da Genesis API é um envelope com success, data e meta. As porcentagens chegam como números simples (0.01 significa 0,01 %) e o horário chega em segundos unix.
  • Os erros comuns de iniciantes são a chave na URL, uma variável de ambiente vazia e um erro de digitação no caminho ou no nome de um parâmetro. Um erro de digitação em um parâmetro não gera erro: você recebe o conjunto completo de dados em vez do filtrado.

Para chamar uma API, seu programa envia uma requisição HTTP formada por um método, um endereço e cabeçalhos, e o servidor devolve um código de status, seus próprios cabeçalhos e um corpo, que na Genesis API é JSON. Você pode enviar a requisição de um terminal com curl ou de código em qualquer linguagem que tenha um cliente HTTP. A primeira requisição abaixo verifica a chave com /account/usage, e a segunda busca as taxas de financiamento (funding) do BTC em /funding/rates. O que é uma API e o que dá para automatizar com ela está na lição 1.

Anatomia de uma requisição

Esta é a requisição de taxas de financiamento (funding) do BTC que o curl envia ao servidor, como a opção -v mostra nas linhas que começam com > (a chave é substituída por um marcador):

> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
ParteNo exemploO que significa
MétodoGETLer dados; todos os endpoints da Genesis API são GET
URL basehttps://api.genesisarbitrage.com/v1Servidor e versão da API
Caminho/funding/ratesO endpoint de taxas de financiamento (funding)
Parâmetros?coin=BTCFiltro: somente BTC
CabeçalhoX-API-KeyA chave com a qual o servidor identifica sua conta e seu plano

Os parâmetros vêm depois do ? como pares nome=valor unidos por &: ?coin=BTC&exchange=Binance,OKX. Os filtros da Genesis API são opcionais, então sem coin o mesmo endpoint devolve todas as moedas. Decimais levam ponto, nunca vírgula: min_spread=0.5.

Cabeçalhos são linhas nome: valor que viajam junto com o endereço. Os nomes dos cabeçalhos não diferenciam maiúsculas de minúsculas (RFC 9110, seção 5.1): X-API-Key e x-api-key são o mesmo cabeçalho, e um x-request-id em minúsculas na saída do curl é o mesmo X-Request-Id. A Genesis API aceita a chave somente em X-API-Key.

Códigos de status

A primeira linha da resposta traz o código de status, e seu programa decide o que fazer em seguida com base nele:

CódigoO que significaO que fazer
200Requisição atendida, dados no corpoLer data e meta
304Dados inalterados desde a sua última respostaReutilizar os dados anteriores
401Chave ausente, inválida, revogada ou assinatura expiradaVerificar o cabeçalho e a assinatura
403Endpoint fora do seu plano (plan_restricted)Mudar de plano ou descartar a requisição
429Limite de requisições, downloads ou cota excedidoEsperar Retry-After segundos
503Dados em reconstrução (snapshot_not_ready)Tentar de novo após Retry-After segundos

Somente um 200 consome sua cota: um 304 e os erros são gratuitos, mas contam para o limite de requisições por segundo. Um 304 só volta para uma requisição com o cabeçalho If-None-Match; esse cabeçalho e os códigos 400, 404, 410 e 500 estão em Respostas e erros da Genesis API. Por que uma nova tentativa após um 429 precisa de uma pausa está explicado no verbete do glossário HTTP 429 Too Many Requests.

Primeira requisição: /account/usage

/account/usage mostra o estado da sua chave: plano, cota usada e limites. Está disponível em todos os planos e não gasta uma chamada, então sua primeira requisição vai para lá. Primeiro coloque a chave em uma variável de ambiente e depois envie a requisição:

# cole a chave e pressione Enter: ela não aparecerá na tela
read -s GENESIS_API_KEY
export GENESIS_API_KEY

curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: $GENESIS_API_KEY"

A opção -i imprime a linha de status e os cabeçalhos antes do corpo. O corpo da resposta, um exemplo ilustrativo para o plano Trial:

{
  "success": true,
  "data": {
    "plan": "trial",
    "calls_used": 0,
    "calls_limit": 500000,
    "rps_limit": 1,
    "freshness_sec": 60,
    "period_resets_at": 1796463000
  },
  "meta": {
    "count": 1,
    "updated_at": 1794730811,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

plan é o seu plano, e calls_used de calls_limit é o uso da cota no período de 30 dias. O exemplo mostra 0 porque nenhuma outra requisição foi feita ainda, e o próprio /account/usage não gasta uma chamada. rps_limit é o número de requisições por segundo, freshness_sec é a frequência de atualização dos dados do seu plano e period_resets_at é o momento em que a cota é reiniciada. Os campos estão descritos na seção Uso da documentação.

Entre os cabeçalhos, procure X-Request-Id, o ID da requisição que você envia ao suporte no lugar da sua chave, e X-RateLimit-Remaining, o número de requisições restantes na janela atual do limite.

A mesma requisição em Python

Um script para Python 3.10+ com a biblioteca requests lê a chave da mesma variável de ambiente:

import os
from datetime import datetime, timezone

import requests

BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"]  # KeyError se não estiver definida

r = requests.get(
    BASE + "/account/usage",
    headers={"X-API-Key": key},
    timeout=10,  # sem timeout, o requests pode esperar para sempre
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
    err = body.get("error") or {}
    raise SystemExit(f"{r.status_code} {err.get('code')}")

usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plano:", usage["plan"])
print("chamadas:", usage["calls_used"], "de", usage["calls_limit"])
print("a cota é reiniciada em:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))

os.environ["GENESIS_API_KEY"] interrompe o script se a variável não estiver definida, o que é melhor do que enviar uma requisição sem chave e receber um 401. r.headers não diferencia maiúsculas de minúsculas, então X-Request-Id é encontrado mesmo quando o servidor envia x-request-id.

period_resets_at é tempo unix: o número de segundos desde 1º de janeiro de 1970, 00:00 UTC. datetime.fromtimestamp(ts, timezone.utc) o transforma em uma data: 1796463000 é 5 de dezembro de 2026, 09:30 UTC.

Segunda requisição: taxas de financiamento (funding) do BTC

O funding é um pagamento periódico entre posições compradas e vendidas em um contrato futuro perpétuo, e as exchanges o liquidam a cada 8, 4 ou 1 hora. /funding/rates devolve as taxas de todas as exchanges, e o parâmetro coin as restringe a uma moeda. A resposta a GET /funding/rates?coin=BTC, um exemplo ilustrativo com duas exchanges da lista:

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "exchanges": [
        {
          "exchange": "Bitget",
          "funding_pct": 0.01,
          "funding_8h_pct": 0.01,
          "next_payout": "00:00",
          "interval": "8h",
          "price": 96021.5,
          "trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
        },
        {
          "exchange": "Hyper",
          "funding_pct": 0.0013,
          "funding_8h_pct": 0.0104,
          "next_payout": null,
          "interval": "1h",
          "price": 96030.0,
          "trade_url": "https://app.hyperliquid.xyz/trade/BTC"
        },
        …
      ]
    }
  ],
  "meta": {
    "count": 1,
    "updated_at": 1794675861,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

Como ler esta resposta:

Todos os campos estão na seção Taxas de funding da documentação. O próximo bloco continua o script: BASE, key e as importações já estão definidos.

r = requests.get(
    BASE + "/funding/rates",
    headers={"X-API-Key": key},
    params={"coin": "BTC"},  # o requests monta ?coin=BTC
    timeout=10,
)
r.raise_for_status()  # lança exceção em 4xx e 5xx
body = r.json()
if not body["data"]:
    raise SystemExit("moeda fora dos dados: verifique o ticker")

ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("snapshot de", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))

rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
    print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
          f'por {e["interval"] or "?"}, '
          f'{e["funding_8h_pct"]:>7}% por 8h')

Para a resposta de exemplo, o script imprime:

snapshot de 2026-11-14 17:04:21 UTC
Hyper     0.0013% por 1h,  0.0104% por 8h
Bitget      0.01% por 8h,    0.01% por 8h

A Hyper fica acima da Bitget mesmo que sua taxa por intervalo seja 0,01 / 0,0013 ≈ 7,7 vezes menor. Sem normalizar para 8 horas, essa comparação dá errado.

Erros comuns de iniciantes

ErroO que o servidor devolveComo corrigir
Chave na URL: ?api_key=…401 e "Missing X-API-Key header."Envie a chave somente no cabeçalho X-API-Key
Variável da chave vazia401 com o mesmo texto: o curl descarta um cabeçalho vazioVerifique o tamanho: echo ${#GENESIS_API_KEY}
Erro de digitação no caminho: /v1/funding/rate ou sem /v1404Confira o caminho na documentação
Erro de digitação no nome de um parâmetro: coins=BTC200 e todas as moedas: um parâmetro desconhecido é ignoradoVerifique meta.count: com coin=BTC ele é 1
Vírgula decimal: min_spread=0,5200 sem filtro aplicadoUse ponto: 0.5
Par em vez de ticker: coin=BTCUSDT200, data vazio, meta.count igual a 0Use o ticker da moeda: BTC

O erro de digitação em um parâmetro é o mais traiçoeiro: não há erro, mas o script recebe o conjunto completo de dados em vez de uma moeda e gasta uma chamada com isso. Depois de adicionar um filtro novo, compare meta.count com o que você espera.

Experimente você mesmo

  1. Envie uma requisição sem chave

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" devolve 401 com invalid_key e "Missing X-API-Key header." no corpo. Procure x-request-id entre os cabeçalhos.

  2. Repita com a chave

    Defina a variável com read -s e envie a requisição da seção /account/usage. Você recebe um 200 e seu plano em data.plan.

  3. Confira a data de reinício

    Execute o script em Python e compare a data de reinício da cota com a linha "reinicia …" do bloco "Genesis API" do seu perfil. Como obter uma chave passo a passo está no início rápido da Genesis API.

  4. Encontre a taxa mais alta

    Adicione o segundo bloco ao script e encontre a exchange com o maior funding_8h_pct. Normalize à mão o funding_pct dela para 8 horas: taxa × 8 / intervalo em horas.

  5. Quebre a requisição de propósito

    Troque coin por coins e compare meta.count; depois tire o s de /funding/rates e veja o código de status.

Quais endpoints servem para decidir com base em spreads, livros de ofertas e funding é o assunto da lição 3.

Perguntas e respostas

Posso chamar a API de um navegador?

Somente endereços que não precisam de chave: https://api.genesisarbitrage.com/health abre em um navegador e mostra {"ok":true}. A barra de endereço não consegue adicionar um cabeçalho X-API-Key, então requisições com chave passam pelo curl, por um script ou pelo formulário "Testar" da documentação. Nunca embuta a chave no código de um site ou de uma extensão: qualquer pessoa que abrir o código-fonte da página a verá.

Qual é a diferença entre a opção -i e -v no curl?

-i imprime a linha de status e os cabeçalhos da resposta antes do corpo. -v mostra também a própria requisição: as linhas com > são o que foi para o servidor e as linhas com < são o que voltou.

Como converter tempo unix em data sem Python?

No macOS, execute date -u -r 1796463000; no Linux, date -u -d @1796463000. Para esse número, ambos mostram 5 de dezembro de 2026, 09:30 UTC.