API 交易

如果您正在将做市系统、报价系统或执行服务接入 Hypercall，请参考本指南。

生产环境 API

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

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

测试网状态： 在 Hypercall 获取更多测试网 HYPE 之前，测试网暂时停用。新的做市商接入应使用生产环境，除非 Hypercall 为您提供了专用环境。

白名单数据流

指示性报价提供方（quote-provider）推流尚未全面开放。Hypercall 可以为经批准的接入方开通此功能，但常规做市商接入应使用 REST 行情数据，以及需要认证的订单、成交和投资组合 WebSocket 频道。

接入清单

交易钱包：能够签署 EIP-712 类型化数据的 EVM 钱包。
资金：在 app.hypercall.xyz 为生产环境充值 USDC。
权限：如需做市商限额或指示性报价提供方推流，请联系 Hypercall。
环境：使用上文列出的生产环境 REST 与 WebSocket URL。请勿假定测试网可用。
对账：自行持久化保存客户端订单 ID、nonce、订单、成交及持仓快照。

接入方式

TypeScript SDK

安装官方 TypeScript 包，获取类型化 REST 客户端、运行时请求校验以及 EIP-712 签名辅助工具：

npm install @hypercallxyz/sdk

有关行情数据读取、账户查询、签名写操作、错误处理及包入口，请参阅 TypeScript SDK 指南。TypeScript SDK 目前涵盖 REST 和签名功能。如需流式更新，请直接连接 WebSocket API。

Rust Crates

Hypercall 在 github.com/hypercall-public/hypercall-rust 发布了覆盖所支持接入面的公开 Rust crate。这些 crate 未发布到 crates.io。请以 git 依赖方式添加，并锁定某个 tag 或 commit。

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：获取期权链层面的最优买价、最优卖价、标记价格以及希腊字母类汇总字段。

2. 配置签名

写操作使用 EIP-712 签名。

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

做市商通常应使用代理钱包（agent wallet）：

主钱包通过 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": 1791273600000,
        "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": 1791273600001,
        "signature": "0x..."
      }
    ]
  }'

关键规则：

price 和 size 均为字符串，在签名载荷和 JSON 请求体中都是如此。
字符串格式必须完全一致，签名与 JSON 请求体之间不得有差异。
每次批量请求最多 50 笔订单。
批量路由仅限订单簿。route 可以为 book_only 或省略。批量接口会拒绝 route: "best_execution"，如需使用请改用 POST /order。目前所有下单接口均拒绝 route: "rfq_only"。
Nonce 为毫秒级时间戳。 超出服务器时间前两天至后一天范围的 nonce 将被拒绝。请参阅 Nonce 管理。
大多数交易拒绝返回 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",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600002,
        "signature": "0x..."
      }
    ]
  }'

替换订单不包含 route 字段，并以 ReplaceOrder 类型签名，即在订单字段基础上增加原订单的 orderId。请参阅认证与签名。

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：订单状态变化，包括 PARTIALLY_FILLED。其中 filled_size 为该订单的累计成交数量。
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 阶段有意设置了限制。

保证金：标准保证金和组合保证金均已上线。任何账户在其 HyperCore 账户切换为统一模式后，均可切换至组合保证金。
期权做空：标准保证金模式下已开放期权做空，受保证金及您所在等级限额约束。请通过 GET /risk/limits?wallet=... 查看 standard_margin_shorts_enabled。
永续合约：永续合约订单使用独立的签名域和接口。请参阅认证与签名。
指示性推流：报价提供方推流采用白名单制，尚非公开的通用接入方式。
强制平仓工具：公开的强制平仓 crate 用于标准保证金强制平仓流程，而非常规做市。
测试网：在 Hypercall 获取更多测试网 HYPE 之前不可用。

常见问题

签名验证失败

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

保证金不足

查看 GET /portfolio?wallet=...。
追加抵押品或减小报价数量。
确认您的钱包具备所报价策略所需的权限等级。

卖单因权限或覆盖不足被拒绝

查看 GET /risk/limits?wallet=...。部分等级仅允许由已成交多头持仓覆盖的卖出。
如您的钱包需要调整等级，请联系 Hypercall。

WebSocket 未收到成交

订阅需认证的频道前，先发送 Authenticate 消息。
订阅 fills，而不仅是 order_updates。
重连后使用 GET /fills?wallet=... 兜底。

后续步骤

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

接入清单​

接入方式​

TypeScript SDK​

Rust Crates​

原生 REST 与 WebSocket​

1. 发现市场​

2. 配置签名​

3. 使用批量订单报价​

4. 刷新报价​

5. 订阅更新​

6. 状态对账​

7. 了解上线范围​

常见问题​

签名验证失败​

保证金不足​

卖单因权限或覆盖不足被拒绝​

WebSocket 未收到成交​

后续步骤​