> For the complete documentation index, see [llms.txt](https://docs.metasleuth.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metasleuth.io/ru/blocksec-aml-api/introduction/request-signing.md).

# Request Signing

Request Signing проверяет API-запросы с помощью API-секрета. Ключ идентифицирует ваш доступ, а секрет создаёт подпись и никогда не должен передаваться в запросах.

Address Label API и Risk Score API используют отдельные ключи и секреты. Используйте учётные данные вызываемого сервиса.

## Включение Request Signing

Полные процедуры настройки, ротации и отключения см. в [API Security Settings](https://docs.metasleuth.io/ru/blocksec-aml-api/introduction/api-security-settings.md).

1. Откройте [Settings → APIs → API Keys](https://metasleuth.io/system/settings/personal/apis), затем **Security Settings** нужного API.
2. Выберите **Request Signing** и создайте API-секрет. Скопируйте и безопасно сохраните его: он отображается только один раз.
3. Выберите, когда подписанные запросы станут обязательными, затем **Save Changes**:
   * **In 24 hours**: используйте переходный период для обновления и тестирования приложений. Новый секрет работает после сохранения; до указанного времени запросы без подписи принимаются с учётом других правил доступа.
   * **Immediately**: после сохранения каждый запрос должен иметь действительную подпись. Убедитесь, что приложения готовы.
4. Отправляйте подписанные запросы по инструкциям ниже. Обновите все приложения до времени, указанного в Security Settings.

Недействительная подпись отклоняется даже в переходный период. Если включён и IP Allowlist, IP источника должен быть разрешён, а подпись — действительна. Тесты используют реальные рабочие запросы и могут расходовать квоту; отдельного тестового секрета или эндпоинта проверки подписи нет.

## Заголовки запроса

| Заголовок     | Значение                                                                    |
| ------------- | --------------------------------------------------------------------------- |
| `Api-Key`     | API-ключ соответствующего сервиса                                           |
| `X-Timestamp` | Текущая метка времени Unix в секундах                                       |
| `X-Nonce`     | Новое случайное уникальное значение для каждого запроса, не более 256 байт  |
| `X-Signature` | `v1=`, затем подпись HMAC-SHA256 в шестнадцатеричном виде строчными буквами |

Метка времени должна отличаться от времени сервера не более чем на **5 минут**. Синхронизируйте часы. При каждом повторе создавайте новые метку времени, nonce и подпись.

Используйте API-ключ и секрет только в серверном коде. Загружайте их из переменных окружения или менеджера секретов; никогда не коммитьте их и не включайте в сборки браузерных или мобильных приложений.

Используйте HTTPS с проверкой сертификатов. Request Signing аутентифицирует запросы, но не шифрует содержимое. Не помещайте учётные данные в URL или параметры запроса. Маскируйте ключи, секреты, заголовки подписи и чувствительные данные запросов/ответов в журналах, трассировках, снимках экрана и вложениях для поддержки.

## Создание канонической строки

Соедините следующие шесть полей одним символом новой строки (`\n`). Не добавляйте завершающий перевод строки.

```
METHOD
PATH
SORTED_QUERY_STRING
BODY_SHA256
TIMESTAMP
NONCE
```

* **METHOD**: HTTP-метод в верхнем регистре, например `GET` или `POST`.
* **PATH**: полный путь URL с префиксом сервиса, без схемы, хоста и строки запроса. Например, `/address-compliance/api/v3/risk-score`. Использование только `/risk-score` приведёт к ошибке проверки.
* **SORTED\_QUERY\_STRING**: строка запроса, нормализованная по правилам ниже. При отсутствии параметров используйте пустую строку.
* **BODY\_SHA256**: хеш SHA-256 точных байтов отправляемого тела в шестнадцатеричном виде строчными буквами. Для пустого тела хешируйте пустую последовательность байтов.
* **TIMESTAMP** и **NONCE**: те же значения, что отправлены в заголовках.

Сериализуйте тело один раз, хешируйте эти байты и отправляйте их без изменений. Изменение пробелов JSON после подписи делает её недействительной.

### Нормализация параметров запроса

1. Разделите исходную строку по `&`, затем каждую пару по первому `=`. Отсутствующее значение считайте пустой строкой.
2. Декодируйте ключи и значения.
3. Сортируйте по декодированному ключу, затем значению в порядке байтов UTF-8. Сохраняйте повторяющиеся ключи.
4. Примените процентное кодирование RFC 3986 к каждому ключу и значению. Не экранируйте только `A–Z`, `a–z`, `0–9`, `-`, `_`, `.` и `~`. Пробел кодируйте как `%20`, буквальный плюс — как `%2B`.
5. Соедините пары `key=value` через `&`, без начального `?`.

Пример:

```
Raw:        b=2&a=1&a=%20&c=x%3Dy
Normalized: a=%20&a=1&b=2&c=x%3Dy
```

Используйте UTF-8. Избегайте исходного `+` в значениях; используйте `%20` для пробелов и `%2B` для плюса. `flag` и `flag=` нормализуются в `flag=`.

### Вычисление подписи

```
X-Signature = "v1=" + hex_lowercase(
    HMAC-SHA256(secret_utf8_bytes, canonical_string_utf8_bytes)
)
```

Используйте байты UTF-8 отображаемого значения секрета. Не декодируйте его как hex или Base64.

## Пример Python

Пример вызывает эндпоинт поддерживаемых цепей Risk Score API. Задайте `MS_API_KEY` и `MS_API_SECRET` своими данными Risk Score. Используется HTTPS-эндпоинт рабочей среды. Для разрешённых тестовых сред используйте отдельные данные; не отправляйте рабочие учётные данные недоверенным хостам.

```python
import hashlib
import hmac
import os
import time
import uuid
from urllib.parse import parse_qsl, quote, urlencode, urlsplit
from urllib.error import HTTPError
from urllib.request import HTTPRedirectHandler, Request, build_opener


def normalize_query(raw_query):
    pairs = parse_qsl(raw_query, keep_blank_values=True,
                      encoding="utf-8", errors="strict")
    pairs.sort(key=lambda p: (p[0].encode("utf-8"), p[1].encode("utf-8")))
    return urlencode(pairs, quote_via=quote, safe="-_.~")


class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        raise HTTPError(req.full_url, code, "Redirect refused", headers, fp)


base = "https://aml.blocksec.com/address-compliance/api/v3"
url = base + "/chain-list"
method = "GET"
body = b""
parts = urlsplit(url)
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
canonical = "\n".join([
    method,
    parts.path,
    normalize_query(parts.query),
    hashlib.sha256(body).hexdigest(),
    timestamp,
    nonce,
])
signature = "v1=" + hmac.new(
    os.environ["MS_API_SECRET"].encode("utf-8"),
    canonical.encode("utf-8"),
    hashlib.sha256,
).hexdigest()
request = Request(url, method=method, headers={
    "Api-Key": os.environ["MS_API_KEY"],
    "X-Timestamp": timestamp,
    "X-Nonce": nonce,
    "X-Signature": signature,
})
with build_opener(NoRedirect()).open(request, timeout=20) as response:
    print("HTTP status:", response.status)
    # Process response.read() in your application; avoid logging sensitive data.
```

Для JSON POST сериализуйте данные в байты UTF-8, используйте их для хеша тела, затем передайте те же байты в `Request` как `data=body`. Установите `Content-Type: application/json`.

Параметры запросов см. в [APIs](https://docs.metasleuth.io/ru/blocksec-aml-api/wallet-screening-api/apis.md).

## Пример Node.js

Требуется Node.js 18 или новее. Используйте те же переменные Risk Score, что в примере Python. Подписываются точные байты UTF-8, которые отправляются.

```javascript
import { createHash, createHmac, randomUUID } from 'node:crypto';

function encode(value) {
  return encodeURIComponent(value).replace(/[!'()*]/g, ch =>
    '%' + ch.charCodeAt(0).toString(16).toUpperCase());
}
function normalizeQuery(raw) {
  const pairs = [...new URLSearchParams(raw).entries()];
  pairs.sort((a, b) => Buffer.compare(Buffer.from(a[0]), Buffer.from(b[0]))
    || Buffer.compare(Buffer.from(a[1]), Buffer.from(b[1])));
  return pairs.map(([k, v]) => `${encode(k)}=${encode(v)}`).join('&');
}
const key = process.env.MS_API_KEY;
const secret = process.env.MS_API_SECRET;
if (!key || !secret) throw new Error('Set MS_API_KEY and MS_API_SECRET');
const base = 'https://aml.blocksec.com/address-compliance/api/v3';
const url = new URL(base + '/risk-score');
const method = 'POST';
const body = Buffer.from(JSON.stringify({
  chain_id: 1,
  address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  interaction_risk: false,
}), 'utf8');
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomUUID();
const canonical = [method, url.pathname, normalizeQuery(url.search.slice(1)),
  createHash('sha256').update(body).digest('hex'), timestamp, nonce].join('\n');
const signature = 'v1=' + createHmac('sha256', Buffer.from(secret, 'utf8'))
  .update(canonical, 'utf8').digest('hex');
const response = await fetch(url, {
  method,
  headers: {
    'Content-Type': 'application/json',
    'Api-Key': key,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
  },
  body,
  redirect: 'error',
});
console.log('HTTP status:', response.status);
// Process await response.json() in your application; avoid logging sensitive data.
```

Оба примера отклоняют перенаправления. Не пересылайте учётные данные и заголовки подписи на адрес перенаправления. Проверьте ожидаемые HTTPS-хост и путь перед созданием и подписанием нового запроса. HTTP-статус сам по себе не означает успех операции; проверяйте бизнес-код JSON согласно разделу [Формат ответа](https://docs.metasleuth.io/ru/blocksec-aml-api/introduction/response-format.md).

## Устранение неполадок

| Код      | Сообщение                                   | Что проверить                                                                                                                            |
| -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `401001` | Request signing is not configured           | Настройте подпись и убедитесь, что для этого API-сервиса доступен секрет.                                                                |
| `401002` | Invalid request signature                   | Проверьте данные сервиса, полноту заголовков, полный путь, метод, нормализованный запрос, точные байты тела и длину nonce (до 256 байт). |
| `401003` | Invalid request timestamp                   | Используйте секунды Unix и синхронизируйте часы; разница с сервером не должна превышать 5 минут.                                         |
| `401004` | Request has already been used               | При каждом повторе создавайте новый nonce и подпись.                                                                                     |
| `403002` | Request IP is not allowed                   | Сверьте публичный исходящий IP приложения с активным списком разрешённых адресов.                                                        |
| `500003` | Request signing verification is unavailable | Повторите с ограниченной задержкой и новым nonce/подписью. Если проблема сохраняется, обратитесь в поддержку.                            |

Полный список и обработку HTTP см. в разделе [Формат ответа](https://docs.metasleuth.io/ru/blocksec-aml-api/introduction/response-format.md).

Успешный повтор может оплачиваться снова: nonce предотвращает воспроизведение, а не повторное списание. Любой непустой заголовок подписи запускает проверку даже при отключённой подписи.

## Ротация секрета

Создайте новый секрет в Security Settings, безопасно скопируйте его и выберите срок старого. Для применения ротации выберите **Save Changes**; создание несохранённого секрета не заменяет текущий.

* **In 24 hours**: после сохранения оба секрета работают в переходный период. Обновите все приложения до истечения старого секрета.
* **Immediately**: старый секрет перестаёт работать после сохранения. Используйте этот вариант при подозрении на раскрытие.

API-ключ не меняется. Пока идёт ротация, новую начать нельзя. Дождитесь истечения старого секрета или отзовите его досрочно. Досрочный отзыв немедленно отклоняет запросы, подписанные этим секретом.
