Gerar strings de autenticação (API REST)

Última atualização: 7 de outubro de 2026

Alguns endpoints REST permitem realizar operações sensíveis, como enviar ordens ou solicitar o saque de um ativo digital. Esses endpoints privados só podem ser chamados por meio de solicitações criptografadas, e uma string de autenticação (authent) deve ser incluída em cada solicitação. O authent é calculado a partir das seguintes entradas:

PostData

postData é uma concatenação com "&" no formato = e é específico para cada endpoint REST.

Exemplo

Para operar o endpoint orderbook, escolha o argumento symbol com o valor
fi_xbtusd_180615. O postData será então symbol=fi_xbtusd_180615.

Atualização do fluxo de autenticação para endpoints v3: a partir de 20 de fevereiro de 2024, para alinhar com as melhores práticas e garantir um padrão de segurança mais elevado, atualizaremos o fluxo de autenticação dos nossos endpoints /derivatives/* (v3). (detalhes abaixo)

Alterações na geração de PostData:


- Antes do lançamento: os clientes precisavam aplicar hash nos parâmetros da query string antes da codificação de URL para a geração do Authent, por exemplo, `greeting=hello world`.


- Após o lançamento: o processo de autenticação passará a exigir o hash do componente URI completo codificado em URL, conforme aparece na solicitação, por exemplo, `greeting=hello%20world`. Esse método reforça a segurança e alinha com as melhores práticas.
Esta atualização é especialmente relevante para o endpoint v3 batchorder, que aceita um corpo JSON nos seus parâmetros de consulta.


Compatibilidade retroativa e planos futuros:


Por enquanto, esta alteração é retrocompatível. A plataforma aceitará os dois métodos de geração de PostData descritos acima. No entanto, pretendemos descontinuar o método antigo (hash de parâmetros de query string decodificados) no futuro, para manter os mais altos padrões de segurança. Avisaremos com antecedência suficiente e recomendamos fortemente que todos os clientes migrem para o novo método o quanto antes, garantindo assim a continuidade do serviço.

Nonce

nonce é um parâmetro inteiro em incremento contínuo. Um bom Nonce é o horário do seu sistema em
milissegundos (no formato string). Nosso sistema tolera Nonces fora de ordem por um breve período de tempo. O Nonce não é obrigatório.

Exemplo 1415957147987

Muitos problemas de autenticação estão relacionados a um Nonce incorreto. Um novo par de chaves de API vai redefinir o Nonce automaticamente e resolver esses problemas.

Caminho do Endpoint

endpointPath é a extensão de URL do endpoint.

Exemplo /api/v3/orderbook

Chave API Secreta

O api_secret é obtido conforme descrito na seção anterior.

Exemplo

rttp4AzwRfYEdQ7R7X8Z/04Y4TZPa97pqCypi3xXxAqftygftnI6H9yGV+O
cUOOJeFtZkr8mVwbAndU3Kz4Q+eG

Com base nessas entradas, o authent deve ser calculado da seguinte forma:

  1. 1

    Concatene

    postData

    +

    nonce

    +

    endpointPath

  2. 2

    Faça o hash do resultado do passo 1 com o algoritmo SHA-256

  3. 3

    Decodifique em Base64 seu api_secret

  4. 4

    Use o resultado do passo 3 para fazer o hash do resultado do passo 2 com o algoritmo HMAC-SHA-512

  5. 5

    Codifique em Base64 o resultado do passo 4

Exemplo

A seguir, um exemplo de implementação de authent em Java. Para exemplos completos em diferentes linguagens de programação, consulte a seção Recursos adicionais. public static String getAuthent(String postData, String nonce, String endpointPath, String secretKeyBase64)
{
Mac mac512;
MessageDigest sha256;
try {
SecretKey secretKey = new SecretKeySpec 
(Base64.decode(secretKeyBase64.getBytes()), HMAC_SHA_512);
mac512 = Mac.getInstance(HMAC_SHA_512);
mac512.init(secretKey);
sha256 = MessageDigest.getInstance("SHA-256");
} catch (IOException e) {
...
} catch (InvalidKeyException e) {
...
} catch (NoSuchAlgorithmException e) {
...
} sha256.update(postData.getBytes());
sha256.update(nonce.getBytes());
sha256.update(endpointPath.getBytes());
mac512.update(sha256.digest());
return Base64.encodeBytes(mac512.doFinal()).trim();
}