Agent-Autorisierung

Multi-Key-Signierunterstützung für Market Maker.

Überblick

Die Agent-Autorisierung ermöglicht es einem dedizierten Signierschlüssel (Agent), im Namen einer Trading-Wallet Orders zu platzieren und zu stornieren. Dies ist nützlich für:

• Sicherheit: Bewahren Sie die Schlüssel der Trading-Wallet im Cold Storage auf und verwenden Sie Hot Keys zum Signieren
• Betrieb: Mehrere Teammitglieder können mit unterschiedlichen Schlüsseln signieren
• Automatisierung: Automatisierte Systeme können mit dedizierten Schlüsseln signieren

Zwei Autorisierungsmodelle

Hypercall verfügt über zwei separate Delegationssysteme, abhängig vom Produkt:

Produkt	Delegationstyp	Speicherung	Einrichtung
Optionen (REST-API)	Agent-Autorisierung	Off-Chain (Datenbank)	POST /approve-agent
Perps (On-Chain-Direktiven)	API-Wallet	On-Chain (Exchange-Contract)	hc_update_api_wallet-Direktive

Dies sind unabhängige Systeme. Die Genehmigung eines Agents für den Optionshandel autorisiert ihn nicht für Perps und umgekehrt.

Optionen: Agent-Autorisierung (Off-Chain)

Agents signieren PlaceOrder- und CancelOrder-EIP-712-Nachrichten im Namen einer Trading-Wallet. Der API-Server überprüft die Autorisierung anhand seiner Datenbank, bevor die Nachricht an die Engine weitergeleitet wird.

Perps: API-Wallet (On-Chain)

API-Wallets signieren Perp-Direktiven unter Verwendung der HypercallAgentSign-EIP-712-Domain. Der Exchange-Contract verifiziert die Autorisierung on-chain über isApiWalletActive(). Siehe EIP-712-Signierung für die vollständige Referenz zur Direktiven-Signierung.

Um eine API-Wallet hinzuzufügen oder zu entfernen, senden Sie eine hc_update_api_wallet-Direktive, die von der Manager-Wallet des Kontos signiert wurde.

Dies entspricht dem API-Wallet-Modell von Hyperliquid. Hyperliquid dokumentiert diese als API-Wallets, auch Agent-Wallets genannt, in Nonces and API wallets und dokumentiert approveAgent im Exchange endpoint.

Nonce-Replay-Schutz

Die Nonce-Verfolgung folgt dem Hyperliquid-Nonce-Modell. Alle signierten Aktionen (Orders, Agent-Genehmigung/-Widerruf, QP-Handshakes) teilen sich einen Nonce-Raum pro Signierer. Die Engine speichert die 100 höchsten Nonces pro Signierer-Adresse. Eine neue Nonce wird akzeptiert, wenn:

1. nonce > min(stored_set) -- muss größer sein als die kleinste gespeicherte Nonce
2. !stored_set.contains(nonce) -- darf kein Duplikat sein
3. nonce liegt innerhalb von (T - 2 Tage, T + 1 Tag) des Server-Zeitstempels

Nonces außerhalb der Reihenfolge sind zulässig (z. B. funktionieren Nonce 105 und danach 102 beide, sofern beide über dem Minimum des Sets liegen). Das Set ist auf 100 Einträge begrenzt, sodass die ältesten Einträge entfernt werden, wenn neue hinzugefügt werden. Dies verhindert, dass ein Konto durch eine einzelne große Nonce unbrauchbar wird.

Der Nonce-Signierer ist die Adresse, die die EIP-712-Nachricht signiert hat: die API-Wallet bei Orders, der wiederhergestellte Signierer bei der Agent-Autorisierung, die QP-Wallet bei Handshakes. Clients sollten Date.now() (Millisekunden-Epoche) als Nonce-Seed verwenden und monoton inkrementieren.

Optionen: Agent-Autorisierung

