压缩与缓存

GET /markets 等大型公开读取返回的是数兆字节的 JSON。请请求压缩，并通过每个响应中的 Cache-Control 响应头判断数据的新鲜程度。

压缩

发送 Accept-Encoding: gzip，API 将以 gzip 压缩响应体并返回 Content-Encoding: gzip。GET /markets 的大小将从约 4 MB 降至约 0.6 MB。

• 浏览器和 Node.js fetch 会自动发送该请求头并自动解压。
• Rust hypercall-client 在其 HTTP 客户端中启用了 gzip，因此每个 REST 调用都会请求压缩并透明解码。
• Python 的 requests 和 httpx 默认发送该请求头并自动解压。普通的 urllib 两者都不做，因此您会收到未压缩的响应体。
• curl 需要加上 --compressed。

小于约 1 KB 的响应不压缩。WebSocket 帧不受影响；请参阅 WebSocket 压缩。

Cache-Control

每个读取都会告诉您共享缓存是否可以保存它。

响应头	出现位置	含义
public, max-age=N	公开市场数据：/markets、/instruments、/instrument-specs、/exchange-info、希腊字母、期权与到期日摘要、历史理论价、资金池读取、/version	任何缓存都可以在最多 N 秒内复用响应体。大多数为 1 到 15 秒；历史数据可能更长。
public, max-age=N, stale-while-revalidate=M	上述部分读取	超过 N 秒后，缓存可以在后台获取新副本的同时，继续提供旧响应体最多 M 秒。
no-store	钱包范围和需认证的读取：投资组合、未成交订单、成交记录、按钱包筛选的交易、MMP 配置等	任何缓存都不会存储。每个请求都会到达 API。
无	其他所有内容，包括 /orderbook 和所有写入	不缓存。

请将 public 读取视为最多已有 max-age（加上任何 stale-while-revalidate）秒的旧数据。当您需要最新状态来做出交易决策时，请从 WebSocket 频道或钱包范围的读取中获取，它们永远不会被缓存。

错误响应（4xx、5xx）永远不会带有 public，也永远不会被缓存。当 API 返回错误时，缓存不会继续提供已过期的响应体；您会收到该错误。

始终到达 API 的请求

携带以下任一内容的请求永远不会收到缓存的响应体，且该请求收到的任何内容都不会被存储：

• Authorization 或 Cookie
• X-Hypercall-Signature 或 X-Hypercall-Expires-At-Ms（MMP 配置等签名读取）
• X-Hypercall-Fence 或 X-Hypercall-Fence-Wait（写后读一致性，请参阅做市商保护）
• X-Hypercall-Gateway-Token 或 X-Admin-Key
• GET 或 HEAD 以外的任何方法，以及 WebSocket 升级

写后读屏障与缓存从不混用。支持 X-Hypercall-Fence 的路由为 no-store，而 public 路由从不等待屏障。

X-Cache-Status

经过 Hypercall 边缘缓存的响应会携带 X-Cache-Status：

值	含义
HIT	在 max-age 内由边缘缓存提供。
MISS	从 API 获取。如果响应为 public，现已被缓存。
BYPASS	请求携带了上述列表中的某个请求头，因此直接发往 API，且未存储任何内容。
EXPIRED	缓存副本已超过其有效期，因此重新向 API 请求。
STALE 或 UPDATING	在 stale-while-revalidate 窗口内由缓存提供，同时获取新副本。

写入及其他非 GET 请求不带 X-Cache-Status。该响应头仅供参考：请勿据此分支交易逻辑。并非所有环境都已部署边缘缓存。不带该响应头的响应直接来自 API。