API 交易

如果您正在将做市商系统、报价系统或执行服务与 Hypercall 集成，请使用本指南。

生产环境 API

REST 基础 URL： https://api.hypercall.xyz

WebSocket URL： wss://api.hypercall.xyz/ws

测试网状态： 测试网暂时禁用，直至 Hypercall 获取更多测试网 HYPE。除非 Hypercall 为您提供专用环境，否则新的做市商集成应使用生产环境。

白名单数据流

指示性报价提供方数据流尚未全面开放。Hypercall 可为经批准的集成启用此功能，但常规做市商接入应使用 REST 市场数据，以及经过身份验证的订单、成交和投资组合 WebSocket 频道。

接入清单

交易钱包：能够签署 EIP-712 类型化数据的 EVM 钱包。
资金：在 app.hypercall.xyz 完成生产环境 USDC 入金。
访问权限：如需做市商额度、卖方（writer）权限或指示性报价提供方数据流，请联系 Hypercall。
环境：使用上述生产环境 REST 和 WebSocket URL。请勿假设测试网可用。
对账：请自行持久化您的客户端订单 ID、nonce、订单、成交和持仓快照。

集成方式

Rust Crate

Hypercall 为受支持的集成接口发布了公开的 Rust crate：

公开的 Rust 代码仓库位于 github.com/hypercall-public/hypercall-rust。

Crate	用途
`hypercall-client`	REST 客户端、WebSocket 客户端、EIP-712 签名辅助工具、本地签名以及 AWS KMS 签名
`hypercall-sdk-types`	客户端共享的公开请求和响应 DTO
`hypercall-ws-protocol`	公开的 WebSocket 消息类型
`hypercall-hyperliquid`	可选的 Hyperliquid 辅助 crate，适用于同时在 Hyperliquid 上进行对冲的集成
`hypercall-liquidator`	标准保证金强制平仓参考客户端。常规做市不需要此工具

请尽可能使用这些 crate。它们内置了当前的签名域、请求结构、路由规则和字符串格式规则，手动实现这些内容很容易出错。

原生 REST 和 WebSocket

如果您不使用 Rust，请以 API 参考、身份验证与签名和 WebSocket API 页面作为权威来源。

1. 发现市场

首先加载活跃市场和合约规格：

curl https://api.hypercall.xyz/markets
curl "https://api.hypercall.xyz/instrument-specs?currency=BTC"
curl "https://api.hypercall.xyz/options-summary?currency=BTC"

使用：

GET /markets 获取已上线的标的资产和到期日分组。
GET /instrument-specs?currency=BTC 获取可交易的期权规格。
GET /options-summary?currency=BTC 获取期权链层面的最优买价、最优卖价、标记价格以及 Greeks 类摘要字段。

2. 配置签名

写入操作使用 EIP-712 签名。

生产环境链 ID： 999
域名称： Hypercall
域版本： 1
验证合约： 0x0000000000000000000000000000000000000000

做市商通常应使用代理钱包：

主钱包通过 POST /approve-agent 批准一个代理。
代理钱包代表主钱包签署下单和撤单请求。
主钱包仍作为投资组合、资金和风险身份。

有关确切的结构体和字段名称，请参阅身份验证与签名。

3. 使用批量订单报价

对于做市商报价，请使用 POST /bulk_order 并设置 route: "book_only"。

curl -X POST https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "100.0",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1001,
        "signature": "0x..."
      },
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "101.0",
        "size": "0.1",
        "side": "Sell",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-ask-1",
        "mmp_enabled": true,
        "nonce": 1002,
        "signature": "0x..."
      }
    ]
  }'

重要规则：

在已签名的负载和 JSON 请求体中，price 和 size 均为字符串。
签名与 JSON 请求体之间的字符串格式必须完全一致。
每次请求的批量订单数量上限为 50 个订单。
批量路由仅限订单簿路由。route: "best_execution" 和 route: "rfq_only" 是单笔订单路径，不是批量报价路径。
大多数交易拒绝会返回 HTTP 200，并带有 status: "REJECTED"。请务必检查每个结果。

