Antes que um bot possa operar por você, a Freya precisa de uma conexão com a exchange onde seus fundos estão — Binance, OKX ou Bybit. Você não move seus fundos nem compartilha sua senha para fazer isso. Em vez disso, você cria uma chave API: uma credencial restrita que permite à Freya executar operações em seu nome, enquanto seu dinheiro permanece na sua própria conta da exchange.
Este guia explica exatamente quais permissões conceder (e quais nunca conceder), como adicionar a chave à Freya e o que fazer se a conexão não validar. Se você quer entender o panorama maior de por que isso é seguro, leia primeiro Meu Dinheiro Está Seguro na Freya Finance?.
Pontos-chave
- Você conecta uma exchange com uma chave API — uma credencial restrita — não movendo fundos nem compartilhando a senha da sua exchange.
- A chave precisa de permissões de Leitura e de trading Spot e/ou Futuros. Ela NUNCA deve ter permissão de saque.
- Chaves OKX exigem uma passphrase que você define ao criá-las; Binance e Bybit não exigem.
- Adicione a chave na Freya em Configurações → Chaves API → Adicionar Chave API, e a Freya a valida instantaneamente.
- Se a validação falhar, a Freya diz exatamente por quê — chave inválida, IP não autorizado na whitelist ou uma permissão ausente — e cada caso tem uma correção simples.
Uma Visão Geral Rápida dos Passos
- Crie uma chave API na sua exchange com permissões de leitura e trading, mas não de saque.
- Copie as credenciais — a chave API, a chave secreta e (para OKX) a passphrase.
- Adicione a chave à Freya em Configurações → Chaves API → Adicionar Chave API, e selecione sua exchange.
- Deixe a Freya validar — a Freya verifica a conexão e as permissões imediatamente.
- Corrija qualquer erro que ela reportar — a Freya diz exatamente o que está errado se a validação falhar.
O Que É uma Chave API — e Quais Permissões a Freya Precisa
Uma chave API é um par de credenciais (uma chave e uma secreta) que permite a um app conversar com sua conta da exchange de forma limitada. Você decide o que essa chave tem permissão para fazer. Para a Freya, habilite apenas:
- Leitura — para que a Freya possa ver seus saldos, posições e status de ordens.
- Trading Spot e/ou Trading Futuros — para que seu bot possa colocar as ordens de que precisa. Habilite o que corresponder aos bots que você planeja executar.
A Freya executa operações; ela nunca precisa mover dinheiro para fora da sua conta. Sempre deixe a permissão de saque desabilitada na chave que você conectar. Esta é uma permissão que você controla na exchange — com ela desligada, nem a Freya nem qualquer pessoa que venha a obter a chave pode sacar seus fundos. É o hábito mais importante ao conectar qualquer plataforma de bots.
Passo 1: Crie uma Chave API na Sua Exchange
Na seção de gerenciamento de API da sua exchange, crie uma nova chave API:
- Binance — crie a chave em API Management, habilite leitura e trading Spot e/ou Futuros, e deixe os saques desligados.
- OKX — crie a chave e defina uma passphrase (você precisará dela na Freya); habilite leitura e trading, não saques.
- Bybit — crie a chave com permissões de leitura e trading para os produtos que você usará, e deixe os saques desligados.
Se sua exchange oferece whitelist de IP, é uma boa prática restringir a chave aos endereços IP da Freya. Se fizer isso, certifique-se de adicionar os IPs da Freya à whitelist, ou a conexão será recusada (veja a tabela de erros abaixo).
Quando você cria a chave, a exchange mostra a chave secreta uma única vez. Copie-a imediatamente e guarde-a em segurança. Se você perdê-la, não poderá recuperá-la — terá que excluir a chave e criar uma nova.
Passo 2: Adicione a Chave à Freya
Na Freya, vá em Configurações → Chaves API e selecione Adicionar Chave API. Em seguida:
- Escolha sua exchange (Binance, OKX ou Bybit).
- Cole a chave API e a chave secreta. Para a OKX, insira também a passphrase que você definiu.
- Dê um nome à chave para que você possa reconhecê-la depois.
Você pode conectar mais de uma exchange e gerenciar ou excluir suas chaves nesta mesma página a qualquer momento.
Passo 3: A Freya Valida Sua Chave
Assim que você adiciona a chave, a Freya verifica a conexão e as permissões — sem adivinhação. Se tudo estiver correto, a chave é verificada e fica pronta para uso. Se algo estiver errado, a Freya mostra uma mensagem clara explicando exatamente o que corrigir.
Entendendo os Erros de Validação
Se a validação falhar, relacione a mensagem que a Freya mostra com a correção abaixo:
| O que a Freya mostra | O que significa | Como corrigir |
|---|---|---|
| Chave API Inválida | A chave foi copiada incorretamente ou excluída na exchange | Copie a chave API novamente com exatidão, ou crie uma nova |
| Chave Secreta Inválida | A chave secreta não corresponde à chave | Copie a chave secreta novamente; se você a perdeu, crie uma nova chave |
| Endereço IP Não Autorizado | A chave é restrita por IP e o endereço da Freya não é permitido | Adicione os IPs da Freya à whitelist da chave, ou remova a restrição de IP |
| Permissões Ausentes | A chave não tem permissão de leitura ou de trading | Habilite leitura e trading Spot/Futuros na chave |
| Permissão de Leitura Desabilitada | A Freya não consegue ler sua conta | Habilite a permissão de leitura/visualização na chave |
| Permissão de Spot/Futuros Desabilitada | A chave não pode colocar as ordens de que seu bot precisa | Habilite o tipo de trading (Spot ou Futuros) que corresponde ao seu bot |
| Conexão Falhou | Um problema temporário de rede ou da exchange | Aguarde um momento e tente adicionar a chave novamente |
A Freya também sinalizará uma chave que está no modo "Sem Restrições" — ou seja, que não tem restrição de IP. Para sua segurança, a Freya pede que você ative a restrição de IP e adicione o endereço que ela mostra antes que a chave possa ser salva. Habilite apenas leitura e trading (nunca saque), e restrinja a chave ao IP da Freya. (Mais sobre erros de conexão em Não Consegue Conectar Sua Exchange?.)
Uma Nota Sobre Segurança
A conexão é segura por design, mas alguns hábitos mantêm-na assim:
- Saque desligado, sempre — a Freya nunca precisa dele.
- Use whitelist de IP quando sua exchange suportar.
- Uma chave, um propósito — e exclua chaves que você não usa mais.
Para o panorama completo de como seus fundos e chaves são protegidos, veja Meu Dinheiro Está Seguro na Freya Finance? e Segurança de API da Exchange e Mitigação de Riscos.
Perguntas Frequentes
Quais permissões a Freya precisa na minha chave API?
Leitura (para ver seus saldos, posições e ordens) e trading Spot e/ou Futuros (para colocar as ordens do seu bot). Habilite o tipo de trading que corresponde aos bots que você vai executar. A Freya nunca precisa de permissão de saque, então sempre deixe essa desabilitada.
A Freya precisa de permissão para sacar meus fundos?
Não. A Freya apenas coloca e gerencia operações; ela não pode e não deve ser capaz de mover fundos para fora da sua exchange. Sempre deixe a permissão de saque desligada na chave que você conectar — é uma permissão que você controla na exchange.
Por que a Freya diz "Endereço IP Não Autorizado"?
Sua chave API está restrita a endereços IP específicos, e o endereço da Freya não está na lista. Adicione os endereços IP da Freya à whitelist da chave na sua exchange, ou remova a restrição de IP da chave. Após atualizá-la, adicione a chave na Freya novamente.
Por que aparece "Chave API Inválida" ou "Chave Secreta Inválida"?
Geralmente a chave ou a secreta foi copiada incorretamente, ou a chave foi excluída ou regenerada na exchange. Copie ambos os valores novamente com exatidão. Como a chave secreta é mostrada apenas uma vez ao criar a chave, se você não a tem mais, exclua a chave na exchange e crie uma nova.
O que é a passphrase, e por que a OKX a solicita?
Chaves API da OKX incluem uma passphrase que você mesmo define ao criar a chave — é uma credencial extra junto da chave e da secreta. Insira a mesma passphrase na Freya ao adicionar uma chave OKX. Binance e Bybit não usam passphrase.
Posso conectar mais de uma exchange?
Sim. Você pode adicionar chaves API para Binance, OKX e Bybit, e gerenciá-las ou excluí-las a qualquer momento em Configurações → Chaves API.
É seguro dar minha chave API à Freya?
Sim, quando a chave é configurada corretamente — apenas leitura e trading, sem saque, e com whitelist de IP onde possível. Seus fundos permanecem na sua própria exchange, e a chave que você compartilha não consegue movê-los. Para a explicação completa, veja Meu Dinheiro Está Seguro na Freya Finance?.
Quais exchanges a Freya suporta?
A Freya atualmente se conecta a Binance, OKX e Bybit (spot e futuros). Mais exchanges podem ser adicionadas com o tempo. Você opera naquela que conectar — seus fundos e os mercados disponíveis permanecem nessa exchange.
Quais moedas ou pares de trading posso operar?
Os pares disponíveis vêm das próprias listagens da exchange que você conectou, não de uma lista separada da Freya — então, se sua exchange lista um par (ex.: BTC/USDT, ETH/USDT), você pode construir um bot com ele. A maioria das operações é contra USDT como moeda de cotação. Se uma exchange deslista um par, ele deixa de ser negociável ali.