跳至主要內容

使用 gRPC 監控 Hyperliquid 的 TP/SL 觸發訂單

更新於
2026年6月24日
塞爾根·烏伊薩爾 個人簡介
塞爾根·烏伊薩爾
全部
超液態
HyperCore
DeFi
交易
gRPC
TypeScript
Node.js

閱讀時間 7 分鐘

概覽​

獲利了結與止損訂單如同隱形的觸發機制，分別位於當前價格的上方與下方。當價格觸及觸發價位時，訂單便會執行，而隨著密集的止損單接連觸發，市場往往會出現劇烈波動。Quicknode 的StreamTpslUpdatesgRPC 資料流，讓您能即時掌握這些觸發訂單的下單與撤銷狀況，而這類資料在公開的 Hyperliquid 端點上並無對應資料。

在本指南中，您將訂閱 StreamTpslUpdates, 了解 ADD 以及 移除 diff 模型，並了解這些概念如何驅動 Hyperliquid TP/SL 熱力圖 範例應用程式。


簡而言之
  • 連線至 Quicknode 的 Hyperliquid gRPC 端點，並訂閱 StreamTpslUpdates
  • 接收以區塊為單位的批次，其中包含兩種差異類型： TPSL_DIFF_TYPE_ADD （新的靜止觸發順序）以及 TPSL_DIFF_TYPE_REMOVE （已下單購買該書）
  • 該 理由 REMOVE 差異中的欄位說明了原因：已填寫、已取消、僅取消等。
  • 沒有獨立的 TRIGGER 事件；觸發的停用會以 REMOVE 差異的形式顯示

您將學到什麼​

  • 為何 TP/SL 觸發訂單在公開的 Hyperliquid 端點上沒有對應功能
  • 每區塊批次模型： TpslUpdatesUpdate 將 a 包裹起來 差異 陣列和一個 快照 bool
  • 每個 TpslOrderDiff 該欄位包含的內容，包括 理由 以及 訂單類型 作為一個普通字串
  • 這兩種差異類型（ADD 和 REMOVE）以及它們的 理由 在執行「移除」時會通知您
  • 本指南中的流概念如何對應至Hyperliquid TP/SL 熱力圖範例應用程式

您需要準備的物品​

StreamTpslUpdates 提供哪些功能​

StreamTpslUpdates 是一個 Quicknode gRPC 串流，用於在 Hyperliquid 上傳送按區塊分批的靜態止損與獲利了結觸發訂單，包括新訂單（TPSL_DIFF_TYPE_ADD) 以及已取消的訂單 (TPSL_DIFF_TYPE_REMOVE). Hyperliquid 的公開 REST 和 WebSocket API 並未公開這些條件單；這些單子會隱藏在可見的買賣盤之外，直到價格達到觸發水準為止，使得 StreamTpslUpdates 唯一的即時資訊來源。

以下是幾塊流式輸出的樣貌：

[ADD]    oid=477397908047 coin=BTC  市價止損賣單         trigger_px=40021.0  sz=0.00429
[新增]    oid=477397923750 coin=ETH  市價止損賣單         trigger_px=1150.3   sz=0.6939
[新增]    oid=477397931759 coin=ETH  市價止損賣單         觸發價格=1106.7   數量=0.1753
[REMOVE] oid=477390148344 coin=ETH  止盈市價賣單  trigger_px=1754.0   sz=0.0301   reason=已取消
[移除] oid=477397616600 coin=BTC  限價市場賣單         觸發價格=40029.0   數量=0.00429   原因=已取消
[新增]    oid=477397938673 coin=BTC  市價止損賣單         trigger_px=50758.0  sz=0.01118

每個串流事件都是一個 TpslUpdatesUpdate：一個以區塊為單位的批次，用來封裝一個 差異 陣列和一個 快照 bool。當 快照 是 true, 第一批包含所有目前處於開啟狀態的觸發訂單。後續批次則為增量處理。

有兩種 diff 類型。 TPSL_DIFF_TYPE_ADD 表示有新的觸發指令進入了靜止集。 TPSL_DIFF_TYPE_REMOVE 表示它離開了；該 理由 「field」會告訴你原因： "填滿" 意指該停火令已發布並執行， 「取消」 或 "reduceOnlyCanceled" 表示該項目在未執行前即已被移除。此處沒有獨立的觸發器事件：觸發的停止操作即為一項「移除」操作，其中 理由：「已填寫」.

