Melhores Práticas

Gestão de ligações

Abra uma única ligação WebSocket e reutilize-a para cada pedido e subscrição, em vez de abrir uma ligação por chamada. Multiplexe pedidos através do socket partilhado e associe cada resposta ao respetivo pedido utilizando req_id.

Quando a ligação cair, restabeleça-a com recuo exponencial (por exemplo, 1s, 2s, 4s, 8s, com limite máximo) mais um pequeno jitter, em vez de tentar novamente em ciclo fechado. Envie um ping periódico para manter a ligação ativa e detetar desconexões silenciosas antecipadamente.

// keepalive: send a ping on an interval over the shared socket
setInterval(() => socket.send(JSON.stringify({ ping: 1 })), 30000);

Limitação de taxa e throttling de pedidos

Limite as solicitações de saída para permanecer dentro dos limites de taxa da API. Coloque as chamadas em fila e regule o seu ritmo em vez de enviar grandes volumes de uma só vez, e utilize debounce nas ações iniciadas pelo utilizador para que uma única interação não gere múltiplos pedidos.

Se atingir o limite de taxa, recue de forma exponencial antes de tentar novamente, aumentando o intervalo após cada rejeição. Prefira subscrições em vez de polling para dados que se atualizam continuamente, para que o servidor envie as alterações em vez de as ter de solicitar novamente.

Quando repetir uma operação não idempotente, como uma compra ou levantamento, forneça um id de pedido para poder consultar o estado final e reconciliar o resultado, em vez de reenviar sem verificação e arriscar uma duplicação.

Para os valores em si — os limites de pedidos por IP e por conta, e os orçamentos partilhados pelos grupos de chamadas WebSocket — consulte Limites.

Autenticação e gestão de tokens

Autentique uma ligação uma única vez, enviando authorize com um token válido antes de efetuar pedidos com âmbito de conta. Utilize tokens com o menor privilégio que a tarefa requer, solicitando apenas os âmbitos de que os seus endpoints necessitam, como trade ou account_manage; um token que não possua um âmbito necessário é rejeitado com um erro 403.

Para aplicações orientadas ao utilizador, utilize o fluxo OAuth 2.0 Authorization Code com PKCE em vez de incorporar tokens. Execute sempre a troca de tokens no seu backend, não no browser, e valide o parâmetro state na callback antes de utilizar o código de autorização. Os códigos de autorização são de utilização única e de curta duração, pelo que deve trocá-los imediatamente e nunca os armazenar ou registar. Gere um novo code_verifier e state para cada pedido, e elimine-os assim que a troca for concluída com êxito. Os tokens de acesso têm uma duração curta, tipicamente uma hora, pelo que deve gerir a expiração atualizando o token ou reexecutando o fluxo de autorização, em vez de assumir que permanece válido. Consulte o guia OAuth 2.0 para a implementação completa.

Nunca incorpore tokens de API de longa duração em código do lado do cliente, repositórios públicos ou artefactos de compilação. Armazene os segredos do lado do servidor, rode-os regularmente e revogue qualquer token que possa ter sido exposto.

// authenticate the connection before account-scoped calls
socket.send(JSON.stringify({ authorize: "<your-token>" }));

Tratamento de erros e limpeza de subscrições

Verifique sempre o campo error em cada resposta antes de utilizar os seus dados, e registe o código e a mensagem de erro no seu próprio sistema de logging. Associe as respostas aos pedidos utilizando req_id para que uma falha seja atribuída à chamada correta.

Cancele as subscrições de que já não necessita: utilize forget com um id de subscrição para interromper um único fluxo, e forget_all por tipo de fluxo para interromper todos os fluxos desse tipo. A limpeza evita subscrições perdidas e tráfego desnecessário.

// stop a single stream by its subscription id
socket.send(JSON.stringify({ forget: subscriptionId }));
// stop every stream of a given type
socket.send(JSON.stringify({ forget_all: "ticks" }));

Ciclo de vida do contrato

Uma transação percorre um ciclo de vida curto: solicite um preço com proposal, execute-o com buy, acompanhe a posição aberta com proposal_open_contract e feche-a com sell ou deixe-a liquidar no vencimento. Compre com base numa proposta recente em vez de uma cotação desatualizada — os preços têm curta duração. Passe um preço máximo na chamada buy para que as variações entre a cotação e a execução não resultem numa execução menos favorável.

Acompanhe cada contrato aberto subscrevendo proposal_open_contract em vez de fazer polling a portfolio. A subscrição envia atualizações de preço à vista e de lucro e altera os indicadores is_sold e is_expired no momento em que o contrato é liquidado.

Quando is_sold se tornar verdadeiro, chame forget nessa subscrição para libertar o fluxo e não acumular subscrições ao longo do tempo. Se uma resposta de buy for perdida ou expirar, reconcilie consultando a posição em portfolio ou proposal_open_contract antes de tentar novamente, para não comprar duas vezes.

Antes de fechar antecipadamente, verifique os indicadores do próprio contrato — utilize sell apenas quando is_valid_to_sell for verdadeiro, e utilize cancel apenas dentro da janela de cancelamento de negociação para transações suportadas. Para os tipos de contrato suportados, defina o stop loss e o take profit com contract_update para que as saídas ocorram do lado do servidor, em vez de monitorizar o fluxo e vender manualmente.

// track an open contract, then release the stream once it settles
socket.send(JSON.stringify({
  proposal_open_contract: 1,
  contract_id: contractId,
  subscribe: 1,
}));

// on each update, when data.proposal_open_contract.is_sold is true:
//   socket.send(JSON.stringify({ forget: subscriptionId }));

Paginação

Para endpoints que devolvem listas, solicite os dados em páginas em vez de obter tudo de uma só vez. Utilize os parâmetros limit e offset para percorrer os resultados, e mantenha os tamanhos de página moderados para reduzir a latência e a pressão na memória.

Continue a solicitar páginas subsequentes até que uma página devolva menos linhas do que o limit que pediu, o que indica que chegou ao fim do conjunto de dados.