4. 刷新报价

当您希望在一次请求中撤销现有报价订单并提交替换订单时，请使用 PUT /bulk_order。

curl -X PUT https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      {
        "wallet": "0x...",
        "order_id": 12345,
        "symbol": "BTC-20260131-100000-C",
        "price": "99.5",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "nonce": 1003,
        "signature": "0x..."
      }
    ]
  }'

PUT /bulk_order 会先撤销旧批次，再创建新批次。结果按请求顺序逐条返回每个替换的结果。若某笔撤单失败，则对应的替换订单不会被创建。

对于单笔延迟敏感的替换操作，请使用 PUT /order。

5. 订阅更新

连接到生产环境 WebSocket：

const ws = new WebSocket("wss://api.hypercall.xyz/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "Authenticate", wallet: "0xYourWallet" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "order_updates" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "fills" }));
  ws.send(JSON.stringify({ type: "Subscribe", channel: "portfolio" }));
};

使用：

order_updates 获取订单状态变化。此频道有意省略部分成交更新。
fills 作为部分成交和已执行交易的权威来源。
portfolio 获取账户状态更新。
orderbook、trades、options_chain 和 index_prices 获取公开市场数据。

有关频道格式和存活性行为，请参阅 WebSocket API。

6. 状态对账

即使您的 WebSocket 连接正常，也应运行对账循环。

状态	REST 回退方案	WebSocket 频道
订单	`GET /orders?wallet=...`	`order_updates`
成交	`GET /fills?wallet=...`	`fills`
投资组合	`GET /portfolio?wallet=...`	`portfolio`
市场	`GET /markets`、`GET /instrument-specs`	`market_updates`、`options_chain`

推荐的对账循环：

启动时加载市场数据。
报价前加载未成交订单和最新成交记录。
订阅 WebSocket 更新。
使用确定性的客户端 ID 进行报价。
定期轮询 REST，以便从断线或消息丢失中恢复。
遇到未知状态时停止报价，直到 REST 和 WebSocket 状态再次一致。

7. 了解上线范围

主网 Alpha 阶段有意进行了限制。

保证金：标准保证金已上线。组合保证金（Portfolio Margin）尚未全面启用。
卖方权限：期权空头敞口需要经批准的访问权限。
指示性数据流：报价提供方数据流采用白名单机制，目前尚不是通用的公开集成路径。
强制平仓工具：公开的 liquidator crate 用于标准保证金强制平仓工作流，不适用于常规做市。
测试网：不可用，直至 Hypercall 获取更多测试网 HYPE。

常见问题

签名验证失败

检查 price 和 size 是否为 JSON 字符串。
检查签名字符串与提交字符串是否完全一致。
生产环境请使用链 ID 999。
每次签名写入请使用新的 nonce。
确认签名者是该钱包本身或经批准的代理。

保证金不足

检查 GET /portfolio?wallet=...。
增加抵押品或减小报价规模。
确认您的钱包具备所报价策略所需的访问级别。

卖出因权限或持仓覆盖不足被拒绝

确保卖出订单由已成交的多头持仓覆盖，或联系 Hypercall 获取卖方权限。
请勿假设新钱包已启用卖方权限。

WebSocket 未收到成交

在订阅需要身份验证的频道之前，先发送 Authenticate 消息。
订阅 fills，而不仅仅是 order_updates。
重连后回退到 GET /fills?wallet=...。

后续步骤

身份验证： 身份验证与签名
WebSocket 协议： WebSocket API
速率限制： 速率限制
错误： 错误与拒绝原因
参考： API 参考

接入清单​

集成方式​

Rust Crate​

原生 REST 和 WebSocket​

1. 发现市场​

2. 配置签名​

3. 使用批量订单报价​

4. 刷新报价​

5. 订阅更新​

6. 状态对账​

7. 了解上线范围​

常见问题​

签名验证失败​

保证金不足​

卖出因权限或持仓覆盖不足被拒绝​

WebSocket 未收到成交​

后续步骤​