實務上最重要的領域：

領域註釋
oid唯一的訂單編號；用於關聯同一筆訂單的「新增」與「移除」操作
trigger_px觸發訂單的價格水準
sz訂單數量。 "0.0" 意指根據倉位規模設定的獲利了結點／止損點（實際規模須待觸發後方知）
訂單類型普通字串： 「獲利了結上限」, 「止損」, 「獲利了結市價單」, 「止損市場」
理由在 REMOVE 上呈現： "填滿", 「取消」, "reduceOnlyCanceled"，等等。
側面「B」 (買入觸發條件) 或 「A」 (賣出觸發條件)

訂單類型 這不是一個枚舉；請使用字串比對來區分 TP 與 SL：

const isTakeProfit = diff.訂單類型.toLowerCase().包含(「獲利了結」);

有關完整的欄位參考資訊，請參閱StreamTpslUpdates 資料集的文件。

設定​

安裝所需的套件：

npm install @grpc/grpc-js @grpc/proto-loader dotenv
npm install --save-dev typescript @types/node ts-node

建立 .env 在專案根目錄下：

# 主網：your-endpoint-id.hype-mainnet.quiknode.pro:10000
# 測試網：您的端點 ID.hype-testnet.quiknode.pro:10000
QUICKNODE_GRPC_ENDPOINT=您的端點 ID.hype-mainnet.quiknode.pro:10000
QUICKNODE_GRPC_TOKEN=您的-代幣-在此

下載 Hyperliquid 的 proto 檔案：

mkdir -p proto
curl -o proto/orderbook.proto \
  https://raw.githubusercontent.com/quiknode-labs/hypercore-grpc-examples/main/proto/orderbook.proto

有關 gRPC 客戶端設定的完整操作指南，請參閱《Node.js 訂單簿設定指南》。

如需完整的程式碼範例，請參閱StreamTpslUpdates gRPC 方法的文件，或Hyperliquid TP/SL 熱力圖範例應用程式。

連線與訂閱​

以下程式碼片段使用了一個 createClient 用於設定 gRPC 通道與認證元資料的輔助程式。請依照以下步驟進行編譯： Node.js gRPC 客戶端設定指南, 然後將結果儲存為 client.ts 位於您的專案根目錄中。

import { createClient } from './client';

const COINS = ['BTC', 'ETH'];
const { client, metadata } = createClient();

const stream = client.StreamTpslUpdates({ coins: COINS }, metadata);

跳過 硬幣：[] 以接收所有幣種的觸發訂單。

解析資料流​

每個 資料 事件是按區塊為單位的批次處理。迭代 update.diffs 並根據類型處理每個差異：

stream.on('data', (update: any) => {
  if (update.snapshot) {
    console.log(`Snapshot: ${update.diffs.length} open trigger orders`);
  }

  for (const diff of update.diffs) {
    const side = diff.side === 'B' ? 'buy' : 'sell';
    if (diff.diff_type === 'TPSL_DIFF_TYPE_ADD') {
      console.log(`New ${diff.order_type} ${side} trigger: px=${diff.trigger_px} sz=${diff.sz}`);
    } else {
      console.log(`Removed oid=${diff.oid} at ${diff.trigger_px} | reason: ${diff.reason ?? 'unknown'}`);
    }
  }
});

stream.on('error', (err) => console.error('Stream error:', err));
stream.on('end', () => console.log('Stream ended'));

該 diff_type 值是與 proto 枚舉名稱相符的字串（'TPSL_DIFF_TYPE_ADD', 'TPSL_DIFF_TYPE_REMOVE'). 當使用生成的 TypeScript 類型時（如下方的範例應用程式所示），您可以與 TpslDiffType 改用枚舉常數： diff.diff_type === TpslDiffType.ADD.

執行串流​

將設定、連線和解析程式碼整合為單一 index.ts, 然後執行：

npx ts-node index.ts

第一批有 快照：true 並包含所有目前已開啟的觸發訂單。後續批次為增量處理。預期輸出：

