Guia da API da WEEX: Configuração, Chamadas, Permissões e Segurança

Se você deseja que um código busque preços, faça ordens e gerencie sua conta para você, a primeira coisa a acertar é como a API da WEEX é aberta, chamada e, acima de tudo, como suas permissões são definidas. A API da WEEX é um conjunto de interfaces de programação que a WEEX abre para desenvolvedores e traders quantitativos, expondo acesso REST e WebSocket para que você possa extrair dados de mercado, colocar e cancelar ordens e consultar contas sem precisar olhar para uma tela. Este guia segue um único fio condutor — o que é, como usar, como chamar e se é seguro — e dedica seu peso à parte que a maioria dos tutoriais ignora: permissões e segurança da API, que é exatamente onde as coisas tendem a dar errado com os fundos.

Todos os parâmetros de interface abaixo vêm da documentação oficial da API da WEEX e refletem informações públicas a partir de julho de 2026. As regras da API podem mudar, portanto, confirme no centro de desenvolvedores ao vivo antes de integrar.

O que é a API da WEEX: Um mapa rápido de capacidades

Em uma linha: a API da WEEX é o canal que permite que o código opere sua conta, dividido em "público" e "privado". Endpoints públicos retornam dados de mercado e configuração do sistema e não precisam de autenticação; endpoints privados lidam com colocação de ordens, cancelamento e gerenciamento de conta, e cada solicitação deve ser assinada. No lado do produto, cobre tanto spot quanto futuros com margem em USDT em mais de 100 ativos.

Escolher entre REST e WebSocket depende se você quer "perguntar uma vez" ou "continuar ouvindo". Verifique um saldo ou dispare uma única ordem via REST; para receber ticks de preço ao vivo, mudanças de profundidade ou execuções de ordens, mantenha uma conexão WebSocket — é mais simples e mais oportuno.

Como obter sua chave de API da WEEX

Faça login na plataforma web da WEEX e crie uma chave na página de gerenciamento de API. O sistema gera três coisas de uma vez, e você precisa de todas as três:

• APIKey — um identificador gerado algoritmicamente, efetivamente seu "nome de usuário".
• SecretKey — a chave privada emitida pelo sistema usada para assinar cada solicitação.
• Passphrase — uma frase de acesso que você mesmo define. Observe com atenção: se a Passphrase for perdida, ela não pode ser recuperada — você deve excluir o grupo de chaves e criar um novo.

Cada conta pode criar até 10 grupos de chaves de API, o que permite emitir chaves separadas por estratégia e por ambiente. Duas escolhas na criação definem o piso de segurança para uma chave: as permissões que você marca (próxima seção) e o IP que você vincula. A WEEX sinaliza explicitamente que uma chave "irrestrita" sem vinculação de IP é um risco de segurança — se o IP do seu servidor for fixo, preencha a lista de permissões de IP.

Permissões da API da WEEX: Onde a leitura e o trade param

Esta é a seção para ler duas vezes. Uma chave de API recém-criada tem como padrão "Somente leitura". Para negociar através da API, você deve habilitar manualmente a permissão de negociação "Spot" correspondente. Muita permissão significa uma perda maior se a chave vazar; pouca e a estratégia não pode ser executada. A regra é uma linha: conceda o mínimo que a estratégia realmente precisa.

Um detalhe fácil de perder, mas que importa para a segurança: a partir de julho de 2026, as permissões listadas nos documentos de início rápido da API spot da WEEX são exatamente essas duas — Somente leitura e Negociação Spot — sem um botão separado de "saque". Para a maioria das estratégias, isso é um recurso, não uma lacuna: mesmo se uma chave vazar, quem a detém não pode retirar ativos diretamente. Trate as opções mostradas na sua página real de criação de chave como a fonte da verdade.

Como chamar: O que uma solicitação assinada precisa

Toda a barreira para endpoints privados é o passo de "assinar". A WEEX gera assinaturas com HMAC SHA256: criptografe a string pré-assinatura com sua SecretKey, então codifique o resultado em Base64. A string pré-assinatura é montada em uma ordem fixa:

timestamp + method (maiúsculo) + requestPath + "?" + queryString + body

A queryString é omitida quando vazia. Tome uma solicitação de profundidade GET como exemplo: /api/v3/market/depth?symbol=BTCUSDT&limit=20 com timestamp 1591089508404 produz a string pré-assinatura 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20.

Uma vez assinada, cada solicitação privada carrega quatro cabeçalhos:

Canais WebSocket privados funcionam da mesma maneira — assine o timestamp mais o caminho da solicitação /v3/ws/private para fazer login. O ponto onde a maioria dos iniciantes fica preso não é a criptografia, é o timestamp: se o timestamp da sua solicitação desviar do tempo do servidor em mais de 30 segundos, a solicitação é rejeitada imediatamente. Um relógio local errado ou um timestamp em cache obsoleto lançarão um erro 401 inexplicável. Sincronizar o tempo NTP antes de entrar no ar economiza metade da depuração. Campos completos e exemplos estão no documento de preparação de integração oficial e na referência de assinatura.

Limites de taxa e regras de acesso que vale a pena conhecer

Você não pode chamar tão rápido quanto quiser. O limite padrão é 10 solicitações/segundo, com alguns endpoints declarando seus próprios limites em seus documentos; excedê-lo retorna 429 Too Many Requests. Atenção à base de contagem: solicitações autenticadas são medidas por chave de API, as não autenticadas por IP público — o que significa que vários scripts somente leitura em um servidor compartilhando um IP de saída podem excluir uns aos outros da cota de endpoint público.

