Présentation générale

Le StreamTpslUpdates stream delivers the lifecycle of trigger and take-profit/stop-loss orders as ADD et REMOVE diffs. Trigger orders do not appear in the regular order book streams until they trigger. This stream is the way to observe resting TP/SL orders directly. Use it for trigger-order heatmaps, liquidation and stop monitoring, frontend overlays, and alerting around resting TP/SL orders.

gRPC : OrderBookStreaming
gRPC : StreamTpslUpdates
Modèle de mise à jour : Snapshot of currently-open trigger orders on subscribe, then add/remove diffs per block

Comment ça marche ?

1. Lors de l'inscription : The first message has snapshot: true and contains all currently-open trigger orders as TPSL_DIFF_TYPE_ADD diffs
2. Par bloc supplémentaire : Each TpslUpdatesUpdate contains ADD diffs for newly placed trigger orders and REMOVE diffs for trigger orders that left the resting set. Removes carry a reason (par exemple, "reduceOnlyCanceled") mirroring node order statuses
3. Maintain a local map of open trigger orders keyed by oid if you need the current resting set

Trigger orders are perpetuals-only, so this stream covers perp coins. An empty coins list subscribes to all perp coins.

Structure de données

Each TpslUpdatesUpdate message contains the trigger-order diffs for one block:

{
  "time": 1781109188721,
  "height": 586405650,
  "diffs": [
    { "diff_type": "TPSL_DIFF_TYPE_ADD", "oid": 54764664388, "coin": "ETH",
      "user": "0xA5cace4Bd730bAC2E814CB50c4F3A58DDBA017BF", "side": "B",
      "trigger_px": "1702.1", "limit_px": "1872.4", "sz": "0.0294",
      "trigger_condition": "Price above 1702.1", "order_type": "Stop Market",
      "reduce_only": true, "timestamp": 1781109188721 }
  ]
}

Paramètres de requête

Champ	Type	Obligatoire	Description
coins	repeated string	Non	List of perp symbols to subscribe to (e.g., "BTC", "ETH"). Empty means all perp coins

Dénomination des pièces

Trigger orders exist for perpetuals only, so the coins parameter accepts perp names: human-readable symbols like « BTC », « ETH », « HYPE », « SOL ». The spot @{index} format does not apply to this stream. An empty list subscribes to all perp coins.

Champs de réponse

TpslUpdatesUpdate

Champ	Type	Description
temps	uint64	Horodatage du bloc en millisecondes
hauteur	uint64	Hauteur du bloc
instantané	bool	True when the diffs carry the currently-open trigger orders as a snapshot (sent on subscribe)
diffs	TpslOrderDiff[]	Trigger-order add/remove diffs for this block

TpslOrderDiff

Champ	Type	Description
diff_type	TpslDiffType	TPSL_DIFF_TYPE_ADD (trigger order placed) or TPSL_DIFF_TYPE_REMOVE (trigger order left the resting set)
oid	uint64	Référence unique de la commande
pièce de monnaie	chaîne de caractères	Perp symbol (e.g., "BTC", "ETH")
utilisateur	chaîne de caractères	Ethereum du titulaire de la commande
côté	chaîne de caractères	« A » (Cours vendeur/Vente) ou « B » (Cours acheteur/Achat)
trigger_px	chaîne de caractères	Prix de déclenchement sous forme de chaîne décimale
limit_px	chaîne de caractères	Limit price as a decimal string (for market trigger orders, the execution limit, which may be offset from trigger_px by a slippage allowance)
sz	chaîne de caractères	Order size as a decimal string. "0.0" for position TP/SL orders, which are sized by the position
condition_de_déclenchement	chaîne de caractères	Human-readable trigger condition (e.g., "Price above 1778")
type_de_commande	chaîne de caractères	Trigger order type (e.g., "Stop Market", "Stop Limit", "Take Profit Market", "Take Profit Limit")
is_position_tpsl	bool	Whether the order is a position take-profit/stop-loss (sized by the position; sz is "0.0")
réduire_uniquement	bool	Que l'ordre soit « réduction uniquement »
horodatage	uint64	Order creation time in milliseconds
reason	chaîne de caractères	Removal reason, present on REMOVE diffs (e.g., "reduceOnlyCanceled"). Mirrors node order statuses

Définition de « proto »

StreamTpslUpdates est défini dans orderbook.proto:

service OrderBookStreaming {
  rpc StreamTpslUpdates (TpslUpdatesRequest) returns (stream TpslUpdatesUpdate);
}

message TpslUpdatesRequest {
  repeated string coins = 1;
}

enum TpslDiffType {
  TPSL_DIFF_TYPE_UNSPECIFIED = 0;
  TPSL_DIFF_TYPE_ADD = 1;
  TPSL_DIFF_TYPE_REMOVE = 2;
}

message TpslUpdatesUpdate {
  uint64 time = 1;
  uint64 height = 2;
  repeated TpslOrderDiff diffs = 3;
  bool snapshot = 4;
}

