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:
200significa ler os dados,304que nada mudou,401e403que é preciso verificar a chave e o plano,429e503que é preciso esperarRetry-Aftersegundos. - A resposta da Genesis API é um envelope com
success,dataemeta. As porcentagens chegam como números simples (0.01significa 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
| Parte | No exemplo | O que significa |
|---|---|---|
| Método | GET | Ler dados; todos os endpoints da Genesis API são GET |
| URL base | https://api.genesisarbitrage.com/v1 | Servidor e versão da API |
| Caminho | /funding/rates | O endpoint de taxas de financiamento (funding) |
| Parâmetros | ?coin=BTC | Filtro: somente BTC |
| Cabeçalho | X-API-Key | A 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ódigo | O que significa | O que fazer |
|---|---|---|
200 | Requisição atendida, dados no corpo | Ler data e meta |
304 | Dados inalterados desde a sua última resposta | Reutilizar os dados anteriores |
401 | Chave ausente, inválida, revogada ou assinatura expirada | Verificar o cabeçalho e a assinatura |
403 | Endpoint fora do seu plano (plan_restricted) | Mudar de plano ou descartar a requisição |
429 | Limite de requisições, downloads ou cota excedido | Esperar Retry-After segundos |
503 | Dados 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:
- o envelope:
successétrue, os dados ficam emdatae os campos de serviço emmeta;meta.counté o número de itens emdata, que paracoin=BTCé uma moeda, com um arrayexchangesdentro; - as porcentagens chegam como números simples:
"funding_pct": 0.01significa 0,01 % por intervalo, não 1 %; em uma posição de US$ 10.000, um pagamento a essa taxa é 10.000 × 0,01 / 100 = US$ 1; funding_8h_pctnormaliza a taxa para 8 horas, de modo que exchanges com intervalos diferentes possam ser comparadas diretamente: a Hyper liquida a cada hora, e 0.0013 × 8 = 0,0104 % por 8 horas;next_payouté o horário do próximo pagamento em UTC como uma string "HH:MM", enullsignifica sem dados, não zero;meta.updated_até o tempo unix em que o snapshot foi gerado: 1794675861 é 14 de novembro de 2026, 17:04:21 UTC; no Trial o snapshot é atualizado a cada 60 segundos.
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
| Erro | O que o servidor devolve | Como 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 vazia | 401 com o mesmo texto: o curl descarta um cabeçalho vazio | Verifique o tamanho: echo ${#GENESIS_API_KEY} |
Erro de digitação no caminho: /v1/funding/rate ou sem /v1 | 404 | Confira o caminho na documentação |
Erro de digitação no nome de um parâmetro: coins=BTC | 200 e todas as moedas: um parâmetro desconhecido é ignorado | Verifique meta.count: com coin=BTC ele é 1 |
Vírgula decimal: min_spread=0,5 | 200 sem filtro aplicado | Use ponto: 0.5 |
Par em vez de ticker: coin=BTCUSDT | 200, data vazio, meta.count igual a 0 | Use 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
Envie uma requisição sem chave
curl -i "https://api.genesisarbitrage.com/v1/account/usage"devolve401cominvalid_keye "Missing X-API-Key header." no corpo. Procurex-request-identre os cabeçalhos.Repita com a chave
Defina a variável com
read -se envie a requisição da seção/account/usage. Você recebe um200e seu plano emdata.plan.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.
Encontre a taxa mais alta
Adicione o segundo bloco ao script e encontre a exchange com o maior
funding_8h_pct. Normalize à mão ofunding_pctdela para 8 horas: taxa × 8 / intervalo em horas.Quebre a requisição de propósito
Troque
coinporcoinse comparemeta.count; depois tire osde/funding/ratese 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.