Qual é o algoritmo de autenticação para endpoints privados?

Última atualização: 1/04/2025

A autenticação da API é necessária sempre que uma chamada de API acede a uma conta através de um dos métodos de API privados.

Por exemplo, os métodos de gestão de conta como Balance, TradeBalance e OpenOrders; os métodos de negociação AddOrder e CancelOrder; e os métodos de financiamento como DepositAddresses e WithdrawInfo, são todos métodos de API privados que exigiriam autenticação de API.

Chaves API e Assinaturas Criptográficas

A autenticação da API baseia-se num par de chaves pública/privada (coletivamente conhecido como chave API) e numa assinatura criptográfica que utiliza algoritmos de hash como SHA256 e HMAC SHA512.

Um exemplo de chave API consistiria numa chave pública e privada semelhante à seguinte:

bash

Bash

Public Key: CJbfPw4tnbf/9en/ZmpewCTKEwmmzO18LXZcHQcu7HPLWre4l8+V9I3y
 
 Private Key: FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ==

Tenha em atenção que estes exemplos não podem ser utilizados, uma vez que não estão associados a nenhuma conta Kraken.

As assinaturas criptográficas são criadas em tempo real pelo código do cliente da API. Os dados para a chamada da API são passados através de uma série de algoritmos de hash e de autenticação de mensagens que assinam os dados de forma segura utilizando o segredo da API (a parte privada da chave da API).

Cabeçalhos HTTP

A chave API e a assinatura são fornecidas à API através dos cabeçalhos HTTP personalizados API-Key e API-Sign.

A chave API é utilizada para identificar qual conta está a ser acedida, pelo que o valor da chave é idêntico para cada chamada de API. A assinatura criptográfica é utilizada para autenticar a chamada de API e é calculada utilizando valores variáveis (como o nonce), pelo que o valor da assinatura é diferente para cada chamada de API.

Os exemplos dos cabeçalhos HTTP API-Key e API-Sign são os seguintes:

  • •

    API-Key: CJbfPw4tnbf/9en/ZmpewCTKEwmmzO18LXZcHQcu7HPLWre4l8+V9I3y

  • •

    API-Sign: RdQzoXRC83TPmbERpFj0XFVArq0Hfadm0eLolmXTuN2R24hzIqtAnF/f7vSfW1tGt7xQOn8bjm+Ht+X0KrMwlA==

Tenha em atenção que o valor da API-Key é exatamente o mesmo que a chave pública mostrada acima, mas que o valor da API-Sign (a assinatura) é diferente da chave privada mostrada acima e mudará para um novo valor para cada chamada de API.

Pseudocódigo da Assinatura

A nossa documentação da API afirma que o valor API-Sign é uma "assinatura de mensagem utilizando HMAC-SHA512 de (caminho URI + SHA256(nonce + dados POST)) e chave API secreta decodificada em base64", que pode ser separada em várias partes distintas, como se segue:

Variáveis

  • •

    Caminho URI = URL da chamada de API sem 'https://api.kraken.com'.

  • •

    nonce = Um identificador único que deve aumentar de valor a cada chamada de API (muitas vezes um carimbo de data/hora UNIX, que é a hora atual em segundos (ou milissegundos para maior resolução) desde 1 de janeiro de 1970).

  • •

    Dados POST = Pares nome/valor codificados por formulário do nonce e dos parâmetros do método da API.

Os exemplos das variáveis para uma chamada ao método TradeBalance são os seguintes (note que todos os valores são valores de string, independentemente do que representam):

  • •

    Caminho URI = "/0/private/TradeBalance"

  • •

    nonce = "1540973848000"

  • •

    Dados POST = "nonce=1540973848000&asset=xbt"

Algoritmo

  • •

    Calcule o SHA256 do nonce e dos dados POST.

  • •

    Descodifique o segredo da API (a parte privada da chave API) a partir de base64.

  • •

    Calcule o HMAC do caminho URI e do SHA256, utilizando SHA512 como hash HMAC e o segredo da API descodificado como chave HMAC.

  • •

    Codifique o HMAC em base64.

Um exemplo do algoritmo utilizando as variáveis mostradas acima é o seguinte:

  • •

    Base64Encode(HMAC-SHA512 de ("/0/private/TradeBalance" + SHA256("1540973848000nonce=1540973848000&asset=xbt")) utilizando Base64Decode("FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ==") como chave HMAC

O resultado é o valor API-Sign.

Código de Exemplo

Exemplos mínimos (sem verificação de erros), mas totalmente funcionais, de geração de uma assinatura de autenticação de API para o endpoint da API TradeBalance são os seguintes:

python

Python

# Import required Python libraries
import time
import base64
import hashlib
import hmac

# Decode API private key from base64 format displayed in account management
api_secret = base64.b64decode(
    "FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ=="
)

# Variables (API endpoint, nonce and HTTP POST data)
api_path = "/0/private/TradeBalance"
api_nonce = str(int(time.time() * 1000))
api_post = "nonce=" + api_nonce + "&asset=xbt"

# Cryptographic hash algorithms
api_sha256 = hashlib.sha256(api_nonce.encode('utf-8') + api_post.encode('utf-8'))
api_hmac = hmac.new(
    api_secret,
    api_path.encode('utf-8') + api_sha256.digest(),
    hashlib.sha512
)

# Encode signature into base64 format used in API-Sign value
api_signature = base64.b64encode(api_hmac.digest())

# API authentication signature for use in API-Sign HTTP header
print(api_signature.decode())


NodeJS

bash

Bash

// Import required NodeJS libraries
const crypto = require('crypto');

// Decode API private key from base64 format displayed in account management
const apiSecret = Buffer.from(
  'FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ==',
  'base64'
);

// Variables (API endpoint, nonce and HTTP POST data)
const apiPath = '/0/private/TradeBalance';
const apiNonce = Date.now().toString();
const apiPost = `nonce=${apiNonce}&asset=xbt`;

// Cryptographic hash algorithms
const apiSha256 = crypto.createHash('sha256').update(`${apiNonce}${apiPost}`).digest();
const apiSha512 = crypto.createHmac('sha512', apiSecret).update(apiPath).update(apiSha256).digest();

// Encode signature into base64 format used in API-Sign value
const apiSignature = apiSha512.toString('base64');

// API authentication signature for use in API-Sign HTTP header
console.log(apiSignature);


PHP

bash

Bash

// Decode API private key from base64 format displayed in account management
$apiSecret = base64_decode('FRs+gtq09rR7OFtKj9BGhyOGS3u5vtY/EdiIBO9kD8NFtRX7w7LeJDSrX6cq1D8zmQmGkWFjksuhBvKOAWJohQ==');

// Variables (API endpoint, nonce and HTTP POST data)
$apiPath = '/0/private/TradeBalance';
$apiNonce = explode(' ', microtime());
$apiNonce = $apiNonce[1] . substr($apiNonce[0], 2, 3);
$apiPost = "nonce={$apiNonce}&asset=xbt";

// Cryptographic hash algorithms
$apiSha256 = hash('sha256', $apiNonce . $apiPost, true);
$apiSha512 = hash_hmac('sha512', $apiPath . $apiSha256, $apiSecret, true);

// Encode signature into base64 format used in API-Sign value
$apiSignature = base64_encode($apiSha512);

// API authentication signature for use in API-Sign HTTP header
print $apiSignature;

Precisa de mais ajuda?