快照：1482筆未成交觸發訂單
新增停損市價賣出觸發單：px=40021.0 sz=0.00429
已移除 oid=477390148344（價格 1754.0） | 原因：已取消

範例應用程式：Hyperliquid TP/SL 熱力圖​

該 Hyperliquid TP/SL 熱力圖 範例應用程式將本指南中的概念應用於瀏覽器中的即時儀表板。它將處於靜態狀態的止盈（TP）／止損（SL）觸發訂單渲染為價格水準熱力圖，並疊加來自 StreamBboBook 作為參考線。

Hyperliquid TP/SL 熱力圖

執行應用程式​

此範例應用程式使用pnpm。請克隆該儲存庫，並導航至範例應用程式：

git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/sample-dapps/hyperliquid-tpsl-heatmap
pnpm install && cp .env.example .env

請在以下位置設定您的 Quicknode 端點和憑證： .env:

QUICKNODE_GRPC_ENDPOINT=您的端點.hype-mainnet.quiknode.pro:10000
QUICKNODE_GRPC_TOKEN=您的-驗證-代幣
DEMO_MODE=false

啟動伺服器：

pnpm dev

開啟 http://localhost:8787. 若缺少憑證，應用程式會自動以標示明確的「示範模式」啟動。

本指南與該應用程式的關聯性​

本指南中提到的流相關概念，是透過以下兩個檔案來實現的： src/server/streams.ts 開啟 gRPC 連線，並 src/server/cluster-store.ts 維持即時狀態。

同時開啟兩個串流​

該應用程式訂閱了 StreamTpslUpdates 以及 StreamBboBook 在啟動時並行執行，每個都擁有自己的重新連線迴圈，並採用指數退避機制：

src/server/streams.ts
// simplified — reconnect implements exponential backoff; see full source for details
const connectTpsl = () => {
  const { client, metadata } = createGrpcClient(config.endpoint!, config.token!);
  const stream = client.StreamTpslUpdates({ coins: config.coins }, metadata);

  stream.on('data', (update: TpslUpdatesUpdate) => {
    store.applyTpslUpdate(update);
    if (update.snapshot) streamState.snapshot = true;
    publish();
  });

  stream.on('error', reconnect);
  stream.on('end', () => reconnect());
};

connectBbo();   // StreamBboBook
connectTpsl();  // StreamTpslUpdates

路由 ADD 和 REMOVE 差異​

applyTpslUpdate 首先處理快照標記（在重新連線時清除過期的狀態），然後根據類型路由每個差異：

src/server/cluster-store.ts
// inside class ClusterStore
applyTpslUpdate(update: TpslUpdatesUpdate): void {
  if (update.snapshot) {
    for (const coin of this.coins) this.clearCoin(coin);
  }
  for (const diff of update.diffs || []) {
    if (diff.diff_type === TpslDiffType.ADD) this.addOrder(diff);
    if (diff.diff_type === TpslDiffType.REMOVE) this.removeOrder(diff);
  }
}

removeOrder 用途 理由 為了區分「觸發的暫停」與「取消」，可直接套用本指南中的「差異」語義：

src/server/cluster-store.ts
// inside class ClusterStore — coinOrders is a Map<string, TpslOrderDiff> keyed by oid
removeOrder(diff: TpslOrderDiff): void {
  const existing = coinOrders.get(String(diff.oid));
  if (existing) coinOrders.delete(String(diff.oid));
  this.pushEvent(eventOrder, diff.reason === 'filled' ? 'TRIGGERED' : 'REMOVED', diff.reason);
}

按價格區間分組​

訂單會彙總至 ClusterBucket 以四捨五入後的價格水準為基準的交易記錄。價格區間的大小會根據資產當前的中價進行調整，因此在典型價格下，BTC 的價格區間約為 500 美元，ETH 的價格區間則約為 25 美元：

src/server/cluster-store.ts
private bucketSizeForCoin(coin: string): number {
  const mid = this.bbo.get(coin)?.mid;
  const referencePrice = mid ?? fallbackPrice;
  return this.niceBucketSize(referencePrice * (this.bucketSizePct / 100));
}