Direktes Signieren

Wenn signer == wallet, ist die Order immer autorisiert (Selbstsignierung).

Agent-Signierung

Wenn signer != wallet, muss der Signierer ein autorisierter Agent sein:

• Der Agent muss im Engine-eigenen Autorisierungszustand vorhanden sein
• Die Autorisierung darf nicht abgelaufen sein
• Engine-Snapshots und das Engine-Journal sind die dauerhaften Quellen für Neustarts

Agent genehmigen

Endpunkt: POST /approve-agent

Anfrage: ApproveAgentRequest

{
  "agent": "0x...",
  "nonce": 1,
  "signature": "0x..."
}

Signierung:

• Der Wallet-Inhaber signiert die ApproveAgent-Nachricht
• Die Wallet wird aus der wiederhergestellten Signatur abgeleitet
• Der Agent ist das Feld agent in der Anfrage

EIP-712-Struct:

struct ApproveAgent {
    address agent;
    uint64 nonce;
}

Antwort: ApproveAgentResponse

{
  "success": true,
  "error": null
}

Hinweise:

• Die Agent-Autorisierung ist persistent (in der DB gespeichert)
• Die Autorisierung läuft nicht ab, es sei denn, expires_at ist gesetzt (noch nicht implementiert)

Agent widerrufen

Endpunkt: DELETE /revoke-agent

Anfrage: RevokeAgentRequest

{
  "agent": "0x...",
  "nonce": 2,
  "signature": "0x..."
}

Signierung:

• Der Wallet-Inhaber signiert die RevokeAgent-Nachricht
• Die Wallet wird aus der wiederhergestellten Signatur abgeleitet

EIP-712-Struct:

struct RevokeAgent {
    address agent;
    uint64 nonce;
}

Antwort: RevokeAgentResponse

Hinweise:

• Wendet einen journalisierten RevokeAgent-Befehl auf den Engine-eigenen Autorisierungszustand an
• Die Autorisierungsprüfungen der Trading-API lesen den Backend-Zustand und setzen Widerrufe für Trading-Anfragen durch. Das Posten in der Trollbox kann positive Agent-Autorisierungen länger zwischenspeichern, sodass ein kürzlich widerrufener Agent möglicherweise weiterhin posten kann, bis dieser Cache abläuft oder die Best-Effort-Invalidierung den betreffenden Edge-Standort erreicht. Dieser Cache autorisiert keine Mutationen der Trading-API.
• Der Agent kann nach dem Widerruf nicht mehr für die Wallet signieren

Autorisierte Agents abrufen

Endpunkt: GET /authorized-agents?wallet=...

Query-Parameter:

• wallet (erforderlich)

Antwort:

{
  "agents": [
    "0x...",
    "0x..."
  ]
}

Hinweise:

• Gibt nur aktive, nicht abgelaufene Agents zurück
• Sortiert nach created_at DESC

Verwendung von Agents

Orders mit einem Agent signieren

Sobald ein Agent genehmigt wurde:

1. Order mit der Agent-Wallet signieren: Verwenden Sie die Agent-Wallet, um PlaceOrder- / CancelOrder-Nachrichten zu signieren
2. Wallet-Feld setzen: Setzen Sie das Feld wallet auf die Adresse der Trading-Wallet (nicht die Agent-Adresse)
3. Middleware-Verifizierung: Die Middleware verifiziert, dass der Agent für diese Wallet autorisiert ist

Beispiel:

// Agent wallet signs the order
const agentSigner = new ethers.Wallet(agentPrivateKey);

const message = {
  wallet: "0x...",  // Trading wallet (not agent)
  symbol: "BTC-20250131-100000-C",
  side: "Buy",
  size: "0.1",
  price: "100.0",
  tif: "gtc",
  clientId: "mm-1",
  nonce: 1
};

// Sign with agent wallet
const signature = await agentSigner._signTypedData(domain, types, message);

