Genesis Arbitrage

Genesis Arbitrage · · 9 min de leitura

Chave da Genesis API: como obter, onde guardar, como reemitir e revogar

Em resumo

  • Uma chave gns_live_… é criada no seu perfil com o botão «Obter chave» e aparece só uma vez. Guardamos apenas o hash, então uma chave perdida não se recupera: é reemitida.
  • A chave vai no cabeçalho X-API-Key, a partir do seu próprio servidor. O código a lê da variável de ambiente GENESIS_API_KEY; ela nunca vai na URL de uma requisição nem no código de um site.
  • Se a chave vazar, clique em «Reemitir»: a chave antiga para de funcionar na hora e você a troca em todos os programas. Cada conta tem uma única chave.

Uma chave de API da Genesis API é uma string gns_live_… que funciona como uma senha: o servidor a usa para identificar sua conta e seu plano. Você a envia em cada requisição no cabeçalho HTTP X-API-Key; sem chave, ou com uma chave errada, a API responde 401 invalid_key. Cada conta tem uma única chave, que você obtém, reemite e revoga no seu perfil da Genesis Arbitrage.

Onde fica a chave

Você gerencia a chave no perfil, no bloco «Genesis API»; os demais blocos do perfil são tratados no guia do perfil da conta. O bloco mostra sua assinatura da API e o estado da chave:

O que você vêO que significa
«Assinatura inativa», botão «Assinar»Ainda não há plano de API; o botão abre os planos
«Assinatura ativa», «Ativa até …», botão «Renovar»O plano vale até essa data
«Assinatura expirada», botão «Renovar»O prazo acabou: a chave é rejeitada e os botões da chave ficam ocultos até a renovação
«Nenhuma chave criada», botão «Obter chave»Você tem um plano, mas ainda não tem chave
«Chave de API» e gns_live_…O início da chave ativa; a chave completa nunca mais é exibida
«criada em …» · «usada em …»Quando a chave foi criada e quando fez a última requisição
«Chamadas usadas», «req/s», «atualização», «reinicia em …»Cota consumida, limite de requisições por segundo, atraso dos dados e data em que o contador reinicia

O link «Documentação» no canto do bloco abre a documentação da Genesis API. A cota e os limites são explicados no guia dos limites da Genesis API.

Como obter a chave

  1. Assine um plano de API

    Na página de preços da Genesis API, escolha Trial, Start, Pro ou Max e um período, clique em «Assinar» e pague a fatura em cripto. O status no perfil muda para «Assinatura ativa».

  2. Clique em «Obter chave»

    O botão aparece no bloco «Genesis API» enquanto você não tem chave. A chave é criada na hora.

  3. Salve a chave na janela «Sua chave de API»

    A janela mostra a chave completa uma única vez. Clique em «Copiar» e guarde a chave em um gerenciador de senhas ou direto nas variáveis protegidas do seu servidor. Depois de «Concluir», você não vê mais a chave completa: guardamos só o hash dela.

  4. Teste a chave com uma requisição

    Chame /account/usage como nos exemplos abaixo. Uma resposta 200 com seu plano em data.plan significa que a chave foi aceita.

Como enviar a chave

A chave vai somente no cabeçalho X-API-Key. O servidor não lê a chave de parâmetros da URL nem do cabeçalho Authorization e responde 401. Os exemplos leem a chave da variável de ambiente GENESIS_API_KEY; a URL base é https://api.genesisarbitrage.com/v1.

curl:

# a chave vem de uma variável de ambiente
curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: $GENESIS_API_KEY"

Python 3.10+ com a biblioteca requests:

import os

import requests

# os.environ[...] falha na hora se a variável não estiver definida
key = os.environ["GENESIS_API_KEY"]

r = requests.get(
    "https://api.genesisarbitrage.com/v1/account/usage",
    headers={"X-API-Key": key},
    timeout=10,
)
r.raise_for_status()
print(r.json()["data"]["plan"])

JavaScript, Node.js 18+ com o fetch nativo:

// arquivo .mjs: módulos permitem top-level await
const key = process.env.GENESIS_API_KEY;
if (!key) throw new Error('GENESIS_API_KEY não está definida');

const res = await fetch(
  'https://api.genesisarbitrage.com/v1/account/usage',
  { headers: { 'X-API-Key': key } },
);
const body = await res.json();
console.log(res.status, body.data?.plan);

As três requisições retornam a mesma resposta (valores ilustrativos):