每筆訂單的名義金額（trigger_px * sz) 會被計入其籃子中。位置規模的止盈/止損訂單，其中 sz：「0.0」 這些數據雖被計入，但不會納入名義總額。由此產生的區間用來驅動熱力圖的渲染：強度反映各價格水準的名義總額，而止盈（TP）與止損（SL）的數量則按區間分別列出。

關於渲染層，請參閱 src/client/HeatmapCanvas.tsx.

結論​

StreamTpslUpdates 針對處於靜止狀態的觸發訂單，提供按區塊分批的 ADD 和 REMOVE 差異資料，而這些資料在公開的 Hyperliquid 端點上並無對應項目。該 理由 REMOVE 差異報告中的「field」欄位會告訴您，該訂單是已被觸發還是已被取消。該 Hyperliquid TP/SL 熱力圖 此範例應用程式將這些概念轉化為即時價格水準熱力圖，顯示停損壓力相對於當前買價與賣價的集中位置。

下一步​

  • Hyperliquid TP/SL 熱力圖：本指南的完整視覺化實現，以即時瀏覽器熱力圖的形式呈現
  • Hyperliquid gRPC API：完整流參考、proto 檔案及連線詳細資訊
  • 交易所 API：透過 REST 端點在 Hyperliquid 上下單與管理訂單
  • 資訊端點：查詢市場數據、用戶持倉、未平倉單及交易紀錄
  • SQL Explorer：在已建立索引的 Hyperliquid 資料上執行 SQL 查詢，包括歷史交易紀錄、資金費率及清算紀錄
  • Quicknode Streams：基於推送的事件傳遞，具備自訂篩選功能及「僅傳送一次」的保證
  • Hyperliquid API 概覽：完整介紹 Quicknode 上所有可用的 HyperCore 和 HyperEVM API

常見問題​

在 Hyperliquid 的公開 API 上，能否看到止損和獲利了結訂單？

不。Hyperliquid 的公開 REST 和 WebSocket API 並不會公開靜置的 TP/SL 觸發訂單。這些條件訂單在價格達到觸發水準之前，不會顯示在可見的訂單簿中。StreamTpslUpdates 是唯一能在這些靜置訂單觸發前查看它們的方式，讓您能預先掌握停損連鎖反應可能發生的位置。

如何在 Hyperliquid 上串流 TP/SL 觸發訂單？

使用 Quicknode Hyperliquid gRPC 端點訂閱 StreamTpslUpdates。傳入一個 coins 陣列以依資產篩選（例如：['BTC', 'ETH']），或傳入空陣列以取得所有幣種。第一批資料的 snapshot 設定為 true，並包含所有目前已開啟的觸發訂單。後續批次則會依每個區塊傳送 ADD 和 REMOVE 的增量差異。

我該如何判斷觸發式訂單是已執行還是已被取消？

請檢查 REMOVE 差異報告中的「原因」欄位。若值為「filled」，表示該訂單已觸發並執行；若值為「canceled」或「reduceOnlyCanceled」，則表示該訂單在未執行前已被移除。

我能否透過 StreamTpslUpdates 一次訂閱所有幣種？

是的。將一個空陣列傳遞給 coins 欄位（coins: []），即可接收所有可用貨幣的 TP/SL 更新。為確保能進行精確的單一貨幣分析，請針對每種貨幣分別維護獨立的叢集狀態。

快照批次包含哪些內容？這為何重要？

當第一個 TpslUpdatesUpdate 批次中的「快照」參數設為 true 時，該批次將包含所有請求幣種中目前處於開啟狀態的 TP/SL 觸發訂單。這能為您的應用程式提供一個完整的基準狀態，作為增量差異比對開始前的參考。若您的資料串流發生斷線並重新連線，系統會傳送新的快照，讓您能夠完整且無遺漏地重置本地狀態。

StreamTpslUpdates 是否需要特定的 Quicknode 方案？

是的。若要使用 Hyperliquid gRPC 串流功能（包括 StreamTpslUpdates），必須訂閱 Quicknode Build 方案或更高階的方案。免費試用端點不包含 gRPC 存取權限。

我們 ❤️ 您的回饋！

如果您有任何意見回饋或對新主題的建議，請告訴我們。我們非常樂意聽取您的意見。

最後更新時間 於
分享這份指南