Komprimierung und Caching

Große öffentliche Lesezugriffe wie GET /markets umfassen Megabytes an JSON. Fordern Sie Komprimierung an und lassen Sie sich vom Cache-Control-Header jeder Antwort sagen, wie aktuell sie ist.

Komprimierung

Senden Sie Accept-Encoding: gzip, und die API liefert den Body gzip-komprimiert mit Content-Encoding: gzip. GET /markets schrumpft von etwa 4 MB auf etwa 0,6 MB.

• Browser und Node.js fetch senden den Header und dekomprimieren automatisch.
• Rust hypercall-client aktiviert gzip in seinem HTTP-Client, sodass jeder REST-Aufruf es anfordert und transparent dekodiert.
• Python requests und httpx senden den Header und dekomprimieren standardmäßig. Einfaches urllib tut beides nicht, Sie erhalten also den unkomprimierten Body.
• curl benötigt --compressed.

Antworten unter etwa 1 KB werden unkomprimiert gesendet. WebSocket-Frames sind nicht betroffen; siehe WebSocket-Komprimierung.

Cache-Control

Jeder Lesezugriff teilt Ihnen mit, ob ein gemeinsam genutzter Cache ihn speichern darf.

Antwort-Header	Wo Sie ihn sehen	Bedeutung
public, max-age=N	Öffentliche Marktdaten: /markets, /instruments, /instrument-specs, /exchange-info, Greeks, Options- und Verfallsübersichten, historische Theos, Pool-Lesezugriffe, /version	Jeder Cache darf den Body bis zu N Sekunden wiederverwenden. Meist sind es 1 bis 15 Sekunden; historische Daten können länger gelten.
public, max-age=N, stale-while-revalidate=M	Einige der oben genannten Lesezugriffe	Nach N Sekunden darf ein Cache den alten Body noch bis zu M weitere Sekunden ausliefern, während er im Hintergrund einen neuen abruft.
no-store	Wallet-bezogene und authentifizierte Lesezugriffe: Portfolio, offene Orders, Fills, nach Wallet gefilterte Trades, MMP-Konfiguration und Ähnliches	Wird von keinem Cache gespeichert. Jede Anfrage erreicht die API.
keiner	Alles andere, einschließlich /orderbook und aller Schreibzugriffe	Nicht gecacht.

Behandeln Sie einen public-Lesezugriff als bis zu max-age (plus ein etwaiges stale-while-revalidate) Sekunden alt. Wenn Sie für eine Handelsentscheidung den neuesten Stand benötigen, lesen Sie ihn über die WebSocket-Kanäle oder über einen Wallet-bezogenen Lesezugriff, die nie gecacht werden.

Fehlerantworten (4xx, 5xx) tragen nie public und werden nie gecacht. Ein Cache liefert keinen abgelaufenen Body weiter aus, während die API Fehler zurückgibt; Sie erhalten den Fehler.

Anfragen, die immer die API erreichen

Ein gecachter Body wird nie an eine Anfrage zurückgegeben, die einen der folgenden Punkte enthält, und nichts, was eine solche Anfrage erhält, wird gespeichert:

• Authorization oder Cookie
• X-Hypercall-Signature oder X-Hypercall-Expires-At-Ms (signierte Lesezugriffe wie die MMP-Konfiguration)
• X-Hypercall-Fence oder X-Hypercall-Fence-Wait (Read-after-Write-Konsistenz, siehe Market Maker Protection)
• X-Hypercall-Gateway-Token oder X-Admin-Key
• jede andere Methode als GET oder HEAD sowie WebSocket-Upgrades

Read-after-Write-Fences und Caching werden nie kombiniert. Eine Route, die X-Hypercall-Fence berücksichtigt, ist no-store, und eine public-Route wartet nie auf einen Fence.

X-Cache-Status

Antworten, die den Hypercall-Edge-Cache durchlaufen, tragen X-Cache-Status:

Wert	Bedeutung
HIT	Aus dem Edge-Cache ausgeliefert, innerhalb von max-age.
MISS	Von der API abgerufen. War die Antwort public, ist sie jetzt gecacht.
BYPASS	Die Anfrage enthielt einen Header aus der obigen Liste, ging daher direkt an die API, und nichts wurde gespeichert.
EXPIRED	Die gecachte Kopie hatte ihre Lebensdauer überschritten, daher wurde die API erneut angefragt.
STALE oder UPDATING	Innerhalb des stale-while-revalidate-Fensters aus dem Cache ausgeliefert, während eine neue Kopie abgerufen wird.

Schreibzugriffe und andere Nicht-GET-Anfragen haben keinen X-Cache-Status. Der Header ist rein informativ: Machen Sie Ihre Handelslogik nicht davon abhängig. Noch nicht jede Umgebung verfügt über den Edge-Cache. Eine Antwort ohne den Header kam direkt von der API.