{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

Os campos da resposta estão descritos na seção Uso da documentação.

Onde guardar a chave

Uma chave da Genesis API só lê dados: com ela não dá para operar nem sacar fundos. Um vazamento custa outra coisa: programas de terceiros consomem sua cota e seu limite de requisições por segundo.

LugarPode?Por quê
Variável de ambiente no servidorSimA chave fica fora do código e do repositório
Um arquivo .env listado no .gitignoreSimCarregado pelo python-dotenv (load_dotenv()) e pelo node --env-file=.env no Node.js 20.6+
Segredos de hospedagem e de CISimA plataforma entrega a chave ao programa na inicialização; no GitHub Actions, um segredo do repositório passado pelo env do passo
Gerenciador de senhasSimUma cópia de reserva para uma pessoa
URL da requisiçãoNãoAs URLs vão parar nos logs do servidor e do proxy e no histórico do navegador
Código de site, extensão ou app móvelNãoQuem abrir o código-fonte da página ou desempacotar o app vê a chave
Repositório públicoNãoA chave fica no histórico de commits mesmo depois de apagar o arquivo
Capturas de tela, chats, tickets de suporteNãoMensagens e imagens são encaminhadas

Se os dados precisam chegar a um navegador, como um painel ou uma extensão, seu servidor chama a Genesis API e o navegador recebe do seu servidor o resultado pronto. O suporte precisa do X-Request-Id da resposta, do horário da requisição em UTC, do endpoint e do status, nunca da chave. Chaves de exchange com permissão de trading são mais arriscadas; como restringi-las está em como proteger sua conta de exchange cripto.

Reemitir e revogar

BotãoO que aconteceQuando usar
«Reemitir»A chave antiga para de funcionar na hora e a janela «Sua chave de API» mostra uma novaA chave vazou ou foi perdida, ou saiu alguém que a conhecia
«Revogar»A chave é desligada sem substituta e o acesso à API é fechado; o bloco volta a mostrar «Obter chave»Você não precisa mais da chave

Os dois botões pedem confirmação antes. Os diálogos dizem «Reemitir a chave? A chave atual deixa de funcionar imediatamente.» e «Revogar a chave? Ela deixa de funcionar na hora e o acesso à API é fechado.», com «Cancelar» e «Confirmar». Se a chave vazou:

  1. Reemita a chave

    Clique em «Reemitir», depois em «Confirmar», e salve a nova chave na janela «Sua chave de API». A partir desse momento, requisições com a chave antiga recebem 401.

  2. Troque a chave em todos os programas

    Atualize variáveis de ambiente, arquivos .env e segredos de CI e de hospedagem, e reinicie os programas: um processo lê o ambiente na inicialização. Se um programa ainda envia a chave antiga, verifique se GENESIS_API_KEY já está definida no ambiente: python-dotenv e node --env-file não sobrescrevem com o valor do .env uma variável já definida.

  3. Confira o uso de chamadas

    A linha «Chamadas usadas» no seu perfil ou uma requisição a /account/usage mostra quantas chamadas foram gastas no período. Reemitir não zera o contador.

401 invalid_key: o que verificar

O servidor responde 401 com o código invalid_key quando a chave está ausente, errada ou revogada, ou quando a assinatura expirou:

{
  "success": false,
  "error": {
    "code": "invalid_key",
    "message": "Missing X-API-Key header."
  }
}

Se o cabeçalho chegou mas a chave foi rejeitada, message lista de uma vez todos os motivos possíveis. Uma resposta 403 plan_restricted significa outra coisa: a chave foi aceita, mas o endpoint não faz parte do seu plano. Os demais códigos estão na seção Erros e no guia de respostas e erros da Genesis API.

O formulário «Testar» na documentação

Cada endpoint da documentação tem um formulário «Testar». Cole a chave no campo «Sua chave de API (gns_live_…)» e clique em «Enviar requisição»: o código de status, o tempo de resposta e uma resposta resumida aparecem abaixo do formulário. A chave fica só no seu navegador e não é enviada a lugar nenhum além da API.

O navegador lembra a chave e preenche o campo na próxima visita, então não use o formulário no computador de outra pessoa. Uma requisição do formulário é uma chamada de API comum: usa a cota e o limite de requisições por segundo como uma requisição feita por código. Sua primeira requisição por código, com a resposta explicada, está no início rápido da Genesis API.

Perguntas e respostas

Posso ter uma chave separada para cada bot?

Não, cada conta tem uma única chave. Todos os programas que a usam dividem a cota de chamadas e o limite de requisições por segundo. Se os limites ficarem apertados, mude de plano: abrir várias contas para contornar os limites viola as regras.

Reemitir zera o contador de chamadas?

Não. «Chamadas usadas» pertence à assinatura da conta, não à chave: a nova chave continua o mesmo período de 30 dias.

Posso escrever o cabeçalho em minúsculas, x-api-key?

Sim. Nomes de cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, regra definida na RFC 9110, seção 5.1. A chave em si deve ser enviada sem alterações.

Preciso de uma chave nova depois de renovar?

Não. Enquanto a assinatura está expirada, a chave recebe 401, e depois de «Renovar» a mesma chave volta a funcionar.