message TpslOrderDiff {
  TpslDiffType diff_type = 1;
  uint64 oid = 2;
  string coin = 3;
  string user = 4;
  string side = 5;
  string trigger_px = 6;
  string limit_px = 7;
  string sz = 8;
  string trigger_condition = 9;
  string order_type = 10;
  bool is_position_tpsl = 11;
  bool reduce_only = 12;
  uint64 timestamp = 13;
  string reason = 14;
}

Exemples de mises à jour

Initial Snapshot (first message, truncated)

The first message has snapshot: true and contains all currently-open trigger orders as ADD diffs:

{
  "time": 1781109147521,
  "height": 586405394,
  "snapshot": true,
  "diffs": [
    { "diff_type": "TPSL_DIFF_TYPE_ADD", "oid": 54678088397, "coin": "ETH",
      "user": "0x2308ccA96D9Ddde6F9A37D447C87d6B6b267E307", "side": "A",
      "trigger_px": "1778.0", "limit_px": "1778.0", "sz": "0.0297",
      "trigger_condition": "Price above 1778", "order_type": "Take Profit Market",
      "reduce_only": true, "timestamp": 1780996670847 },
    { "diff_type": "TPSL_DIFF_TYPE_ADD", "oid": 54694008956, "coin": "BTC",
      "user": "0xB996742Cc1BA8E8A949021dd609f7b45Ac032CC1", "side": "A",
      "trigger_px": "60687.0", "limit_px": "60596.0", "sz": "0.00018",
      "trigger_condition": "Price below 60687", "order_type": "Stop Limit",
      "reduce_only": true, "timestamp": 1781017693515 }
  ]
}

Position TP/SL Order

Position TP/SL orders carry sz: "0.0" because they are sized by the position at trigger time:

{ "diff_type": "TPSL_DIFF_TYPE_ADD", "oid": 54629542173, "coin": "BTC",
  "user": "0x0F15d3Ecc22BE9Ab1C1be2A0a265bfb715af3Ccc", "side": "B",
  "trigger_px": "79089.0", "limit_px": "79089.0", "sz": "0.0",
  "trigger_condition": "Price above 79089", "order_type": "Stop Market",
  "is_position_tpsl": true, "reduce_only": true, "timestamp": 1780928051012 }

Live Add

{
  "time": 1781109188721,
  "height": 586405650,
  "diffs": [
    { "diff_type": "TPSL_DIFF_TYPE_ADD", "oid": 54764664388, "coin": "ETH",
      "user": "0xA5cace4Bd730bAC2E814CB50c4F3A58DDBA017BF", "side": "B",
      "trigger_px": "1702.1", "limit_px": "1872.4", "sz": "0.0294",
      "trigger_condition": "Price above 1702.1", "order_type": "Stop Market",
      "reduce_only": true, "timestamp": 1781109188721 }
  ]
}

Live Remove (with reason)

{
  "time": 1781109151770,
  "height": 586405419,
  "diffs": [
    { "diff_type": "TPSL_DIFF_TYPE_REMOVE", "oid": 54764554453, "coin": "BTC",
      "user": "0x4f62EFb29bb38a975C1e54cb39aD3aA4E8777CF4", "side": "A",
      "trigger_px": "61968.0", "limit_px": "61968.0", "sz": "0.00019",
      "trigger_condition": "Price below 61968", "order_type": "Stop Market",
      "reduce_only": true, "timestamp": 1781109080552, "reason": "reduceOnlyCanceled" }
  ]
}

Utilisation de l'API

gRPC

// Specific perp coins
const request = {
  coins: ['ETH', 'BTC']
};

// All perp coins
const allCoinsRequest = {
  coins: []
};

gRPC

StreamTpslUpdates n'est disponible que via l'API gRPC (OrderBookStreaming service). Il n'est pas disponible via JSON-RPC ou WebSocket.

Remarques importantes

• Trigger orders are not in the book streams: Resting TP/SL orders do not appear in StreamL2Book/StreamL4Book until they trigger and convert into regular orders. This stream is the direct view of the resting trigger set
• Snapshot on subscribe and reconnect: The first message carries all currently-open trigger orders as ADD diffs, so reconnects rebuild state automatically
• Position TP/SL sizing: Orders with is_position_tpsl: true carry sz: "0.0", as they are sized by the position rather than a fixed size
• reason on removes: Remove diffs include a reason string mirroring node order statuses (e.g., "reduceOnlyCanceled"), useful for distinguishing cancels from triggers
• Perp coins only: Trigger orders exist for perpetuals; an empty coins list means all perp coins
• zstd compression recommended: Enable zstd compression on your gRPC channel to reduce bandwidth, especially when streaming all perp coins

Streams associés

• StreamL4BookUpdates - Typed per-order book diffs for regular resting orders
• Commandes - Événements liés au cycle de vie des commandes (en cours, exécutées, annulées, etc.)
• Events - Balance changes, transfers, liquidations, and funding payments