> 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/rest-api/historical-data/userisolatedmarginupdatesbytime.md).

# userIsolatedMarginUpdatesByTime

Returns isolated margin updates (`updateIsolatedMargin` and `topUpIsolatedOnlyMargin` actions) for a user with `time` ≥ `startTime` (or after a `cursor`), ordered **oldest-first** by `time` then `tx_index`.

For pagination: pass `startTime` for the first page, then on each subsequent page pass the `cursor` `"{time}_{tx_index}"` built from the **last record** of the previous response. When `cursor` is supplied, `startTime` is ignored and the boundary record is excluded from the next page (no duplicates).

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

{% hint style="info" %}
Record shapes match the [userIsolatedMarginUpdates WebSocket channel](/readme/websocket/userisolatedmarginupdates.md), so REST history and the live stream can be merged and deduplicated on `(time, tx_index)`. For leverage change history, see [userLeverageUpdatesByTime](/readme/rest-api/historical-data/userleverageupdatesbytime.md).
{% endhint %}

## POST Request

<table><thead><tr><th width="161.9998779296875">Field</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"userIsolatedMarginUpdatesByTime"</code></td></tr><tr><td><code>user</code></td><td>string</td><td>Ethereum address (0x-prefixed, 42 characters)</td></tr><tr><td><code>startTime</code></td><td>integer</td><td>Earliest <code>time</code> to include (Unix ms, inclusive). Skipped when <code>cursor</code> is used. Either <code>startTime</code> or <code>cursor</code> must be supplied</td></tr><tr><td><code>endTime</code></td><td>integer</td><td>Latest <code>time</code> to include (Unix ms, inclusive). Default: now (optional)</td></tr><tr><td><code>cursor</code></td><td>string</td><td>Composite of <code>time</code> and <code>tx_index</code> with <code>"_"</code> separator (e.g. <code>"1734571490123_12"</code>). Take from the <strong>last record</strong> of the previous response (optional)</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Max results to return. Default 100, max 500 (optional)</td></tr></tbody></table>

{% tabs %}
{% tab title="cURL" %}

```bash
# First page
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userIsolatedMarginUpdatesByTime",
    "user": "0x0000000000000000000000000000000000000000",
    "startTime": 0,
    "limit": 100
  }'

# Next page — cursor built from the last record of the previous response
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userIsolatedMarginUpdatesByTime",
    "user": "0x0000000000000000000000000000000000000000",
    "cursor": "1734571490123_12",
    "limit": 100
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

url = 'https://api.hydromancer.xyz/info'
headers = {
    'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
    'Content-Type': 'application/json',
}
user = '0x0000000000000000000000000000000000000000'
limit = 500

params = {'type': 'userIsolatedMarginUpdatesByTime', 'user': user, 'startTime': 0, 'limit': limit}
while True:
    page = requests.post(url, json=params, headers=headers).json()
    if not page:
        break
    for update in page:
        ...  # process isolated margin update
    if len(page) < limit:
        break
    last = page[-1]
    params = {
        'type': 'userIsolatedMarginUpdatesByTime',
        'user': user,
        'cursor': f"{last['time']}_{last['tx_index']}",
        'limit': limit,
    }
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

const url = 'https://api.hydromancer.xyz/info';
const headers = {
    'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
    'Content-Type': 'application/json',
};
const user = '0x0000000000000000000000000000000000000000';
const limit = 500;

let params = { type: 'userIsolatedMarginUpdatesByTime', user, startTime: 0, limit };
while (true) {
    const { data: page } = await axios.post(url, params, { headers });
    if (!page.length) break;
    for (const update of page) { /* process isolated margin update */ }
    if (page.length < limit) break;
    const last = page[page.length - 1];
    params = {
        type: 'userIsolatedMarginUpdatesByTime',
        user,
        cursor: `${last.time}_${last.tx_index}`,
        limit,
    };
}
```

{% endtab %}
{% endtabs %}

***

## Response Fields

JSON array of isolated margin update records, ordered **oldest-first** by `time` then `tx_index`. `update_type` selects one of two record shapes; fields the shape doesn't carry are omitted.

#### `"isolated_margin"` — margin added or removed (`updateIsolatedMargin`)

| Field         | Type    | Description                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------- |
| `update_type` | string  | `"isolated_margin"`                                                                      |
| `time`        | int     | Block time when the update was made (Unix ms) — **first half of the next-page `cursor`** |
| `user`        | string  | Ethereum address                                                                         |
| `coin`        | string  | Asset symbol                                                                             |
| `is_buy`      | boolean | Position side the margin change applies to                                               |
| `ntli`        | string  | Notional transfer amount (USDC); positive adds margin, negative removes                  |
| `tx_index`    | int     | Transaction index within the block — **second half of the next-page `cursor`**           |

#### `"top_up_isolated_margin"` — margin topped up to a target leverage (`topUpIsolatedOnlyMargin`)

| Field             | Type   | Description                                                                              |
| ----------------- | ------ | ---------------------------------------------------------------------------------------- |
| `update_type`     | string | `"top_up_isolated_margin"`                                                               |
| `time`            | int    | Block time when the update was made (Unix ms) — **first half of the next-page `cursor`** |
| `user`            | string | Ethereum address                                                                         |
| `coin`            | string | Asset symbol                                                                             |
| `target_leverage` | string | Leverage the margin top-up targets                                                       |
| `tx_index`        | int    | Transaction index within the block — **second half of the next-page `cursor`**           |