Agent-Autorisierung

Multi-Key-Signierung für Market Maker.

Überblick

Mit der Agent-Autorisierung kann ein dedizierter Signierschlüssel (Agent) im Namen einer Trading-Wallet Orders platzieren und stornieren. Das ist nützlich für:

• Sicherheit: Trading-Wallet-Schlüssel bleiben im Cold Storage, zum Signieren dienen Hot Keys
• Betrieb: Mehrere Teammitglieder können mit unterschiedlichen Schlüsseln signieren
• Automatisierung: Automatisierte Systeme können mit dedizierten Schlüsseln signieren

Zwei Autorisierungsmodelle

Hypercall verwendet je nach Produkt zwei getrennte Delegationssysteme:

Produkt	Delegationstyp	Speicherort	Einrichtung
Optionen (REST API)	Agent-Autorisierung	Engine-Zustand von Hypercall	POST /approve-agent
Perps	API-Wallet	On-Chain (Ihr Account-Contract)	Direktive hc_update_api_wallet

Die beiden Systeme sind voneinander unabhängig. Wenn Sie einen Agent für den Optionshandel genehmigen, ist er damit nicht für Perps autorisiert, und umgekehrt.

Optionen: Agent-Autorisierung (Off-Chain)

Agents signieren PlaceOrder- und CancelOrder-EIP-712-Nachrichten im Namen einer Trading-Wallet. Die API prüft den Agent gegen den Autorisierungszustand der Engine, bevor die Order die Engine erreicht.

Perps: API-Wallet (On-Chain)

API-Wallets signieren Perp-Orders und Stornierungen in der EIP-712-Domain HypercallApiSign. Hypercall prüft den Signierer gegen Ihren Account-Contract (isApiWalletActive()), bevor die Order angenommen wird. Auf der TEE-Route (Standard in der App, für API-Clients per Opt-in) signiert und sendet eine sichere Enklave, die einen separaten Hyperliquid-Trading-Schlüssel für Ihren Account hält, die native Order. Auf der Smart-Contract-Route, einer erweiterten Einstellung in der App, läuft die Order über Ihren Account-Contract. Die Signier-Referenz finden Sie unter EIP-712-Signierung, den Ablauf unter Perps.

Um eine API-Wallet hinzuzufügen oder zu entfernen, reichen Sie eine Direktive hc_update_api_wallet ein, die von der Manager-Wallet des Accounts signiert ist.

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

Schutz vor Nonce-Replay

Die Nonce-Verwaltung folgt dem Nonce-Modell von Hyperliquid. Alle signierten Aktionen (Orders, Genehmigung und Widerruf von Agents, 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. !stored_set.contains(nonce): sie kein Duplikat ist
2. nonce > min(stored_set), sobald die Menge 100 Einträge enthält: sie größer als die kleinste gespeicherte Nonce ist
3. nonce innerhalb von (T - 2 Tage, T + 1 Tag) um den Server-Zeitstempel liegt

Nonces außerhalb der Reihenfolge sind erlaubt (z. B. funktionieren Nonce 105 und danach 102, sofern beide über dem Minimum der Menge liegen). Die Menge ist auf 100 Einträge begrenzt, daher werden die ältesten Einträge verdrängt, sobald neue hinzukommen. So kann eine einzelne große Nonce einen Account nicht unbrauchbar machen.

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-Epoch) als Ausgangswert für die Nonce verwenden und monoton hochzählen.

Agent-Autorisierung für Optionen

Direkte Signierung

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 beim Neustart

Agent genehmigen

Endpunkt: POST /approve-agent

Request: ApproveAgentRequest

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

Signierung:

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

EIP-712-Struct:

struct ApproveAgent {
    address agent;
    uint64 nonce;
}

Response: ApproveAgentResponse

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

Hinweise:

• Die Agent-Autorisierung ist journalisierter Engine-Zustand und übersteht Neustarts
• Über diesen Endpunkt erteilte Genehmigungen laufen nicht ab

