tpslUpdates

Stream real-time TP/SL trigger order updates per block.

💧 New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

Subscribe

{
    "method": "subscribe",
    "subscription": {
        "type": "tpslUpdates",
        "coins": ["ETH", "BTC"]
    }
}

Parameters:

Parameter	Type	Required	Description
coins	string[]	No	Perp coins to subscribe to. Omit for all markets (needs tpslUpdatesAll add-on).

Per-tier coin limits: Starter 5 · Growth 50 · Scale 200. See rate-limits-user-limits-and-heartbeats.md for the full table.

Trigger orders only exist on perpetual markets. Spot and outcome markets do not have TP/SL orders, so no marketTypes filter is needed.

Unsubscribe

{
    "method": "unsubscribe",
    "subscription": {
        "type": "tpslUpdates",
        "coins": ["ETH", "BTC"]
    }
}

Update data format

Updates are streamed per-block with trigger order changes for subscribed markets:

{
    "type": "tpslUpdates",
    "seq": 1,
    "cursor": "500:1704067200000",
    "data": {
        "height": 782007304,
        "timestamp": 1704067200000,
        "diffs": [
            {
                "type": "add",
                "oid": 285974866067,
                "coin": "BTC",
                "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
                "side": "A",
                "triggerPx": "50000.00",
                "limitPx": "49000",
                "sz": "0.01",
                "triggerCondition": "Price above 50000",
                "orderType": "Take Profit Market",
                "isPositionTpsl": true,
                "reduceOnly": true,
                "timestamp": 1704067100000
            },
            {
                "type": "remove",
                "oid": 285974866000,
                "coin": "BTC",
                "reason": "triggered"
            }
        ]
    }
}

Diff types

Type	Description	Fields
add	New trigger order placed (or re-opened)	All order fields (see below)
remove	Trigger order removed	oid, coin, reason

Trigger orders are immutable — there is no update diff type. An order is either open (add) or terminal (remove). If a user cancels and replaces a trigger order, you'll see a remove + add with a new oid.

Add fields

Field	Type	Description
oid	int	Unique order ID
coin	string	Market symbol (e.g., "BTC", "ETH")
user	string	User address (0x...)
side	string	"B" = buy, "A" = sell
triggerPx	string	Trigger price as decimal string
limitPx	string	Limit price as decimal string
sz	string	Order size as decimal string
triggerCondition	string	Human-readable condition (e.g., "Price above 50000")
orderType	string	Order type — "Take Profit Market", "Stop Market", etc.
isPositionTpsl	bool	True if this is a position-level TP/SL (attached to a position)
reduceOnly	bool	True if reduce-only order
timestamp	int	Order creation timestamp (ms since epoch)

Remove handling

A remove diff is always terminal — drop the order from your local state. The optional reason field is informational only; you don't need to branch on it.

Known reason values (for logging / analytics)

Reason	Description
triggered	Trigger condition met, order placed on book
canceled	User canceled the order
reduceOnlyCanceled	Reduce-only order canceled (position closed)
marginCanceled	Canceled due to insufficient margin
rejected	Order rejected by the engine
siblingFilledCanceled	Sibling TP/SL order triggered, this one canceled
liquidatedCanceled	Order canceled due to position liquidation

The reason field passes through the underlying Hyperliquid status verbatim, so future status names will appear automatically. Always treat a remove diff as terminal regardless of the reason value.

Common errors

1. Too many coins - Reduce number of coins or upgrade tier

2. Subscribing to all markets requires permission - Needs tpslUpdatesAll add-on

3. Rate limit exceeded - Reduce subscription frequency

4. Authentication failed - Check API key