Gerar strings de autenticação (API REST)

Última atualização: 31 de mar. de 2025

Alguns endpoints REST permitem a realização de operações sensíveis, como a colocação de ordens ou a solicitação de retirada de ativos digitais. Esses endpoints privados podem, portanto, ser chamados apenas por meio de solicitações criptografadas, e uma string de autenticação (authent) deve ser incluída em cada uma dessas solicitações. A autenticação é calculada a partir das seguintes entradas:

PostData

postData é uma concatenação "&" no formato <argumento>=<valor> e é específica para cada endpoint REST.

Exemplo

Para operar o endpoint orderbook, você escolhe o argumento symbol com o valor
fi_xbtusd_180615. postData é então fornecido por 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, iremos atualizar o fluxo de autenticação para os nossos endpoints /derivatives/* (v3). (detalhes abaixo)

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


- Antes do lançamento: Os usuários eram obrigados a fazer hash dos parâmetros da string de consulta antes da codificação de URL para a geração de Authent, por exemplo, `greeting=hello world`.


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


Compatibilidade Retroativa e Planos Futuros:


Por enquanto, esta mudança é retrocompatível. A plataforma aceitará ambos os métodos de geração de PostData descritos acima. No entanto, pretendemos descontinuar o método antigo (hashing de parâmetros de string de consulta decodificados) no futuro para manter os mais altos padrões de segurança. Forneceremos aviso prévio suficiente antes desta mudança e encorajamos fortemente todos os usuários a fazer a transição para o novo método o mais rápido possível para garantir a continuidade ininterrupta do serviço.

Nonce

nonce é um parâmetro inteiro que incrementa continuamente. Um bom nonce é o tempo do seu sistema em
milissegundos (em formato de string). Nosso sistema tolera nonces fora de ordem por um breve período de tempo. 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 redefinirá automaticamente o nonce e resolverá esses problemas.

Caminho do Endpoint

endpointPath Esta é a extensão URL do endpoint.

Exemplo /api/v3/orderbook

Segredo da API

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

Exemplo

rttp4AzwRfYEdQ7R7X8Z/04Y4TZPa97pqCypi3xXxAqftygftnI6H9yGV+O
cUOOJeFtZkr8mVwbAndU3Kz4Q+eG

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

  1. 1

    Concatenar

    postData

    +

    nonce

    +

    endpointPath

  2. 2

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

  3. 3

    Decodifique em Base64 seu api_secret

  4. 4

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

  5. 5

    Codifique em Base64 o resultado da etapa 4

Exemplo

O seguinte mostra uma implementação de authent em Java. Para exemplos completos de trabalho 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();
}

Precisa de mais ajuda?