Agent widerrufen

Endpunkt: DELETE /revoke-agent

Request: RevokeAgentRequest

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

Signierung:

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

EIP-712-Struct:

struct RevokeAgent {
    address agent;
    uint64 nonce;
}

Response: 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-Requests durch. Für Beiträge in der Trollbox kann eine positive Agent-Autorisierung länger zwischengespeichert werden, sodass ein kürzlich widerrufener Agent eventuell noch posten kann, bis dieser Cache abläuft oder die Best-Effort-Invalidierung den betreffenden Edge-Standort erreicht. Dieser Cache autorisiert keine schreibenden Aufrufe der Trading-API.
• Nach dem Widerruf kann der Agent nicht mehr für die Wallet signieren

Alle Agents widerrufen

Endpunkt: DELETE /revoke-all-agents

Request: { "nonce": 3, "signature": "0x..." }, vom Wallet-Inhaber über RevokeAllAgents(uint64 nonce) signiert. Entfernt sämtliche Agents der wiederhergestellten Wallet.

Autorisierte Agents abrufen

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

Query-Parameter:

• wallet (erforderlich)

Response:

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

Hinweise:

• Gibt nur aktive, nicht abgelaufene Agents zurück

Verwendung von Agents

Orders mit einem Agent signieren

Sobald ein Agent genehmigt ist:

1. Order mit der Agent-Wallet signieren: Verwenden Sie die Agent-Wallet, um PlaceOrder- / CancelOrder-Nachrichten zu signieren
2. Feld wallet setzen: Setzen Sie das Feld wallet auf die Adresse der Trading-Wallet (nicht auf die Agent-Adresse)
3. Prüfung durch die Middleware: Die Middleware prüft, ob 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. The REST body uses snake_case `client_id`.
const { clientId, ...rest } = message;
const response = await fetch('/order', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...rest,
    client_id: clientId,
    signature
  })
});

Bulk-Orders mit einem Agent

Bulk-Endpunkte prüfen die Agent-Autorisierung für jedes einzelne Element:

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

Autorisierungsprüfungen

Middleware (einzelne Orders)

Endpunkte:

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

Prüfung: signature_and_agent_middleware verifiziert:

1. Die Wiederherstellung der Signatur gelingt
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. Wiederherstellung der Signatur 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, beim Engine-Replay wiederhergestellt und für API-Prüfungen über den Lese-Snapshot bereitgestellt.

Autorisierungslogik

Die Autorisierung des Signierers folgt einer expliziten ODER-Logik:

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

Ablauf

Die Engine unterstützt ein expires_at für eine Autorisierung und behandelt einen abgelaufenen Agent als nicht autorisiert. POST /approve-agent setzt keinen solchen Wert, daher bleiben über die API genehmigte Agents aktiv, bis sie widerrufen werden.

Sicherheitsaspekte

1. Sicherheit der Agent-Schlüssel: Schützen Sie die privaten Schlüssel der Agents (verwenden Sie Hardware-Wallets oder eine sichere Schlüsselverwaltung)
2. Regelmäßige Überprüfung: Prüfen Sie die autorisierten Agents regelmäßig über GET /authorized-agents
3. Ungenutzte Agents widerrufen: Widerrufen Sie Agents, die nicht mehr benötigt werden

Best Practices

1. Agents für die Automatisierung nutzen: Bewahren Sie die Trading-Wallet-Schlüssel im Cold Storage auf und setzen Sie Agents für automatisierte Systeme ein
2. Umfang der Agents begrenzen: Genehmigen Sie nur Agents, die tatsächlich 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

"Signer 0x... is not authorized to act for wallet 0x..."

Ursache: Der Agent ist nicht genehmigt, oder die Autorisierung ist abgelaufen bzw. wurde 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 im Engine-eigenen Autorisierungszustand nicht vorhanden
• Die Autorisierung wurde widerrufen
• Die Autorisierung ist abgelaufen

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