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

Última atualização: 1 de abr. de 2025

A autenticação da API é necessária sempre que uma chamada de API acessa uma conta por meio de um dos métodos de API privados.

Por exemplo, os métodos de gerenciamento 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 de API e Assinaturas Criptográficas

A autenticação da API é baseada em um par de chaves pública/privada (conhecido coletivamente como uma chave de API) e uma assinatura criptográfica usando algoritmos de hash como SHA256 e HMAC SHA512.

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

bash

Bash

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

Observe que esses exemplos não podem ser usados, pois 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 de API são passados por uma série de algoritmos de hash e autenticação de mensagem que assinam os dados com segurança usando o segredo da API (a parte privada da chave de API).

Cabeçalhos HTTP

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

A chave de API é usada para identificar qual conta está sendo acessada, portanto, o valor da chave é idêntico para cada chamada de API. A assinatura criptográfica é usada para autenticar a chamada de API e é calculada usando valores variáveis (como o nonce), portanto, o valor da assinatura é diferente para cada chamada de API.

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==

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

Pseudocódigo da Assinatura

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

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 (geralmente 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 em formulário do nonce e dos parâmetros do método da API.

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

  • •

    URI path = "/0/private/TradeBalance"

  • •

    nonce = "1540973848000"

  • •

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

Algoritmo

  • •

    Calcule o SHA256 do nonce e dos dados POST.

  • •

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

  • •

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

  • •

    Codifique o HMAC em base64.

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

  • •

    Base64Encode(HMAC-SHA512 de ("/0/private/TradeBalance" + SHA256("1540973848000nonce=1540973848000&asset=xbt")) usando 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?