如何在Hyperliquid上交易HIP-4预测市场

QuickNode 发布于 2026-05-06 阅读 351

本文详细介绍了如何在Hyperliquid网络上交易HIP-4预测市场。

## 概述

[HIP-4](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets) 于2026年5月2日在Hyperliquid主网上线，引入了完全抵押的二元结果市场，这些市场以[USDH](https://usdh.com/)结算为0或1。这些市场与永续合约和现货一起存在于HyperCore中，共享相同的CLOB基础设施、相同的WebSocket流以及你用于其他所有Hyperliquid资产的相同数据端点。本指南首先带你了解数据模型，然后逐步引导你发现市场、读取和流式传输订单簿、获取USDH，并使用Quicknode Hyperliquid TypeScript SDK进行交易。

TL;DR

- HIP-4市场是二元YES/NO合约，以USDH结算为0或1，在HyperCore CLOB上交易，开仓费为零
- 每一方在`allMids`、数据集以及所有流式API中都显示为`#N`币种（例如，YES为`#20`，NO为`#21`）
- Quicknode为TypeScript、Python、Go和Rust构建并维护[SDK](https://www.quicknode.com/docs/hyperliquid)，以及[托管的REST API参考](https://hyperliquidapi.com/)和[gRPC流式端点](https://www.quicknode.com/docs/hyperliquid#hypercore-apis)
- 本指南的完整源代码位于 [qn-guide-examples](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets)
- [SQL Explorer](https://www.quicknode.com/sql-explorer) 允许你使用纯SQL查询历史HIP-4交易和订单

### 你将做什么

- 理解HIP-4数据模型：`#N`币种表示法、`outcomeMeta`、`allMids`以及交易/订单/簿更新数据集
- 设置Quicknode Hyperliquid端点并初始化TypeScript SDK
- 批准构建者费用（每个钱包一次）
- 发现活跃的预测市场并检查YES/NO侧的形状
- 实时读取和流式传输双方的订单簿
- 通过现货市场交换USDC来获取USDH
- 下达限价单和市价单，取消现有订单，并处理常见错误

### 你需要什么

- 一个[Quicknode账户](https://www.quicknode.com/signup?utm_source=internal&utm_campaign=guides&utm_content=trade-hip-4-prediction-markets-on-hyperliquid)并配有[Hyperliquid端点](http://quicknode.com/hyperliquid)
- [Node.js 20+](https://nodejs.org/en/download/) 和一个包管理器（`npm`、`pnpm`或`yarn`）
- 一个Hyperliquid钱包私钥以及至少一些USDC在你的现货余额中（用于USDH兑换步骤）
- 熟悉TypeScript和基本预测市场概念

## 什么是HIP-4结果市场？

HIP-4将二元结果市场引入HyperCore。每个市场提出一个是非问题（例如，“BTC在到期时是否会高于79,980 USD？”）。交易者使用USDH作为抵押品购买YES或NO头寸。到期时，获胜方每个单位结算为1 USDH，失败方结算为0。YES代币在任何时刻的价格代表市场对事件发生的隐含概率。

HIP-4市场运行条件：

- **链上且无需许可。** 直接在Hyperliquid L1上结算，无需桥接或托管方。
- **开仓费为零。** 与永续合约和现货不同，HIP-4对开仓不收取任何费用（构建者费用仍然适用）。
- **与所有其他资产在同一个CLOB上。** 相同的L2订单簿端点、WebSocket流和成交数据集涵盖了HIP-4以及其他所有资产。如果你已经查询Hyperliquid数据，基本上已经完成了大部分工作。

## Quicknode Hyperliquid开发者工具包

在编写任何代码之前，值得了解Quicknode为Hyperliquid提供了什么，以便你为要构建的内容选择合适的工具。

| 工具 | 提供的内容 | 链接 |
| --- | --- | --- |
| **Hyperliquid SDK（TypeScript、Python、Go、Rust）** | 完整的交易和数据SDK：订单、流、账户状态 | [Hyperliquid SDK](https://www.quicknode.com/docs/hyperliquid/supported-hyperliquid-sdks) |
| **数据集** | 通过gRPC和JSON-RPC/WebSocket API包含不同类型区块链和交易所事件的数据流，例如`trades`、`orders`和`book-updates` | [文档](https://www.quicknode.com/docs/hyperliquid/datasets) |
| **WebSocket / JSON-RPC API** | 实时订阅（`bookUpdates`、`allMids`、`trades`）和状态查询 | [文档](https://www.quicknode.com/docs/hyperliquid/json-rpc/hl_getBatchBlocks) |
| **gRPC流式传输** | 最低延迟的区块级订单簿和交易数据路径，适合高频策略 | [文档](https://www.quicknode.com/docs/hyperliquid#hypercore-apis) |
| **信息端点** | 快照查询：`outcomeMeta`、`allMids`、`l2Book`、`clearinghouseState` | [文档](https://www.quicknode.com/docs/hyperliquid/info-endpoints) |
| **REST API (hyperliquidapi.com)** | 由Quicknode构建的Hyperliquid零托管REST构建者API | [hyperliquidapi.com](https://hyperliquidapi.com/) |
| **SQL Explorer** | 对索引表的历史查询：`hyperliquid_trades`、`hyperliquid_orders`以及35个以上其他表 | [sql-explorer](https://www.quicknode.com/sql-explorer) |

本指南全程使用[Hyperliquid SDK for TypeScript](https://www.npmjs.com/package/@quicknode/hyperliquid-sdk)。它允许你通过单一统一接口访问所有数据API并进行交易。

## 数据模型

SDK使得处理HIP-4市场变得容易，但理解底层数据模型很重要。HIP-4数据通过与其他Hyperliquid资产相同的API和数据集流动。唯一区分元素是`#N`币种表示法。本节涵盖在编写任何代码之前你需要知道的三件事。

### 市场身份与发现

每个HIP-4结果侧由一个以`#`为前缀的币种字符串标识，例如`#20`（YES）和`#21`（NO）。这将结果市场币种与永续合约（无前缀）和现货代币（`@N`或`xyz:`前缀）区分开来。整数`N`从资产的数字ID派生而来，编码方式为`N = 10 * outcomeIndex + sideIndex`。 [Hyperliquid资产ID](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids)规范涵盖了完整的映射。

两个端点为你提供任何活跃市场的完整画面：

**[`outcomeMeta`](https://www.quicknode.com/docs/hyperliquid/info-endpoints/outcomeMeta)** 返回市场定义：

outcomeMeta响应

```json
{
  "outcomes": [\
    {\
      "outcome": 3,\
      "name": "Recurring",\
      "description": "class:priceBinary|underlying:BTC|expiry:20260506-0600|targetPrice:80930|period:1d",\
      "sideSpecs": [\
        { "name": "Yes" },\
        { "name": "No" }\
      ]\
    }\
  ],
  "questions": []
}
```

| 字段 | 描述 |
| --- | --- |
| `outcomes[].outcome` | 标识市场实例的递增整数 |
| `outcomes[].name` | 市场类型标签（例如，`"Recurring"`） |
| `outcomes[].description` | 管道分隔的键值对：`class`、`underlying`、`expiry`（格式`YYYYMMDD-HHMM`）、`targetPrice`、`period` |
| `outcomes[].sideSpecs` | 每侧一个条目的数组。`sideSpecs[0]`是YES，`sideSpecs[1]`是NO |
| `questions` | 保留给非二元市场类型，对价格二元市场为空 |

**[`allMids`](https://www.quicknode.com/docs/hyperliquid/info-endpoints/allMids)** 返回交易所上每种资产的实时中间价格。HIP-4市场以`#N`键的形式出现，与常规永续和现货代码并列：

allMids响应（摘录）

```json
{
  "BTC": "96423.0",
  "ETH": "1823.5",
  "#20": "0.47",
  "#21": "0.53"
}
```

过滤以`#`开头的键以隔离结果市场中间价。`sdk.stream.allMids()`以连续实时流的形式提供相同数据。

### 数据中的活动表现

当订单被下达且交易被撮合时，Quicknode [Hyperliquid数据集](https://www.quicknode.com/docs/hyperliquid/datasets)会以`#N`标识符捕获活动：

**[`trades`](https://www.quicknode.com/docs/hyperliquid/datasets/trades):** 每个交易行使用`coin: "#N"`。`feeToken`字段使用`+N`表示法（例如，`+20`），并且`fee`始终为`"0.0"`，因为HIP-4开仓订单不收取费用。

**[`orders`](https://www.quicknode.com/docs/hyperliquid/datasets/orders):** 订单记录使用相同的`coin: "#N"`表示法。结果交易的双边都作为买单出现（`side: "B"`）。

**[`book-updates`](https://www.quicknode.com/docs/hyperliquid/datasets/book-updates):** 每个事件包含一个`raw_book_diff`字段：`{"new": {"sz": "..."}}`（新订单下达）、`"remove"`（订单取消或成交）或`{"update": {"origSz": "...", "newSz": "..."}}`（原地尺寸修改，仅限HIP-4）。使用这些来维护本地订单簿副本。

**[`l2-book`](https://www.quicknode.com/docs/hyperliquid/datasets/l2-book) 和 [`l4-book`](https://www.quicknode.com/docs/hyperliquid/datasets/l4-book):** 可按币种查询的聚合和原始订单簿快照。传递`"#N"`作为币种过滤器以检索特定结果侧的数据。

### 读取价格：隐含概率

因为YES和NO是互补结果，它们的中间价格之和约为1.0：

```text
YES 中间价 + NO 中间价 ≈ 1.0
```

YES中间价为`0.47`意味着市场隐含该事件发生的概率为47%。NO中间价为`0.53`隐含53%。与1.0的微小偏差反映了价差以及双方之间任何暂时的套利机会。

SDK抽象了大部分内容：`sdk.predictionMarkets()`会为你解析`#N`符号，通过正确的质押账户路由USDH兑换，并处理API响应的类型转换。当你直接读取原始`allMids`、数据集记录或gRPC事件时，上述结构才重要。有了这个基础，本指南的其余部分将进行实际操作。

## 使用Quicknode交易HIP-4市场

本节将引导你完成从零开始到在HIP-4市场进行实时交易所需的一切：批准构建者费用、验证设置、发现活跃市场、读取和流式传输订单簿、获取USDH以及下达第一个订单。

指南示例代码库包含七个独立的脚本，每个涵盖使用HIP-4的一个特定方面。你可以跟随下面的关键摘录来理解每个概念，或者克隆完整仓库并逐一运行脚本，以从你自己的钱包中查看实时输出。

### 获取示例代码

克隆并安装

```bash
git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/hyperliquid/hip4-prediction-markets
npm install
cp .env.example .env
```

在`.env`中填写你的端点、私钥和钱包地址（在下面的[设置你的Quicknode端点](https://www.quicknode.com/guides/hyperliquid/trade-hip-4-prediction-markets-on-hyperliquid#set-up-your-quicknode-endpoint)中介绍），然后构建并运行任何脚本：

构建并运行

```bash
npm run build
node --env-file=.env dist/0-approve.js
```

每个脚本都是独立的：

| 脚本 | 涵盖内容 |
| --- | --- |
| `0-approve.ts` | 一次性构建者费用批准 |
| `1-setup.ts` | 健康检查：端点、活跃市场、账户状态 |
| `2-list-markets.ts` | 发现活跃市场并检查完整的`PredictionMarket`形状 |
| `3-orderbook-snapshot.ts` | 获取YES和NO的L2订单簿，计算隐含概率 |
| `4-stream-orderbook.ts` | 订阅实时`bookUpdates`和`allMids` WebSocket流 |
| `5-buy-usdh.ts` | 通过现货市场`@230`将USDC兑换为USDH |
| `6-trade.ts` | 限价单和市价单、取消操作，并检查`PlacedOrder`形状 |

### 设置你的Quicknode端点

1. 登录你的[Quicknode仪表板](https://dashboard.quicknode.com/)。
2. 创建一个新端点，并选择 **Hyperliquid** 作为链。
3. 复制HyperCore HTTPS端点URL，并移除`/hypercore`后缀。
4. 在你的项目根目录中创建一个`.env`文件：

.env

```bash
QUICKNODE_ENDPOINT=https://your-endpoint.hype-mainnet.quiknode.pro/your-api-key/
PRIVATE_KEY=your_wallet_private_key_hex
WALLET_ADDRESS=your_wallet_address
USDH_AMOUNT=11
```

在任何shell脚本或cURL示例中，将你的端点作为一个变量保存：`TEST_RPC=$QUICKNODE_ENDPOINT`

警告

切勿将`.env`提交到版本控制。将其添加到`.gitignore`中。`PRIVATE_KEY`字段会提供对你钱包的完全控制。

### 初始化SDK

安装Quicknode Hyperliquid TypeScript SDK：

安装

```bash
npm install @quicknode/hyperliquid-sdk
```

使用不同的语言？

本指南使用TypeScript SDK。Quicknode还维护Python、Go和Rust的SDK（所有都具有相同的核心原语）。你可以在[Quicknode Hyperliquid文档中心](https://www.quicknode.com/docs/hyperliquid)找到所有SDK的链接。如果你更喜欢原始HTTP，[REST API参考](https://hyperliquidapi.com/)涵盖了本指南中使用的每个端点。

使用你的端点和签名凭证初始化SDK。`autoApprove: true`标志会在第一次交易时自动处理构建者费用批准，而`maxFee: "1%"`设置了你的钱包将接受的最大费率：

SDK初始化

```ts
import { HyperliquidSDK } from "@quicknode/hyperliquid-sdk";

const sdk = new HyperliquidSDK(process.env.QUICKNODE_ENDPOINT, {
  privateKey: process.env.PRIVATE_KEY,
  autoApprove: true,
  maxFee: "1%",
});
```

构建者费用

[构建者代码](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes)是一种Hyperliquid原生机制，允许基础设施提供商在交易所费用之上收取费用。你一次批准最高费率，实际收费始终等于或低于该费率。

### 批准构建者费用

在你的钱包可以交易之前，必须批准构建者费用。这是每个钱包的一次性链上操作。使用`autoApprove: true`，SDK会在你第一次交易时处理此操作，但显式运行它可以显示批准前后的状态，并确认一切就绪。

0-approve.ts（关键摘录）

```ts
// 1. 检查当前状态
const before = await sdk.approvalStatus() as any;

// 2. 批准
console.log(`\n批准构建者费用 (maxFee: ${MAX_FEE})...`);
const result = await sdk.approveBuilderFee(MAX_FEE) as any;

// 3. 验证
const after = await sdk.approvalStatus() as any;
```

完整源代码：[0-approve.ts](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets/src/0-approve.ts)

预期输出（首次运行）：

0-approve.ts输出

```bash
============================================================
构建者费用批准
============================================================

── 当前状态 ──────────────────────────────────────────
approved     : true
maxFeeRate   : 0%
canTradePerps: false
canTradeSpot : false
status msg   : 你的批准低于最低费用。请以更高的maxFeeRate重新批准。

批准构建者费用 (maxFee: 1%)...

── 批准结果 ──────────────────────────────────────────
{
  "status": "ok",
  "response": { "type": "default" }
}

── 批准后状态 ────────────────────────────────────────
approved     : true
maxFeeRate   : 1%
canTradePerps: true
canTradeSpot : true
status msg   : 你可以交易永续合约和现货。

批准成功。你现在可以交易永续合约、现货和HIP-4市场。
```

### 验证你的连接和活跃市场

在下达任何订单之前，请确认你的端点可达、HIP-4市场活跃，并且构建者费用批准已到位。

1-setup.ts（关键摘录）

```ts
const markets = await sdk.predictionMarkets();
console.log("活跃的HIP-4市场数量:", markets.length);

for (const m of markets) {
  console.log(`  ${m.title}`);
  console.log(`  YES: ${m.yes.symbol} (assetId: ${m.yes.assetId}) | mid: ${m.yes.mid}`);
  console.log(`   NO: ${m.no.symbol}  (assetId: ${m.no.assetId}) | mid: ${m.no.mid}`);
}

// ── 所有中间价格（过滤 HIP-4 # 资产）───────────────────
const allMids = await sdk.info.allMids() as any;
const hip4Mids = Object.entries(allMids).filter(([k]) => k.startsWith("#"));

const approval = await sdk.approvalStatus();
console.log("canTradePerps:", approval.canTradePerps);
console.log("canTradeSpot :", approval.canTradeSpot);
```

完整源代码：[1-setup.ts](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets/src/1-setup.ts)

预期输出（已修剪）：

1-setup.ts输出

```bash
── HIP-4 预测市场 ────────────────────────────────────
活跃市场数量   : 1

标题     : BTC 高于 79980 (05/09 12:00 UTC)
  到期时间 : 2026-05-09T12:00:00.000Z
  抵押品   : USDH
  最小订单 : 10 USDH
  YES       : #20 (assetId: 20) | mid: 0.47
  NO        : #21 (assetId: 21) | mid: 0.53

── HIP-4 中间价格（来自 allMids）──────────────────────
  #20   : 0.47
  #21   : 0.53

── 构建者费用批准 ────────────────────────────────────
canTradePerps: true
canTradeSpot : true
✓  构建者费用已批准。准备就绪。
```

### 浏览活跃预测市场

`sdk.predictionMarkets()` 返回每个活跃HIP-4市场的完整 `PredictionMarket` 形状，包括实时中间价格、`outcomeMeta` 中使用的管道分隔描述以及双边对象。

2-list-markets.ts（关键摘录）

```ts
import { HyperliquidSDK, type PredictionMarket } from "@quicknode/hyperliquid-sdk";

const markets = await sdk.predictionMarkets();

for (const market of markets as PredictionMarket[]) {
  console.log("标题      :", market.title);
  console.log("描述      :", market.description);
  console.log("标的资产  :", market.underlying);
  console.log("目标价格  :", market.targetPrice);
  console.log("到期时间  :", market.expiry);
  console.log("最小订单  :", market.minOrderValue, "USDH");

for (const side of market.sides) {
    const liveMid = await sdk.getMid(side);
    console.log(`  ${side.name}: symbol=${side.symbol}  assetId=${side.assetId}  mid=${side.mid}  liveMid=${liveMid}`);
  }
}
```

完整源代码：[2-list-markets.ts](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets/src/2-list-markets.ts)

预期输出（已修剪）：

2-list-markets.ts输出

```bash
────────────────────────────────────────────────────────────
标题      : BTC 高于 79980 (05/09 12:00 UTC)
描述      : Will BTC be above 79980|USD|2026-05-09T12:00:00.000Z
简短标识  : btc-above-79980-0509-1200-utc
标的资产  : BTC
目标价格  : 79980
到期时间  : 2026-05-09T12:00:00.000Z
最小订单  : 10 USDH

边:
    YES : symbol=#20  assetId=20  mid=0.47  liveMid=0.4712
    NO  : symbol=#21  assetId=21  mid=0.53  liveMid=0.5288
```

`market.yes` 和 `market.no` 简写属性允许你直接访问每一侧，而无需遍历 `market.sides`。当你需要币种字符串时（例如，传递给 `l2Book` 或 `bookUpdates`），请使用 `market.yes.symbol`。

### 读取实时订单簿

将YES或NO符号传递给 `sdk.info.l2Book()` 以获取完整的聚合订单簿。每个层级具有 `px`（价格）、`sz`（总大小）和 `n`（现有订单数量）。并行获取两侧可最大程度减少延迟。

3-orderbook-snapshot.ts（关键摘录）

```ts
const [yesBook, noBook] = await Promise.all([\
  sdk.info.l2Book(market.yes.symbol),\
  sdk.info.l2Book(market.no.symbol),\
]);

const yesBids = yesBook.levels[0]; // 按最佳到最差排序
const yesAsks = yesBook.levels[1];

const bestBid = parseFloat(yesBids[0].px);
const bestAsk = parseFloat(yesAsks[0].px);
const spread  = bestAsk - bestBid;
const mid     = (bestBid + bestAsk) / 2;

console.log("价差:", spread.toFixed(5), "中间价:", mid.toFixed(5));

// 隐含概率
const yesMid = parseFloat(market.yes.mid);
const noMid  = parseFloat(market.no.mid);
console.log(`YES: ${(yesMid * 100).toFixed(2)}%  NO: ${(noMid * 100).toFixed(2)}%  Sum: ${((yesMid + noMid) * 100).toFixed(2)}%`);
```

完整源代码：[3-orderbook-snapshot.ts](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets/src/3-orderbook-snapshot.ts)

预期输出（已修剪）：

3-orderbook-snapshot.ts输出

```bash
── #20 (YES) ────────────────────────────────────────────────
最佳买价    : 0.46
最佳卖价    : 0.47
价差      : 0.01000  (2.128%)
中间价（订单簿）: 0.46500
买盘深度   : 1240 单位，跨 5 个层级
卖盘深度   : 980 单位，跨 4 个层级

── 隐含概率 ────────────────────────────────────────────
YES 中间价 : 47.00%
NO  中间价 : 53.00%
总和       : 100.00%  (应约为 100%)

实时 getMid YES: 0.4712
实时 getMid NO : 0.5288
```

提示

YES中间价低于0.50意味着市场当前认为该事件不太可能发生。YES中间价高于0.50意味着可能发生。跟踪两侧：在实时订单簿中，NO中间价并不简单地等于`1 - YES中间价`，因为每一侧都有自己的价差。

### 流式传输实时订单簿更新

对于实时数据，使用 `sdk.stream.bookUpdates()` 在订单簿增量到达时接收它们。并行订阅 `allMids` 以跟踪中间价格，无需轮询。两个订阅都在SDK管理的同一WebSocket连接上运行。

4-stream-orderbook.ts（关键摘录）

```ts
// 流式传输 allMids：过滤 #N 键以跟踪 HIP-4 价格
sdk.stream.allMids((mids) => {
  const hip4 = Object.fromEntries(Object.entries(mids).filter(([k]) => k.startsWith("#")));
  console.log("[allMids] HIP-4:", JSON.stringify(hip4));
});

// 流式传输 YES 侧的订单簿增量
sdk.stream.bookUpdates([market.yes.symbol], (data) => {
  for (const ev of data.block.events) {
    const side   = ev.side === "A" ? "ASK" : "BID";
    const action =
      typeof ev.raw_book_diff === "object" &&
      "new" in (ev.raw_book_diff as object)
        ? "+"
        : typeof ev.raw_book_diff === "object" &&
            "update" in (ev.raw_book_diff as object)
          ? "~"
          : "-";
    console.log(`[bookUpdate] ${action}${side} px=${ev.px} oid=${ev.oid}`);
  }
});

await new Promise((r) => setTimeout(r, 30_000));
sdk.stream.stop();
```

为清晰起见已简化

此代码片段省略了TypeScript类型注解以提高可读性。在实际源代码中，两个回调都接收 `data: Record<string, unknown>` 并使用显式类型转换（例如，`(data as any).block`）来访问嵌套字段。

完整源代码：[4-stream-orderbook.ts](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets/src/4-stream-orderbook.ts)

预期输出（已修剪）：

4-stream-orderbook.ts输出

```bash
[allMids] 流已启动 ✓
[allMids] HIP-4: {"#20":"0.47","#21":"0.53"}
[bookUpdate] +ASK px=0.48  oid=4829301
[bookUpdate] -BID px=0.46  oid=4829105
[allMids] 刻度 #10 | HIP-4: {"#20":"0.4712","#21":"0.5288"}

流汇总
allMids 刻度数     : 28
bookUpdate 增量数 : 14
l2Book 快照数    : 6
最终 HIP-4 中间价  : {"#20":"0.4712","#21":"0.5288"}
```

### 购买 USDH 抵押品

HIP-4 市场需要 USDH（Hyperliquid 的稳定币）作为抵押品。你通过现货市场 `@230` 交换 USDC 来获得它。SDK 通过所需的质押账户（`cStaking`/`cWithdrawal`）自动处理路由。只需调用带有你所需金额的 `buyUsdh()` 即可。

5-buy-usdh.ts（关键摘录）

```ts
// 购买 11 USDH（最小订单为 10 USDH；额外的 1 作为安全缓冲）
const result = await sdk.buyUsdh(11);

console.log("状态    :", result.status);
console.log("是否已成交  :", result.isFilled);
console.log("平均价格  :", result.avgPrice);
console.log("已成交大小:", result.filledSize);
```

完整源代码：[5-buy-usdh.ts](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets/src/5-buy-usdh.ts)

预期输出：

5-buy-usdh.ts输出

```bash
通过现货市场 @230 交换 11 USDC -> USDH...
（SDK 根据 Hyperliquid 要求通过质押账户路由）

=== USDH 兑换结果 ===
状态     : ok
是否已成交   : true
平均价格   : 1.0001
已成交大小 : 11
```

警告

始终购买比你计划交易略多的 USDH。最小订单价值为 10 USDH（`size * price >= 10`），因此精确购买 10 不会留下缓冲。如果在下达订单时收到 `ValidationError`，请首先使用 `sdk.info.spotClearinghouseState(walletAddress)` 检查你的 USDH 余额。

### 下达你的第一笔 HIP-4 交易

SDK 提供 `sdk.buy()` / `sdk.sell()` 用于限价单，以及 `sdk.marketBuy()` / `sdk.marketSell()` 用于市价单。将侧对象（`market.yes` 或 `market.no`）作为第一个参数传递。

HIP-4 大小约束

HIP-4 资产具有 `szDecimals = 0`，意味着大小必须是整数。最小订单名义价值为 10 USDH。使用 `Math.ceil(10 / price)` 找到最小的有效大小。下面的示例在最小值基础上增加了 5 个单位的缓冲。

#### 限价单（GTC）

限价单会留在订单簿上，直到成交或取消。使用 `tif: "gtc"`（Good Till Cancel）。不要在 HIP-4 订单上设置 `priorityFee`。不支持该参数，并且会返回错误。

6-trade.ts（限价单）

```ts
const midPrice  = await sdk.getMid(market.yes);
const buyPrice  = parseFloat((midPrice * 0.97).toFixed(4)); // 比中间价低 3%
const sellPrice = parseFloat((midPrice * 1.03).toFixed(4)); // 比中间价高 3%
const limitSize = Math.ceil(minOrderUSDH / buyPrice) + 5;   // 最小 10 USDH + 缓冲

const limitBuy  = await sdk.buy(market.yes,  { size, price: buyPrice,  tif: "gtc" });
const limitSell = await sdk.sell(market.yes, { size, price: sellPrice, tif: "gtc" });

console.log("BUY  oid:", limitBuy.oid,  "isResting:", limitBuy.isResting);
console.log("SELL oid:", limitSell.oid, "isResting:", limitSell.isResting);

// 完成后取消
if (limitBuy.isResting)  await limitBuy.cancel();
if (limitSell.isResting) await limitSell.cancel();
```

#### 市价单（IOC）

市价单以最佳可用价格立即成交，具有可配置的滑点容忍度（默认为 3%）。大小仍必须满足最坏情况成交价格下 10 USDH 的最小值。

6-trade.ts（市价单）

```ts
const worstCasePx = midPrice * 1.03; // 在买入时考虑 3% 的滑点
const marketSize  = Math.ceil(10 / worstCasePx) + 5;

const marketBuy  = await sdk.marketBuy(market.yes,  { size: marketSize, slippage: 0.03 });
const marketSell = await sdk.marketSell(market.yes, { size: marketSize, slippage: 0.03 });

console.log("市价 BUY  isFilled:", marketBuy.isFilled,  "avgPrice:", marketBuy.avgPrice);
console.log("市价 SELL isFilled:", marketSell.isFilled, "avgPrice:", marketSell.avgPrice);
```

完整源代码：[6-trade.ts](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets/src/6-trade.ts)

预期输出（已修剪）：

6-trade.ts输出

```bash
── 限价 BUY (YES) ──────────────────────────────────────
OID        : 4830012
状态       : resting
isResting  : true
isFilled   : false
isError    : false
价格       : 0.4559
大小       : 27
已成交大小 : null
平均价格   : null

── 市价 BUY (YES) ─────────────────────────────────────
OID        : null
状态       : filled
isResting  : false
isFilled   : true
isError    : false
价格       : 0.47
大小       : 22
已成交大小 : 22
平均价格   : 0.471

限价 BUY  已取消: {"status":"ok"}
限价 SELL 已取消: {"status":"ok"}
```

## 常见错误

请注意以下事项

**没有 USDH 余额。** 如果你没有 USDH，HIP-4 订单会静默失败或返回令人困惑的错误。在下达订单之前，始终执行 USDH 获取步骤，并使用 `sdk.info.spotClearinghouseState(walletAddress)` 确认你的余额。

**订单价值低于 10 USDH。** 每个 HIP-4 订单必须满足 `size * price >= 10`。如果你的价格是 0.05，则至少需要 200 个单位。始终将大小计算为 `Math.ceil(10 / price) + buffer`，而不是硬编码一个数字。

**在 HIP-4 上使用 `priorityFee`。** 结果市场订单不支持 `priorityFee` 参数。传递它会返回 `ValidationError`。

**小数大小。** 所有 HIP-4 资产的 `szDecimals = 0`。像 `10.5` 这样的大小会被拒绝。始终使用 `Math.ceil()` 或 `Math.floor()`。

**构建者费用未批准。** 如果 `sdk.approvalStatus()` 显示 `canTradeSpot: false`，则任何交易都不会成功。首先运行批准步骤。

## 结论

你现在拥有了从原始数据到 HIP-4 预测市场实时交易的完整路径。关键在于 HIP-4 不是一个单独的系统：它使用与其他所有 Hyperliquid 资产相同的 CLOB、相同的 WebSocket 流和相同的成交数据集。`#N` 币种表示法是原始 API 响应中唯一区分结果市场数据的内容。一旦你理解了这种映射，整个 Quicknode Hyperliquid 工具包就可以无需修改地工作。

### 接下来构建什么

既然你已经掌握了基础知识，以下是一些在此基础上构建的想法：

**实时概率提醒机器人。** 将 `sdk.stream.allMids()` 与消息 webhook（Telegram、Discord 或 Slack）结合。实时流式传输 `#N` 中间价格，并在市场的隐含概率超过你定义的阈值时触发通知（对于监控接近到期或在重大新闻事件后的市场非常有用）。

**使用 SQL Explorer 进行到期前行为分析。** 使用 [SQL Explorer](https://www.quicknode.com/sql-explorer) 查询 `hyperliquid_trades WHERE coin LIKE '#%'`，并在结算前几小时测量交易量、成交频率和价格变动。与 `hyperliquid_orders` 结合，以跟踪跨多个市场周期的订单放置模式。

**YES/NO 价差套利扫描器。** 订阅所有活跃 YES/NO 对的 `bookUpdates`。当 `YES 中间价 + NO 中间价` 明显偏离 1.0 时，将该价差标记为潜在的套利机会。加入 `l2Book` 深度数据以在操作前估计成交概率。

**使用 gRPC 的高频市场数据管道。** 对于延迟敏感的策略，Quicknode 的 [gRPC 流式 API](https://www.quicknode.com/docs/hyperliquid#hypercore-apis) 为你提供最低延迟的区块级订单簿和交易数据路径。在服务端解析 `#N` 事件，并以比 WebSocket 轮询更低的开销响应每个区块。

### 资源

- **[Quicknode Hyperliquid 文档中心](https://www.quicknode.com/docs/hyperliquid)**：端点、数据集、流和所有 SDK 选项的完整 API 参考
- **[数据集参考](https://www.quicknode.com/docs/hyperliquid/datasets)**：所有索引的 Hyperliquid 表，包括 `trades`、`orders`、`book-updates`、`l2-book` 和 `l4-book`
- **[HIP-4 规范](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets)**：Hyperliquid 官方预测市场文档
- **[npm 上的 TypeScript SDK](https://www.npmjs.com/package/@quicknode/hyperliquid-sdk)**：包源代码和变更日志
- **[完整指南示例仓库](https://github.com/quiknode-labs/qn-guide-examples/tree/main/hyperliquid/hip4-prediction-markets)**：本指南中的所有 7 个脚本
- **[SQL Explorer 智能机器人指南](https://learnblockchain.cn/article/25149)**：使用纯 SQL 查询 Hyperliquid 数据

## 常见问题

什么是 USDH，为什么我需要它？

USDH 是 Hyperliquid 的稳定币，用作 HIP-4 预测市场的抵押品。你可以通过现货市场 @230 将 USDC 兑换为 USDH。SDK 的 buyUsdh() 方法会自动处理路由。

为什么 YES 中间价 + NO 中间价约等于 1.0？

YES 和 NO 是互补的二元结果：恰好有一个结算为 1，另一个结算为 0。在一个有效的市场中，它们的价格反映了每个结果的隐含概率，这些概率之和必须为 100%。与 1.0 的微小偏差反映了价差和双方之间暂时的套利机会。

我可以在没有 USDH 的情况下交易 HIP-4 市场吗？

不能。USDH 是所有 HIP-4 订单所需的抵押品。尝试在没有足够 USDH 余额的情况下下达订单将导致错误。首先运行 sdk.buyUsdh()，并使用 sdk.info.spotClearinghouseState(walletAddress) 验证你的余额。

为什么 HIP-4 订单大小必须是整数？

Hyperliquid 上的 HIP-4 资产的 szDecimals = 0，意味着交易所只接受整数数量。如果你传递像 10.5 这样的小数大小，订单将被拒绝。始终使用 Math.ceil() 计算最小有效大小：Math.ceil(10 / price)。

API 响应中像 \`#20\` 这样的币种是什么意思？

#N 表示法标识一个 HIP-4 结果市场侧。数字 N 从资产 ID 派生而来，使用 N = 10 \* outcomeIndex + sideIndex，其中 outcomeIndex 标识结果，sideIndex 标识交易侧。SDK 抽象了这一点：sdk.predictionMarkets() 返回已解析的 market.yes.symbol 和 market.no.symbol。当你直接读取 allMids、trades、orders 或 book-updates 数据集响应时，会遇到原始的 #N 值。

#### 我们 ❤️ 反馈！

如果你有任何反馈或新主题请求，[请告诉我们](https://airtable.com/shrKKKP7O1Uw3ZcUB?prefill_Guide+Name=How%20to%20Trade%20HIP-4%20Prediction%20Markets%20on%20Hyperliquid)。我们很乐意听取你的意见。

>- 原文链接： [quicknode.com/guides/hyp...](https://www.quicknode.com/guides/hyperliquid/trade-hip-4-prediction-markets-on-hyperliquid)
>- 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～

概述

HIP-4 于2026年5月2日在Hyperliquid主网上线，引入了完全抵押的二元结果市场，这些市场以USDH结算为0或1。这些市场与永续合约和现货一起存在于HyperCore中，共享相同的CLOB基础设施、相同的WebSocket流以及你用于其他所有Hyperliquid资产的相同数据端点。本指南首先带你了解数据模型，然后逐步引导你发现市场、读取和流式传输订单簿、获取USDH，并使用Quicknode Hyperliquid TypeScript SDK进行交易。

TL;DR

HIP-4市场是二元YES/NO合约，以USDH结算为0或1，在HyperCore CLOB上交易，开仓费为零
每一方在allMids、数据集以及所有流式API中都显示为#N币种（例如，YES为#20，NO为#21）
Quicknode为TypeScript、Python、Go和Rust构建并维护SDK，以及托管的REST API参考和gRPC流式端点
本指南的完整源代码位于 qn-guide-examples
SQL Explorer 允许你使用纯SQL查询历史HIP-4交易和订单

你将做什么

理解HIP-4数据模型：#N币种表示法、outcomeMeta、allMids以及交易/订单/簿更新数据集
设置Quicknode Hyperliquid端点并初始化TypeScript SDK
批准构建者费用（每个钱包一次）
发现活跃的预测市场并检查YES/NO侧的形状
实时读取和流式传输双方的订单簿
通过现货市场交换USDC来获取USDH
下达限价单和市价单，取消现有订单，并处理常见错误

你需要什么

一个Quicknode账户并配有Hyperliquid端点
Node.js 20+ 和一个包管理器（npm、pnpm或yarn）
一个Hyperliquid钱包私钥以及至少一些USDC在你的现货余额中（用于USDH兑换步骤）
熟悉TypeScript和基本预测市场概念

什么是HIP-4结果市场？

HIP-4市场运行条件：

链上且无需许可。 直接在Hyperliquid L1上结算，无需桥接或托管方。
开仓费为零。 与永续合约和现货不同，HIP-4对开仓不收取任何费用（构建者费用仍然适用）。
与所有其他资产在同一个CLOB上。 相同的L2订单簿端点、WebSocket流和成交数据集涵盖了HIP-4以及其他所有资产。如果你已经查询Hyperliquid数据，基本上已经完成了大部分工作。

Quicknode Hyperliquid开发者工具包

在编写任何代码之前，值得了解Quicknode为Hyperliquid提供了什么，以便你为要构建的内容选择合适的工具。

工具	提供的内容	链接
Hyperliquid SDK（TypeScript、Python、Go、Rust）	完整的交易和数据SDK：订单、流、账户状态	Hyperliquid SDK
数据集	通过gRPC和JSON-RPC/WebSocket API包含不同类型区块链和交易所事件的数据流，例如`trades`、`orders`和`book-updates`	文档
WebSocket / JSON-RPC API	实时订阅（`bookUpdates`、`allMids`、`trades`）和状态查询	文档
gRPC流式传输	最低延迟的区块级订单簿和交易数据路径，适合高频策略	文档
信息端点	快照查询：`outcomeMeta`、`allMids`、`l2Book`、`clearinghouseState`	文档
REST API (hyperliquidapi.com)	由Quicknode构建的Hyperliquid零托管REST构建者API	hyperliquidapi.com
SQL Explorer	对索引表的历史查询：`hyperliquid_trades`、`hyperliquid_orders`以及35个以上其他表	sql-explorer

本指南全程使用Hyperliquid SDK for TypeScript。它允许你通过单一统一接口访问所有数据API并进行交易。

数据模型

SDK使得处理HIP-4市场变得容易，但理解底层数据模型很重要。HIP-4数据通过与其他Hyperliquid资产相同的API和数据集流动。唯一区分元素是#N币种表示法。本节涵盖在编写任何代码之前你需要知道的三件事。

市场身份与发现

每个HIP-4结果侧由一个以#为前缀的币种字符串标识，例如#20（YES）和#21（NO）。这将结果市场币种与永续合约（无前缀）和现货代币（@N或xyz:前缀）区分开来。整数N从资产的数字ID派生而来，编码方式为N = 10 * outcomeIndex + sideIndex。 Hyperliquid资产ID规范涵盖了完整的映射。

两个端点为你提供任何活跃市场的完整画面：

outcomeMeta 返回市场定义：

outcomeMeta响应

{
  "outcomes": [\
    {\
      "outcome": 3,\
      "name": "Recurring",\
      "description": "class:priceBinary|underlying:BTC|expiry:20260506-0600|targetPrice:80930|period:1d",\
      "sideSpecs": [\
        { "name": "Yes" },\
        { "name": "No" }\
      ]\
    }\
  ],
  "questions": []
}

字段	描述
`outcomes[].outcome`	标识市场实例的递增整数
`outcomes[].name`	市场类型标签（例如，`"Recurring"`）
`outcomes[].description`	管道分隔的键值对：`class`、`underlying`、`expiry`（格式`YYYYMMDD-HHMM`）、`targetPrice`、`period`
`outcomes[].sideSpecs`	每侧一个条目的数组。`sideSpecs[0]`是YES，`sideSpecs[1]`是NO
`questions`	保留给非二元市场类型，对价格二元市场为空

allMids 返回交易所上每种资产的实时中间价格。HIP-4市场以#N键的形式出现，与常规永续和现货代码并列：

allMids响应（摘录）

{
  "BTC": "96423.0",
  "ETH": "1823.5",
  "#20": "0.47",
  "#21": "0.53"
}

过滤以#开头的键以隔离结果市场中间价。sdk.stream.allMids()以连续实时流的形式提供相同数据。

数据中的活动表现

当订单被下达且交易被撮合时，Quicknode Hyperliquid数据集会以#N标识符捕获活动：

trades: 每个交易行使用coin: "#N"。feeToken字段使用+N表示法（例如，+20），并且fee始终为"0.0"，因为HIP-4开仓订单不收取费用。

orders: 订单记录使用相同的coin: "#N"表示法。结果交易的双边都作为买单出现（side: "B"）。

book-updates: 每个事件包含一个raw_book_diff字段：{"new": {"sz": "..."}}（新订单下达）、"remove"（订单取消或成交）或{"update": {"origSz": "...", "newSz": "..."}}（原地尺寸修改，仅限HIP-4）。使用这些来维护本地订单簿副本。

l2-book 和 l4-book: 可按币种查询的聚合和原始订单簿快照。传递"#N"作为币种过滤器以检索特定结果侧的数据。

读取价格：隐含概率

因为YES和NO是互补结果，它们的中间价格之和约为1.0：

YES 中间价 + NO 中间价 ≈ 1.0

YES中间价为0.47意味着市场隐含该事件发生的概率为47%。NO中间价为0.53隐含53%。与1.0的微小偏差反映了价差以及双方之间任何暂时的套利机会。

SDK抽象了大部分内容：sdk.predictionMarkets()会为你解析#N符号，通过正确的质押账户路由USDH兑换，并处理API响应的类型转换。当你直接读取原始allMids、数据集记录或gRPC事件时，上述结构才重要。有了这个基础，本指南的其余部分将进行实际操作。

使用Quicknode交易HIP-4市场

获取示例代码

克隆并安装

git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/hyperliquid/hip4-prediction-markets
npm install
cp .env.example .env

在.env中填写你的端点、私钥和钱包地址（在下面的设置你的Quicknode端点中介绍），然后构建并运行任何脚本：

构建并运行

npm run build
node --env-file=.env dist/0-approve.js

每个脚本都是独立的：

脚本	涵盖内容
`0-approve.ts`	一次性构建者费用批准
`1-setup.ts`	健康检查：端点、活跃市场、账户状态
`2-list-markets.ts`	发现活跃市场并检查完整的`PredictionMarket`形状
`3-orderbook-snapshot.ts`	获取YES和NO的L2订单簿，计算隐含概率
`4-stream-orderbook.ts`	订阅实时`bookUpdates`和`allMids` WebSocket流
`5-buy-usdh.ts`	通过现货市场`@230`将USDC兑换为USDH
`6-trade.ts`	限价单和市价单、取消操作，并检查`PlacedOrder`形状

设置你的Quicknode端点

登录你的Quicknode仪表板。
创建一个新端点，并选择 Hyperliquid 作为链。
复制HyperCore HTTPS端点URL，并移除/hypercore后缀。
在你的项目根目录中创建一个.env文件：

.env

QUICKNODE_ENDPOINT=https://your-endpoint.hype-mainnet.quiknode.pro/your-api-key/
PRIVATE_KEY=your_wallet_private_key_hex
WALLET_ADDRESS=your_wallet_address
USDH_AMOUNT=11

在任何shell脚本或cURL示例中，将你的端点作为一个变量保存：TEST_RPC=$QUICKNODE_ENDPOINT

警告

切勿将.env提交到版本控制。将其添加到.gitignore中。PRIVATE_KEY字段会提供对你钱包的完全控制。

初始化SDK

安装Quicknode Hyperliquid TypeScript SDK：

安装

npm install @quicknode/hyperliquid-sdk

使用不同的语言？

本指南使用TypeScript SDK。Quicknode还维护Python、Go和Rust的SDK（所有都具有相同的核心原语）。你可以在Quicknode Hyperliquid文档中心找到所有SDK的链接。如果你更喜欢原始HTTP，REST API参考涵盖了本指南中使用的每个端点。

使用你的端点和签名凭证初始化SDK。autoApprove: true标志会在第一次交易时自动处理构建者费用批准，而maxFee: "1%"设置了你的钱包将接受的最大费率：

SDK初始化

import { HyperliquidSDK } from "@quicknode/hyperliquid-sdk";

const sdk = new HyperliquidSDK(process.env.QUICKNODE_ENDPOINT, {
  privateKey: process.env.PRIVATE_KEY,
  autoApprove: true,
  maxFee: "1%",
});

构建者费用

构建者代码是一种Hyperliquid原生机制，允许基础设施提供商在交易所费用之上收取费用。你一次批准最高费率，实际收费始终等于或低于该费率。

批准构建者费用

在你的钱包可以交易之前，必须批准构建者费用。这是每个钱包的一次性链上操作。使用autoApprove: true，SDK会在你第一次交易时处理此操作，但显式运行它可以显示批准前后的状态，并确认一切就绪。

0-approve.ts（关键摘录）

// 1. 检查当前状态
const before = await sdk.approvalStatus() as any;

// 2. 批准
console.log(`\n批准构建者费用 (maxFee: ${MAX_FEE})...`);
const result = await sdk.approveBuilderFee(MAX_FEE) as any;

// 3. 验证
const after = await sdk.approvalStatus() as any;

完整源代码：0-approve.ts

预期输出（首次运行）：

0-approve.ts输出

============================================================
构建者费用批准
============================================================

── 当前状态 ──────────────────────────────────────────
approved     : true
maxFeeRate   : 0%
canTradePerps: false
canTradeSpot : false
status msg   : 你的批准低于最低费用。请以更高的maxFeeRate重新批准。

批准构建者费用 (maxFee: 1%)...

── 批准结果 ──────────────────────────────────────────
{
  "status": "ok",
  "response": { "type": "default" }
}

── 批准后状态 ────────────────────────────────────────
approved     : true
maxFeeRate   : 1%
canTradePerps: true
canTradeSpot : true
status msg   : 你可以交易永续合约和现货。

批准成功。你现在可以交易永续合约、现货和HIP-4市场。

验证你的连接和活跃市场

在下达任何订单之前，请确认你的端点可达、HIP-4市场活跃，并且构建者费用批准已到位。

1-setup.ts（关键摘录）

const markets = await sdk.predictionMarkets();
console.log("活跃的HIP-4市场数量:", markets.length);

for (const m of markets) {
  console.log(`  ${m.title}`);
  console.log(`  YES: ${m.yes.symbol} (assetId: ${m.yes.assetId}) | mid: ${m.yes.mid}`);
  console.log(`   NO: ${m.no.symbol}  (assetId: ${m.no.assetId}) | mid: ${m.no.mid}`);
}

// ── 所有中间价格（过滤 HIP-4 # 资产）───────────────────
const allMids = await sdk.info.allMids() as any;
const hip4Mids = Object.entries(allMids).filter(([k]) => k.startsWith("#"));

const approval = await sdk.approvalStatus();
console.log("canTradePerps:", approval.canTradePerps);
console.log("canTradeSpot :", approval.canTradeSpot);

完整源代码：1-setup.ts

预期输出（已修剪）：

1-setup.ts输出

── HIP-4 预测市场 ────────────────────────────────────
活跃市场数量   : 1

  标题     : BTC 高于 79980 (05/09 12:00 UTC)
  到期时间 : 2026-05-09T12:00:00.000Z
  抵押品   : USDH
  最小订单 : 10 USDH
  YES       : #20 (assetId: 20) | mid: 0.47
  NO        : #21 (assetId: 21) | mid: 0.53

── HIP-4 中间价格（来自 allMids）──────────────────────
  #20   : 0.47
  #21   : 0.53

── 构建者费用批准 ────────────────────────────────────
canTradePerps: true
canTradeSpot : true
✓  构建者费用已批准。准备就绪。

浏览活跃预测市场

sdk.predictionMarkets() 返回每个活跃HIP-4市场的完整 PredictionMarket 形状，包括实时中间价格、outcomeMeta 中使用的管道分隔描述以及双边对象。

2-list-markets.ts（关键摘录）

import { HyperliquidSDK, type PredictionMarket } from "@quicknode/hyperliquid-sdk";

const markets = await sdk.predictionMarkets();

for (const market of markets as PredictionMarket[]) {
  console.log("标题      :", market.title);
  console.log("描述      :", market.description);
  console.log("标的资产  :", market.underlying);
  console.log("目标价格  :", market.targetPrice);
  console.log("到期时间  :", market.expiry);
  console.log("最小订单  :", market.minOrderValue, "USDH");

  for (const side of market.sides) {
    const liveMid = await sdk.getMid(side);
    console.log(`  ${side.name}: symbol=${side.symbol}  assetId=${side.assetId}  mid=${side.mid}  liveMid=${liveMid}`);
  }
}

完整源代码：2-list-markets.ts

预期输出（已修剪）：

2-list-markets.ts输出

────────────────────────────────────────────────────────────
标题      : BTC 高于 79980 (05/09 12:00 UTC)
描述      : Will BTC be above 79980|USD|2026-05-09T12:00:00.000Z
简短标识  : btc-above-79980-0509-1200-utc
标的资产  : BTC
目标价格  : 79980
到期时间  : 2026-05-09T12:00:00.000Z
最小订单  : 10 USDH

  边:
    YES : symbol=#20  assetId=20  mid=0.47  liveMid=0.4712
    NO  : symbol=#21  assetId=21  mid=0.53  liveMid=0.5288

market.yes 和 market.no 简写属性允许你直接访问每一侧，而无需遍历 market.sides。当你需要币种字符串时（例如，传递给 l2Book 或 bookUpdates），请使用 market.yes.symbol。

读取实时订单簿

将YES或NO符号传递给 sdk.info.l2Book() 以获取完整的聚合订单簿。每个层级具有 px（价格）、sz（总大小）和 n（现有订单数量）。并行获取两侧可最大程度减少延迟。

3-orderbook-snapshot.ts（关键摘录）

const [yesBook, noBook] = await Promise.all([\
  sdk.info.l2Book(market.yes.symbol),\
  sdk.info.l2Book(market.no.symbol),\
]);

const yesBids = yesBook.levels[0]; // 按最佳到最差排序
const yesAsks = yesBook.levels[1];

const bestBid = parseFloat(yesBids[0].px);
const bestAsk = parseFloat(yesAsks[0].px);
const spread  = bestAsk - bestBid;
const mid     = (bestBid + bestAsk) / 2;

console.log("价差:", spread.toFixed(5), "中间价:", mid.toFixed(5));

// 隐含概率
const yesMid = parseFloat(market.yes.mid);
const noMid  = parseFloat(market.no.mid);
console.log(`YES: ${(yesMid * 100).toFixed(2)}%  NO: ${(noMid * 100).toFixed(2)}%  Sum: ${((yesMid + noMid) * 100).toFixed(2)}%`);

完整源代码：3-orderbook-snapshot.ts

预期输出（已修剪）：

3-orderbook-snapshot.ts输出

── #20 (YES) ────────────────────────────────────────────────
最佳买价    : 0.46
最佳卖价    : 0.47
价差      : 0.01000  (2.128%)
中间价（订单簿）: 0.46500
买盘深度   : 1240 单位，跨 5 个层级
卖盘深度   : 980 单位，跨 4 个层级

── 隐含概率 ────────────────────────────────────────────
YES 中间价 : 47.00%
NO  中间价 : 53.00%
总和       : 100.00%  (应约为 100%)

实时 getMid YES: 0.4712
实时 getMid NO : 0.5288

提示

YES中间价低于0.50意味着市场当前认为该事件不太可能发生。YES中间价高于0.50意味着可能发生。跟踪两侧：在实时订单簿中，NO中间价并不简单地等于1 - YES中间价，因为每一侧都有自己的价差。

流式传输实时订单簿更新

对于实时数据，使用 sdk.stream.bookUpdates() 在订单簿增量到达时接收它们。并行订阅 allMids 以跟踪中间价格，无需轮询。两个订阅都在SDK管理的同一WebSocket连接上运行。

4-stream-orderbook.ts（关键摘录）

// 流式传输 allMids：过滤 #N 键以跟踪 HIP-4 价格
sdk.stream.allMids((mids) => {
  const hip4 = Object.fromEntries(Object.entries(mids).filter(([k]) => k.startsWith("#")));
  console.log("[allMids] HIP-4:", JSON.stringify(hip4));
});

// 流式传输 YES 侧的订单簿增量
sdk.stream.bookUpdates([market.yes.symbol], (data) => {
  for (const ev of data.block.events) {
    const side   = ev.side === "A" ? "ASK" : "BID";
    const action =
      typeof ev.raw_book_diff === "object" &&
      "new" in (ev.raw_book_diff as object)
        ? "+"
        : typeof ev.raw_book_diff === "object" &&
            "update" in (ev.raw_book_diff as object)
          ? "~"
          : "-";
    console.log(`[bookUpdate] ${action}${side} px=${ev.px} oid=${ev.oid}`);
  }
});

await new Promise((r) => setTimeout(r, 30_000));
sdk.stream.stop();

为清晰起见已简化

此代码片段省略了TypeScript类型注解以提高可读性。在实际源代码中，两个回调都接收 data: Record<string, unknown> 并使用显式类型转换（例如，(data as any).block）来访问嵌套字段。

完整源代码：4-stream-orderbook.ts

预期输出（已修剪）：

4-stream-orderbook.ts输出

[allMids] 流已启动 ✓
[allMids] HIP-4: {"#20":"0.47","#21":"0.53"}
[bookUpdate] +ASK px=0.48  oid=4829301
[bookUpdate] -BID px=0.46  oid=4829105
[allMids] 刻度 #10 | HIP-4: {"#20":"0.4712","#21":"0.5288"}

流汇总
allMids 刻度数     : 28
bookUpdate 增量数 : 14
l2Book 快照数    : 6
最终 HIP-4 中间价  : {"#20":"0.4712","#21":"0.5288"}

购买 USDH 抵押品

HIP-4 市场需要 USDH（Hyperliquid 的稳定币）作为抵押品。你通过现货市场 @230 交换 USDC 来获得它。SDK 通过所需的质押账户（cStaking/cWithdrawal）自动处理路由。只需调用带有你所需金额的 buyUsdh() 即可。

5-buy-usdh.ts（关键摘录）

// 购买 11 USDH（最小订单为 10 USDH；额外的 1 作为安全缓冲）
const result = await sdk.buyUsdh(11);

console.log("状态    :", result.status);
console.log("是否已成交  :", result.isFilled);
console.log("平均价格  :", result.avgPrice);
console.log("已成交大小:", result.filledSize);

完整源代码：5-buy-usdh.ts

预期输出：

5-buy-usdh.ts输出

通过现货市场 @230 交换 11 USDC -> USDH...
（SDK 根据 Hyperliquid 要求通过质押账户路由）

=== USDH 兑换结果 ===
状态     : ok
是否已成交   : true
平均价格   : 1.0001
已成交大小 : 11

警告

始终购买比你计划交易略多的 USDH。最小订单价值为 10 USDH（size * price >= 10），因此精确购买 10 不会留下缓冲。如果在下达订单时收到 ValidationError，请首先使用 sdk.info.spotClearinghouseState(walletAddress) 检查你的 USDH 余额。

下达你的第一笔 HIP-4 交易

SDK 提供 sdk.buy() / sdk.sell() 用于限价单，以及 sdk.marketBuy() / sdk.marketSell() 用于市价单。将侧对象（market.yes 或 market.no）作为第一个参数传递。

HIP-4 大小约束

HIP-4 资产具有 szDecimals = 0，意味着大小必须是整数。最小订单名义价值为 10 USDH。使用 Math.ceil(10 / price) 找到最小的有效大小。下面的示例在最小值基础上增加了 5 个单位的缓冲。

限价单（GTC）

限价单会留在订单簿上，直到成交或取消。使用 tif: "gtc"（Good Till Cancel）。不要在 HIP-4 订单上设置 priorityFee。不支持该参数，并且会返回错误。

6-trade.ts（限价单）

const midPrice  = await sdk.getMid(market.yes);
const buyPrice  = parseFloat((midPrice * 0.97).toFixed(4)); // 比中间价低 3%
const sellPrice = parseFloat((midPrice * 1.03).toFixed(4)); // 比中间价高 3%
const limitSize = Math.ceil(minOrderUSDH / buyPrice) + 5;   // 最小 10 USDH + 缓冲

const limitBuy  = await sdk.buy(market.yes,  { size, price: buyPrice,  tif: "gtc" });
const limitSell = await sdk.sell(market.yes, { size, price: sellPrice, tif: "gtc" });

console.log("BUY  oid:", limitBuy.oid,  "isResting:", limitBuy.isResting);
console.log("SELL oid:", limitSell.oid, "isResting:", limitSell.isResting);

// 完成后取消
if (limitBuy.isResting)  await limitBuy.cancel();
if (limitSell.isResting) await limitSell.cancel();

市价单（IOC）

市价单以最佳可用价格立即成交，具有可配置的滑点容忍度（默认为 3%）。大小仍必须满足最坏情况成交价格下 10 USDH 的最小值。

6-trade.ts（市价单）

const worstCasePx = midPrice * 1.03; // 在买入时考虑 3% 的滑点
const marketSize  = Math.ceil(10 / worstCasePx) + 5;

const marketBuy  = await sdk.marketBuy(market.yes,  { size: marketSize, slippage: 0.03 });
const marketSell = await sdk.marketSell(market.yes, { size: marketSize, slippage: 0.03 });

console.log("市价 BUY  isFilled:", marketBuy.isFilled,  "avgPrice:", marketBuy.avgPrice);
console.log("市价 SELL isFilled:", marketSell.isFilled, "avgPrice:", marketSell.avgPrice);

完整源代码：6-trade.ts

预期输出（已修剪）：

6-trade.ts输出

── 限价 BUY (YES) ──────────────────────────────────────
OID        : 4830012
状态       : resting
isResting  : true
isFilled   : false
isError    : false
价格       : 0.4559
大小       : 27
已成交大小 : null
平均价格   : null

── 市价 BUY (YES) ─────────────────────────────────────
OID        : null
状态       : filled
isResting  : false
isFilled   : true
isError    : false
价格       : 0.47
大小       : 22
已成交大小 : 22
平均价格   : 0.471

限价 BUY  已取消: {"status":"ok"}
限价 SELL 已取消: {"status":"ok"}

常见错误

请注意以下事项

没有 USDH 余额。 如果你没有 USDH，HIP-4 订单会静默失败或返回令人困惑的错误。在下达订单之前，始终执行 USDH 获取步骤，并使用 sdk.info.spotClearinghouseState(walletAddress) 确认你的余额。

订单价值低于 10 USDH。 每个 HIP-4 订单必须满足 size * price >= 10。如果你的价格是 0.05，则至少需要 200 个单位。始终将大小计算为 Math.ceil(10 / price) + buffer，而不是硬编码一个数字。

在 HIP-4 上使用 priorityFee。 结果市场订单不支持 priorityFee 参数。传递它会返回 ValidationError。

小数大小。 所有 HIP-4 资产的 szDecimals = 0。像 10.5 这样的大小会被拒绝。始终使用 Math.ceil() 或 Math.floor()。

构建者费用未批准。 如果 sdk.approvalStatus() 显示 canTradeSpot: false，则任何交易都不会成功。首先运行批准步骤。

结论

你现在拥有了从原始数据到 HIP-4 预测市场实时交易的完整路径。关键在于 HIP-4 不是一个单独的系统：它使用与其他所有 Hyperliquid 资产相同的 CLOB、相同的 WebSocket 流和相同的成交数据集。#N 币种表示法是原始 API 响应中唯一区分结果市场数据的内容。一旦你理解了这种映射，整个 Quicknode Hyperliquid 工具包就可以无需修改地工作。

接下来构建什么

既然你已经掌握了基础知识，以下是一些在此基础上构建的想法：

实时概率提醒机器人。 将 sdk.stream.allMids() 与消息 webhook（Telegram、Discord 或 Slack）结合。实时流式传输 #N 中间价格，并在市场的隐含概率超过你定义的阈值时触发通知（对于监控接近到期或在重大新闻事件后的市场非常有用）。

使用 SQL Explorer 进行到期前行为分析。 使用 SQL Explorer 查询 hyperliquid_trades WHERE coin LIKE '#%'，并在结算前几小时测量交易量、成交频率和价格变动。与 hyperliquid_orders 结合，以跟踪跨多个市场周期的订单放置模式。

YES/NO 价差套利扫描器。 订阅所有活跃 YES/NO 对的 bookUpdates。当 YES 中间价 + NO 中间价 明显偏离 1.0 时，将该价差标记为潜在的套利机会。加入 l2Book 深度数据以在操作前估计成交概率。

使用 gRPC 的高频市场数据管道。 对于延迟敏感的策略，Quicknode 的 gRPC 流式 API 为你提供最低延迟的区块级订单簿和交易数据路径。在服务端解析 #N 事件，并以比 WebSocket 轮询更低的开销响应每个区块。

资源

Quicknode Hyperliquid 文档中心：端点、数据集、流和所有 SDK 选项的完整 API 参考
数据集参考：所有索引的 Hyperliquid 表，包括 trades、orders、book-updates、l2-book 和 l4-book
HIP-4 规范：Hyperliquid 官方预测市场文档
npm 上的 TypeScript SDK：包源代码和变更日志
完整指南示例仓库：本指南中的所有 7 个脚本
SQL Explorer 智能机器人指南：使用纯 SQL 查询 Hyperliquid 数据

常见问题

什么是 USDH，为什么我需要它？

USDH 是 Hyperliquid 的稳定币，用作 HIP-4 预测市场的抵押品。你可以通过现货市场 @230 将 USDC 兑换为 USDH。SDK 的 buyUsdh() 方法会自动处理路由。

为什么 YES 中间价 + NO 中间价约等于 1.0？

我可以在没有 USDH 的情况下交易 HIP-4 市场吗？

为什么 HIP-4 订单大小必须是整数？

API 响应中像 `#20` 这样的币种是什么意思？

#N 表示法标识一个 HIP-4 结果市场侧。数字 N 从资产 ID 派生而来，使用 N = 10 * outcomeIndex + sideIndex，其中 outcomeIndex 标识结果，sideIndex 标识交易侧。SDK 抽象了这一点：sdk.predictionMarkets() 返回已解析的 market.yes.symbol 和 market.no.symbol。当你直接读取 allMids、trades、orders 或 book-updates 数据集响应时，会遇到原始的 #N 值。

我们 ❤️ 反馈！

如果你有任何反馈或新主题请求，请告诉我们。我们很乐意听取你的意见。

原文链接： quicknode.com/guides/hyp...

登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～

概述

你将做什么

你需要什么

什么是HIP-4结果市场？

Quicknode Hyperliquid开发者工具包

数据模型

市场身份与发现

数据中的活动表现

读取价格：隐含概率

使用Quicknode交易HIP-4市场

获取示例代码

设置你的Quicknode端点

初始化SDK

批准构建者费用

验证你的连接和活跃市场

浏览活跃预测市场

读取实时订单簿

流式传输实时订单簿更新

购买 USDH 抵押品

下达你的第一笔 HIP-4 交易

限价单（GTC）

市价单（IOC）

常见错误

结论

接下来构建什么

资源

常见问题

我们 ❤️ 反馈！

相关文章

0 条评论