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 ambienteGENESIS_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
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».
Clique em «Obter chave»
O botão aparece no bloco «Genesis API» enquanto você não tem chave. A chave é criada na hora.
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.
Teste a chave com uma requisição
Chame
/account/usagecomo nos exemplos abaixo. Uma resposta200com seu plano emdata.plansignifica 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.
| Lugar | Pode? | Por quê |
|---|---|---|
| Variável de ambiente no servidor | Sim | A chave fica fora do código e do repositório |
Um arquivo .env listado no .gitignore | Sim | Carregado pelo python-dotenv (load_dotenv()) e pelo node --env-file=.env no Node.js 20.6+ |
| Segredos de hospedagem e de CI | Sim | A plataforma entrega a chave ao programa na inicialização; no GitHub Actions, um segredo do repositório passado pelo env do passo |
| Gerenciador de senhas | Sim | Uma cópia de reserva para uma pessoa |
| URL da requisição | Não | As 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óvel | Não | Quem abrir o código-fonte da página ou desempacotar o app vê a chave |
| Repositório público | Não | A chave fica no histórico de commits mesmo depois de apagar o arquivo |
| Capturas de tela, chats, tickets de suporte | Não | Mensagens 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ão | O que acontece | Quando usar |
|---|---|---|
| «Reemitir» | A chave antiga para de funcionar na hora e a janela «Sua chave de API» mostra uma nova | A 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:
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.Troque a chave em todos os programas
Atualize variáveis de ambiente, arquivos
.enve 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 seGENESIS_API_KEYjá está definida no ambiente: python-dotenv enode --env-filenão sobrescrevem com o valor do.envuma variável já definida.Confira o uso de chamadas
A linha «Chamadas usadas» no seu perfil ou uma requisição a
/account/usagemostra 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."
}
}
- O cabeçalho não chegou. «Missing X-API-Key header.» significa que a requisição não trazia chave nenhuma. Verifique o nome do cabeçalho e se a variável está definida onde o programa roda: no servidor, no contêiner, na tarefa agendada.
- A chave está corrompida. Um espaço a mais, aspas dentro do valor ou um final cortado resultam em
401: a chave precisa coincidir caractere por caractere. - A chave foi reemitida ou revogada. Compare o início da chave no seu programa com o que o perfil mostra em «Chave de API».
- A assinatura expirou. O perfil mostra «Assinatura expirada». Depois de «Renovar», a mesma chave volta a funcionar, sem precisar reemitir.
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.