Всё об аутентификации HMAC-SHA256 для API криптобирж

При работе с API вы используете пару ключей: API Key и Secret Key.

• API Key (Публичный ключ) — это ваш идентификатор. Вы отправляете его в заголовке каждого запроса, чтобы сервер знал, кто вы. Его можно сравнить с логином.
• Secret Key (Секретный ключ) — это ваш пароль. Его никогда нельзя отправлять напрямую! Он используется для создания цифровой подписи.

Просто отправить API-ключ недостаточно. Если злоумышленник перехватит ваш запрос, он сможет его скопировать и повторно отправить (replay attack) или даже изменить (например, поменять адрес для вывода средств). Нужен механизм, который докажет серверу две вещи:

1. Запрос был отправлен именно вами (владельцем Secret Key).
2. Содержимое запроса не было изменено по пути.

Этим механизмом и является HMAC.

Аналогия: Восковая печать на письме

Представьте, что ваш API-запрос — это средневековое письмо. Вы можете просто подписать его своим именем (это API Key). Но чтобы доказать подлинность, вы расплавляете воск (это ваш Secret Key), капаете на конверт и ставите оттиск личной печатью (это алгоритм HMAC-SHA256). В итоге получается уникальная печать.

Получатель (сервер биржи) видит ваше имя, берет свой экземпляр вашей печати (он тоже знает ваш Secret Key) и делает такой же оттиск на таком же письме. Если печати совпадают — письмо подлинное и не вскрывалось. Если нет — его либо подделали, либо вскрыли и изменили по пути.

Техническое объяснение

HMAC (Hash-based Message Authentication Code) — это код аутентификации сообщений, использующий хеш-функцию. SHA256 — это конкретная хеш-функция (из семейства SHA-2), которая превращает любой объем данных в уникальную строку из 64 символов.

Процесс HMAC-SHA256 берет данные вашего запроса, объединяет их с вашим секретным ключом и пропускает через алгоритм хеширования. Результат — уникальная "подпись", которую можно безопасно отправить на сервер.

Процесс генерации подписи для API AsterDEX и большинства других бирж одинаков:

1. Соберите все параметры запроса. Это могут быть параметры из строки запроса (для GET) или из тела запроса (для POST).
2. Добавьте `timestamp`. К параметрам обязательно добавляется текущее время в миллисекундах. Это защищает от "атак повторения" (replay attacks), так как сервер отклонит запросы со слишком старой меткой времени.
3. Создайте строку для подписи (query string). Все пары "ключ=значение" сортируются по алфавиту и объединяются в одну строку с помощью символа `&`. Например: `price=25000&quantity=0.1&side=BUY&symbol=BTCUSDT×tamp=1678886400000`.
4. Сгенерируйте подпись. Полученная строка хешируется с помощью алгоритма HMAC-SHA256, где в качестве ключа используется ваш Secret Key.
5. Добавьте подпись в запрос. Полученный хеш в виде шестнадцатеричной строки добавляется как еще один параметр с именем `signature`.

Давайте сгенерируем подпись для гипотетического запроса на покупку 0.1 BTC. Обратите внимание, как оба языка, используя одни и те же исходные данные, производят абсолютно идентичную подпись.

Python

Используем встроенные библиотеки `hmac` и `hashlib`.

import hmac
import hashlib
import time

# Данные запроса
params = {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": 0.1,
    "price": 25000,
    "timestamp": int(time.time() * 1000)
}

# Секретный ключ (должен храниться в безопасности!)
secret_key = "your_very_secret_key"

# 1. Создаем строку для подписи (query string)
query_string = '&'.join([f"{key}={params[key]}" for key in sorted(params)])
print(f"Строка для подписи:
{query_string}
")

# 2. Генерируем подпись
signature = hmac.new(
    secret_key.encode('utf-8'),
    query_string.encode('utf-8'),
    hashlib.sha256
).hexdigest()

print(f"Сгенерированная подпись (HMAC-SHA256):
{signature}")

Node.js (JavaScript)

Используем встроенный модуль `crypto`.

const crypto = require('crypto');

// Те же данные запроса
// ВАЖНО: timestamp должен быть тем же, что и в Python-примере, для получения идентичной подписи.
const params = {
    symbol: "BTCUSDT",
    side: "BUY",
    type: "LIMIT",
    timeInForce: "GTC",
    quantity: 0.1,
    price: 25000,
    timestamp: 1678886400000 // Пример timestamp для идентичности
};

// Тот же секретный ключ
const secretKey = "your_very_secret_key";

// 1. Создаем строку для подписи
const queryString = Object.keys(params)
    .sort()
    .map(key => `${key}=${params[key]}`)
    .join('&');

console.log(`Строка для подписи:
${queryString}
`);

// 2. Генерируем подпись
const signature = crypto.createHmac('sha256', secretKey)
    .update(queryString)
    .digest('hex');

console.log(`Сгенерированная подпись (HMAC-SHA256):
${signature}`);

HMAC-аутентификация — это несложный, но чрезвычайно мощный механизм защиты ваших API-запросов. Поняв его логику, вы сможете безопасно взаимодействовать с любой современной криптобиржей.

Теперь, когда вы понимаете теорию, посмотрите, как она применяется на практике в наших руководствах:

• Создание простого торгового бота на Python
• Автоматическая ребалансировка портфеля