Chaves de API

Como deixar os seus scripts e ferramentas lerem os seus bots e sinais, e gerenciar bots, sem fazer login: criar uma chave, o que cada escopo permite, a requisição exata, os limites e como guardar a chave com segurança.

O webhook é o Okkana chamando o seu servidor. A chave de API é o caminho contrário: o seu script, automação ou programa chama o Okkana, prova quem é com a chave e lê ou altera os seus dados sem login.

Uma chave alcança duas coisas da sua conta: os seus bots e os seus sinais. Ela lista e lê os dois e, se você permitir, cria, edita, pausa, duplica e apaga bots. Serve para exportar sinais para uma planilha, pausar bots num fluxo do n8n ou deixar um agente de IA montar um bot.

Ela não alcança dados de mercado, o seu perfil, o seu webhook nem o feed ao vivo, e não cria outras chaves. O Okkana continua sem enviar ordens.

No seu perfil, em Chaves de API, dê à chave um nome que diga onde ela vai rodar, como o nome da ferramenta, e escolha o acesso: Leitura, que lista e lê bots e sinais, ou Leitura e escrita, que também cria, edita e apaga bots.

A chave começa com okk_ seguido de 43 letras e dígitos. O Okkana a mostra uma única vez, na criação. Só uma impressão digital irreversível é guardada, então uma chave perdida não se recupera: revogue e crie outra.

Você pode ter até 10 chaves ativas. Use uma por ferramenta, para revogar uma sem parar as outras.

Uma chave carrega escopos, e cada rota pede um. O bots:read lista bots e lê um com as estatísticas. O signals:read lista os seus sinais, todos ou de um bot, e lê um com condições, desempenho e MFE/MAE. O bots:write cria, substitui, pausa ou ativa, duplica e apaga bots.

Um escopo não inclui o outro: uma chave só com bots:write não lista bots. Os dois presets do perfil são Leitura, com bots:read e signals:read, e Leitura e escrita, com os três.

Uma chave cujos escopos não cobrem a rota recebe 403. O mesmo vale para qualquer chave numa rota que não é aberta a chaves: mercados, o seu perfil, o webhook, alertas, o diário de operações, o feed ao vivo e a gestão de chaves.

O catálogo de métricas, templates e mercados com que se monta uma regra é público e não pede chave.

Envie a chave no header Authorization como Bearer okk_…, por HTTPS, em toda requisição. Guarde a chave e o endereço da API em variáveis de ambiente.

Corpos e respostas são JSON com nomes em camelCase. Preços e quantidades são strings decimais e os horários são UTC. As listas respondem com items, nextCursor e asOf: devolva o nextCursor como cursor para ler a próxima página, e use limit para o tamanho da página. Os sinais aceitam botId para listar os de um bot.

Criar ou substituir um bot passa pela mesma validação do construtor de bots, e um corpo recusado responde com os campos que falharam.

Cada chave tem o seu próprio limite numa janela de um minuto, contado à parte para leituras (GET) e escritas (o resto): 120 leituras e 30 escritas por padrão. Toda resposta de uma rota aberta a chaves traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, o horário Unix em que a janela termina.

Acima do limite a resposta é 429 com um Retry-After em segundos: espere esse tempo. Um 401 quer dizer que a chave não vale: digitada errada, revogada, expirada ou de uma conta apagada. Um 403 quer dizer que a chave vale, mas os escopos ou a rota não permitem a requisição.

Os erros têm um formato só, com código, mensagem e um id da requisição para citar se precisar de ajuda.

A lista de chaves no seu perfil mostra o nome, os primeiros caracteres, os escopos, a data de criação e o último uso, atualizado no máximo uma vez por minuto. Uma chave que você não reconhece, ou usada quando você não esperava, é motivo para revogar.

Revogar vale na hora: a próxima requisição com essa chave responde 401.

A chave fica no servidor que faz as requisições, numa variável de ambiente ou num cofre de credenciais, como o da sua ferramenta de automação. Nunca numa página web, num código de front-end, num app que você distribui, num repositório git ou numa captura de tela: quem a tiver faz o que os escopos permitem. Prefira Leitura quando a ferramenta só lê.

Um bot criado por uma chave é um bot comum: aparece no app, conta no seu limite de bots, dispara sinais, e os sinais e as estatísticas dele são iguais aos de qualquer outro.

O Okkana registra qual chave criou ou editou a definição de um bot, nessa versão do bot. Pausar, ativar e apagar não são versões, então nada é acrescentado ao histórico do bot por eles.

Se a chave for revogada depois, os bots que ela criou continuam.