> 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/de/blocksec-aml-api/introduction/request-signing.md).

# Request Signing

Request Signing ergänzt API-Anfragen um eine Prüfung mit einem API-Secret. Der API-Schlüssel identifiziert Ihren Zugriff; das Secret erzeugt die Signatur und darf niemals in Anfragen gesendet werden.

Address Label API und Risk Score API verwenden separate API-Schlüssel und Secrets. Verwenden Sie die Zugangsdaten des aufgerufenen Dienstes.

## Request Signing aktivieren

Die vollständigen Abläufe für Konfiguration, Rotation und Deaktivierung finden Sie unter [API Security Settings](https://docs.metasleuth.io/de/blocksec-aml-api/introduction/api-security-settings.md).

1. Öffnen Sie [Settings → APIs → API Keys](https://metasleuth.io/system/settings/personal/apis) und danach **Security Settings** der betreffenden API.
2. Wählen Sie **Request Signing** und erstellen Sie ein API-Secret. Kopieren und speichern Sie es sicher: Es wird nur einmal angezeigt.
3. Wählen Sie, wann signierte Anfragen erforderlich werden, und dann **Save Changes**:
   * **In 24 hours**: Nutzen Sie den Übergang für Updates und Tests. Das neue Secret funktioniert nach dem Speichern; unsignierte Anfragen werden bis zum angezeigten Zeitpunkt nach den anderen Zugriffsregeln akzeptiert.
   * **Immediately**: Jede Anfrage muss nach dem Speichern eine gültige Signatur enthalten. Stellen Sie sicher, dass Ihre Anwendungen bereit sind.
4. Senden Sie signierte Anfragen nach den folgenden Anweisungen. Aktualisieren Sie alle Anwendungen vor dem in Security Settings angezeigten Zeitpunkt.

Ungültige Signaturen werden auch während des Übergangs abgelehnt. Ist zusätzlich IP Allowlist aktiv, muss die Quell-IP erlaubt und die Signatur gültig sein. Tests sind echte Geschäftsanfragen und können Kontingent verbrauchen; es gibt kein separates Test-Secret und keinen eigenen Signaturprüfungsendpunkt.

## Anfrage-Header

| Header        | Wert                                                                        |
| ------------- | --------------------------------------------------------------------------- |
| `Api-Key`     | API-Schlüssel des Dienstes                                                  |
| `X-Timestamp` | Aktueller Unix-Zeitstempel in Sekunden                                      |
| `X-Nonce`     | Neuer, zufälliger und eindeutiger Wert pro Anfrage, höchstens 256 Byte lang |
| `X-Signature` | `v1=` gefolgt von der HMAC-SHA256-Signatur in hexadezimalen Kleinbuchstaben |

Der Zeitstempel darf höchstens **5 Minuten** von der Serverzeit abweichen. Synchronisieren Sie Ihre Systemuhr. Erzeugen Sie für jeden erneuten Versuch einen neuen Zeitstempel, eine neue Nonce und Signatur.

Verwenden Sie API-Schlüssel und Secret ausschließlich im serverseitigen Code. Laden Sie sie aus Umgebungsvariablen oder einer Secret-Verwaltung; speichern Sie sie nie in der Versionsverwaltung oder in Browser- bzw. mobilen Anwendungspaketen.

Verwenden Sie HTTPS mit Zertifikatsprüfung. Request Signing authentifiziert Anfragen, verschlüsselt aber nicht deren Inhalt. Zugangsdaten gehören nicht in URLs oder Abfrageparameter. Schwärzen Sie API-Schlüssel, Secrets, Signatur-Header und sensible Anfrage-/Antwortdaten in Protokollen, Traces, Screenshots und Support-Anhängen.

## Kanonische Zeichenfolge erstellen

Verbinden Sie die folgenden sechs Felder mit einem einzelnen Zeilenumbruch (`\n`). Fügen Sie keinen abschließenden Zeilenumbruch hinzu.

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

* **METHOD**: HTTP-Methode in Großbuchstaben, etwa `GET` oder `POST`.
* **PATH**: Vollständiger URL-Pfad mit Dienstpräfix, ohne Schema, Host oder Abfragezeichenfolge. Beispiel: `/address-compliance/api/v3/risk-score`. Nur `/risk-score` führt zum Fehlschlagen der Prüfung.
* **SORTED\_QUERY\_STRING**: Wie unten normalisierte Abfragezeichenfolge. Ohne Parameter verwenden Sie eine leere Zeichenfolge.
* **BODY\_SHA256**: SHA-256-Hash der exakt gesendeten Body-Bytes in hexadezimalen Kleinbuchstaben. Bei leerem Body hashen Sie eine leere Bytefolge.
* **TIMESTAMP** und **NONCE**: Dieselben Werte wie in den Anfrage-Headern.

Serialisieren Sie den Body einmal, hashen Sie diese Bytes und senden Sie exakt diese Bytes. Geänderte JSON-Leerzeichen nach dem Signieren machen die Signatur ungültig.

### Abfrageparameter normalisieren

1. Teilen Sie die rohe Abfragezeichenfolge an `&` und jedes Paar am ersten `=`. Behandeln Sie fehlende Werte als leere Zeichenfolge.
2. Dekodieren Sie Schlüssel und Werte.
3. Sortieren Sie nach dekodiertem Schlüssel, dann Wert, jeweils in UTF-8-Byte-Reihenfolge. Behalten Sie doppelte Schlüssel bei.
4. Kodieren Sie Schlüssel und Werte nach RFC 3986 mit Prozentkodierung. Nur `A–Z`, `a–z`, `0–9`, `-`, `_`, `.` und `~` bleiben unmaskiert. Kodieren Sie Leerzeichen als `%20` und wörtliche Pluszeichen als `%2B`.
5. Verbinden Sie die Paare `key=value` mit `&`, ohne vorangestelltes `?`.

Beispiel:

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

Verwenden Sie UTF-8. Vermeiden Sie rohe `+` in Werten; verwenden Sie `%20` für Leerzeichen und `%2B` für Pluszeichen. Sowohl `flag` als auch `flag=` werden zu `flag=` normalisiert.

### Signatur berechnen

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

Verwenden Sie das Secret als UTF-8-Bytes des angezeigten Werts. Dekodieren Sie es nicht als Hexadezimal oder Base64.

## Python-Beispiel

Dieses Beispiel ruft den Endpunkt für unterstützte Chains der Risk Score API auf. Setzen Sie `MS_API_KEY` und `MS_API_SECRET` auf Ihre Risk Score-Zugangsdaten. Das Beispiel verwendet den HTTPS-Produktionsendpunkt. Nutzen Sie separate Zugangsdaten für autorisierte Testumgebungen und senden Sie Produktionszugangsdaten niemals an nicht vertrauenswürdige Hosts.

```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.
```

Serialisieren Sie bei JSON POST die Nutzdaten als UTF-8-Bytes, hashen Sie diese und übergeben Sie dieselben Bytes als `data=body` an `Request`. Setzen Sie `Content-Type: application/json`.

Anfrageparameter finden Sie unter [APIs](https://docs.metasleuth.io/de/blocksec-aml-api/wallet-screening-api/apis.md).

## Node.js-Beispiel

Erfordert Node.js 18 oder neuer. Verwenden Sie dieselben Risk Score-Umgebungsvariablen wie im Python-Beispiel. Signiert werden die exakt gesendeten UTF-8-Bytes.

```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.
```

Beide Beispiele verweigern Weiterleitungen. Leiten Sie Zugangsdaten oder Signatur-Header nicht an Weiterleitungsziele weiter. Prüfen Sie HTTPS-Host und Pfad, bevor Sie eine neue Anfrage erstellen und signieren. Der HTTP-Status allein belegt keinen Geschäftserfolg; prüfen Sie den JSON-Geschäftscode gemäß [Antwortformat](https://docs.metasleuth.io/de/blocksec-aml-api/introduction/response-format.md).

## Fehlerbehebung

| Code     | Meldung                                     | Prüfpunkte                                                                                                                                                    |
| -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401001` | Request signing is not configured           | Konfigurieren Sie die Signatur und prüfen Sie, ob für diesen API-Dienst ein Secret verfügbar ist.                                                             |
| `401002` | Invalid request signature                   | Prüfen Sie Dienstzugangsdaten, vollständige Header, vollständigen Pfad, Methode, normalisierte Abfrage, exakte Body-Bytes und Nonce-Länge (maximal 256 Byte). |
| `401003` | Invalid request timestamp                   | Verwenden Sie Unix-Sekunden und synchronisieren Sie Ihre Uhr; die Abweichung darf höchstens 5 Minuten betragen.                                               |
| `401004` | Request has already been used               | Erstellen Sie bei jedem erneuten Versuch eine neue Nonce und Signatur.                                                                                        |
| `403002` | Request IP is not allowed                   | Prüfen Sie die öffentliche Ausgangs-IP Ihrer Anwendung anhand der aktiven Erlaubnisliste.                                                                     |
| `500003` | Request signing verification is unavailable | Wiederholen Sie mit begrenztem Backoff und neuer Nonce/Signatur. Kontaktieren Sie bei fortbestehenden Problemen den Support.                                  |

Vollständige Liste und HTTP-Behandlung finden Sie unter [Antwortformat](https://docs.metasleuth.io/de/blocksec-aml-api/introduction/response-format.md).

Ein erfolgreicher erneuter Versuch kann erneut berechnet werden: Nonces verhindern Replay, nicht doppelte Abrechnung. Jeder nicht leere Signatur-Header löst eine Prüfung aus, auch bei deaktivierter Signatur.

## Secret rotieren

Erstellen Sie unter Security Settings ein neues Secret, kopieren und speichern Sie es sicher und wählen Sie den Ablauf des alten Secrets. **Save Changes** wendet die Rotation an; ein ungespeichertes neues Secret ersetzt das aktuelle nicht.

* **In 24 hours**: Nach dem Speichern funktionieren beide Secrets während des Übergangs. Aktualisieren Sie alle Anwendungen vor Ablauf des alten Secrets.
* **Immediately**: Das alte Secret funktioniert nach dem Speichern nicht mehr. Nutzen Sie diese Option bei vermuteter Offenlegung.

Der API-Schlüssel bleibt unverändert. Während einer Rotation kann keine neue beginnen. Warten Sie auf den Ablauf des alten Secrets oder widerrufen Sie es vorzeitig. Der Widerruf lehnt damit signierte Anfragen sofort ab.