// Send request
const response = await fetch('/order', {
  method: 'POST',
  body: JSON.stringify({
    ...message,
    signature
  })
});

Bulk-Orders mit einem Agent

Bulk-Endpunkte überprüfen die Agent-Autorisierung pro Element:

• Jede Order in POST /bulk_order kann von einem anderen Agent signiert werden
• Die Agent-Autorisierung wird pro Element geprüft
• Wenn die Agent-Autorisierung für ein Element fehlschlägt, gibt dieses Element einen Fehler in BulkOrderResult zurück

Autorisierungsprüfungen

Middleware (Einzelne Orders)

Endpunkte:

• POST /order
• DELETE /order
• DELETE /order_cloid

Prüfung: signature_and_agent_middleware verifiziert:

1. Die Signaturwiederherstellung ist erfolgreich
2. Der Signierer ist autorisiert (signer == wallet ODER Agent autorisiert)

Handler (Bulk-Orders)

Endpunkte:

• POST /bulk_order
• DELETE /bulk_order
• DELETE /bulk_order_cloid

Prüfung: Verifizierung pro Element im Handler:

1. Signaturwiederherstellung pro Element
2. Prüfung der Agent-Autorisierung pro Element

Speicherung der Autorisierung

Die Agent-Autorisierung ist Engine-eigener Zustand. ApproveAgent- und RevokeAgent-Befehle werden journalisiert, durch Engine-Replay wiederhergestellt und über den Lese-Snapshot für API-Prüfungen bereitgestellt.

Autorisierungslogik

Die Signierer-Autorisierung folgt einer expliziten ODER-Logik:

• Direktes Signieren: signer == wallet.
• Agent-Signierung: Der Engine-Snapshot enthält einen Autorisierungsdatensatz für wallet_address == <wallet> und agent_address == <signer>, und expires_at fehlt oder liegt in der Zukunft.

Ablauf

expires_at wird durch die Autorisierungsprüfungen des Engine-Snapshots durchgesetzt. Agents mit expires_at < NOW() werden als nicht autorisiert behandelt.

Sicherheitsüberlegungen

1. Sicherheit der Agent-Schlüssel: Schützen Sie die privaten Schlüssel des Agents (verwenden Sie Hardware-Wallets oder sicheres Schlüsselmanagement)
2. Regelmäßige Audits: Überprüfen Sie autorisierte Agents regelmäßig über GET /authorized-agents
3. Ungenutzte Agents widerrufen: Widerrufen Sie Agents, die nicht mehr benötigt werden
4. Ablauf: Verwenden Sie expires_at für temporäre Agent-Autorisierungen, wenn der Genehmigungspfad einen nicht standardmäßigen Ablauf bereitstellt

Best Practices

1. Agents für Automatisierung verwenden: Bewahren Sie die Schlüssel der Trading-Wallet im Cold Storage auf und verwenden Sie Agents für automatisierte Systeme
2. Agent-Umfang begrenzen: Genehmigen Sie nur Agents, die Zugriff benötigen
3. Agent-Nutzung überwachen: Verfolgen Sie, welche Agents Orders platzieren
4. Zeitnah widerrufen: Widerrufen Sie Agents sofort, wenn sie nicht mehr benötigt werden

Häufige Probleme

"Unauthorized: signer not authorized for wallet"

Ursache: Der Agent wurde nicht genehmigt oder die Autorisierung ist abgelaufen/widerrufen.

Lösung: Genehmigen Sie den Agent über POST /approve-agent oder signieren Sie direkt mit der Wallet.

Agent-Autorisierung funktioniert nicht

Ursachen:

• Der Agent ist nicht im Engine-eigenen Autorisierungszustand vorhanden
• Die Autorisierung wurde widerrufen
• Die Autorisierung ist abgelaufen

Lösung: Prüfen Sie den Agent-Status über GET /authorized-agents?wallet=....