> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/websocket/tpslupdates.md).

# tpslUpdates

{% hint style="info" %}
💧 New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.
{% endhint %}

### Subscribe

```json
{
    "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](/readme/websocket/rate-limits-user-limits-and-heartbeats.md) for the full table.

{% hint style="warning" %}
Trigger orders only exist on **perpetual markets**. Spot and outcome markets do not have TP/SL orders, so no `marketTypes` filter is needed.
{% endhint %}

### Unsubscribe

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

### Update data format

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

```json
{
    "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.

<details>

<summary>Known reason values (for logging / analytics)</summary>

| 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.

</details>

### 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hydromancer.xyz/readme/websocket/tpslupdates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.