Uma regra de lote vale a pena lembrar: uma ordem em lote abrangendo 4 pares de negociação com 10 ordens cada conta como uma única solicitação. Agrupar ordens permite que uma estratégia de alta frequência aumente o throughput e conserve a cota ao mesmo tempo.

A API da WEEX é segura? Separe o controlável do não controlável

"É seguro" merece algo melhor do que um sim/não. No lado da plataforma, você obtém autenticação assinada, vinculação de IP, permissões em camadas e proteção contra repetição baseada em timestamp. Mas em cenários de API, a maioria dos incidentes acontece do lado do usuário — chaves armazenadas descuidadamente, permissões com escopo muito amplo, credenciais inseridas em um front-end ou em um repositório público. A parte controlável está inteiramente em suas mãos:

• Escopo de permissões ao mínimo; uma estratégia somente leitura nunca deve ter permissão de trade.
• Vincule um IP fixo a cada chave — sem chaves irrestritas.
• Mantenha SecretKey e Passphrase em variáveis de ambiente ou em um gerenciador de segredos, nunca codificadas no código do lado do cliente ou comprometidas com o Git.
• Use chaves diferentes para desenvolvimento e produção para que não possam contaminar umas às outras.
• Gire as chaves em um cronograma e, no momento em que vir chamadas anormais, exclua a chave na plataforma web — uma chave pode ser revogada e reconstruída a qualquer momento, e essa é a maneira mais rápida de parar o sangramento.
• Coloque monitoramento e alertas na atividade da conta e no volume de chamadas para que frequências ou ordens incomuns apareçam imediatamente.

Para uma visão geral mais ampla de capacidades e perguntas comuns, veja o explicador da WEEX sobre se a WEEX suporta negociação via API. Acerte a lista de verificação acima, e a segurança da API da WEEX se resume principalmente à higiene da sua chave, em vez de qualquer coisa misteriosa.

A versão curta

O caminho para a API da WEEX é realmente limpo: crie uma chave de API com permissões mínimas na plataforma web (Somente leitura por padrão, trade habilitado manualmente), colete o trio APIKey / SecretKey / Passphrase e vincule um IP; ao chamar endpoints privados, assine com HMAC SHA256 no formato fixo, envie todos os quatro cabeçalhos e respeite a janela de timestamp de 30 segundos e o limite de 10 solicitações por segundo; finalmente, bloqueie a higiene da chave, permissões de privilégio mínimo, lista de permissões de IP e alertas. Para começar na prática, execute sua primeira solicitação contra os endpoints de mercado públicos no centro de desenvolvedores da WEEX, depois adicione a colocação de ordens privadas.

FAQ

1. A WEEX suporta negociação via API?

Sim. A WEEX oferece interfaces REST e WebSocket para dados de mercado automatizados, colocação e cancelamento de ordens e gerenciamento de conta, em spot e futuros com margem em USDT — adequados para bots quantitativos, de grade e de market-making.

2. Quantas chaves de API uma conta pode criar?

Até 10 grupos. É melhor dividi-las por estratégia e ambiente — uma chave de monitoramento somente leitura, uma chave de negociação spot, uma chave de dev/teste — para que funcionem de forma independente e possam ser revogadas individualmente.

3. E se eu esquecer a Passphrase?

Ela não pode ser recuperada. A Passphrase é uma frase que você define na criação, e o sistema não a armazena em texto simples. Se perdida, você exclui esse grupo de chaves de API e cria um novo.

4. Por que minhas solicitações privadas continuam sendo rejeitadas?

A causa mais comum é o timestamp. Se o timestamp da sua solicitação desviar do tempo do servidor WEEX em mais de 30 segundos, ela é rejeitada — sincronize seu relógio local primeiro. Em seguida, verifique a ordem da string pré-assinatura, se o nome do método está em maiúsculo e se todos os quatro cabeçalhos estão presentes.

5. Se minha chave de API vazar, um invasor pode sacar minhas moedas?

Para a API spot, o risco é relativamente contido — a partir de julho de 2026, as permissões documentadas são apenas Somente leitura e Negociação Spot, sem permissão de saque autônoma. Mesmo assim, exclua a chave vazada na plataforma web imediatamente e verifique se há ordens anormais.

6. Existem limites de taxa nas chamadas?

Sim. O padrão é 10 solicitações/segundo; excedê-lo retorna 429. Solicitações autenticadas são contadas por chave de API e as não autenticadas por IP. Uma ordem em lote (ex: 4 pares com 10 ordens cada) conta como uma solicitação, que estratégias de alta frequência podem usar para economizar cota.

Aviso de risco

Ativos digitais são altamente voláteis, e a negociação programática através de uma API pode amplificar em vez de reduzir o risco, levando potencialmente à perda parcial ou total do principal. Riscos específicos para negociação via API incluem roubo ou ordens não autorizadas de uma chave vazada, ordens erradas em cascata de um erro de lógica de código, ordens falhas por latência de rede ou desvio de timestamp, ser limitado por exceder limites de chamada e perder o mercado, e risco de liquidação sob alavancagem de futuros. Sempre escope chaves para privilégio mínimo, vincule um IP, proteja sua SecretKey e Passphrase e teste exaustivamente em um ambiente de pequeno porte antes de entrar no ar. Este artigo é apenas um guia técnico de integração e não é um conselho de investimento.