> 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/userfillsbytime.md).

# userFillsByTime

Get trading fills for a single user within a time range. Includes twap fills.

{% hint style="info" %}
**All data fully available from 28-07-2025. We have performed a full backfill of all fills the HL native API offered, meaning that we have full historical data for most traders except for some very high volume addresses. TWAP fills are included from 02-08-2025.**
{% 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>"userFillsByTime"</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 fill time 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 fill time 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>txIndex</code> with <code>"_"</code> separator (e.g. <code>"1234567890000_23"</code>). Take from the <strong>last record</strong> of the previous response (optional)</td></tr><tr><td><code>builder</code></td><td>string</td><td>Filter to fills routed through this builder address (0x-prefixed, 42 characters). Omit for no filtering (optional)</td></tr><tr><td><code>aggregateByTime</code></td><td>boolean</td><td><code>true</code> or <code>false</code>, <code>false</code> by default (optional)</td></tr><tr><td><code>dex</code></td><td>string</td><td>i.e. <code>"xyz"</code> or <code>"main_dex"</code>, or omit for no filtering (optional)</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Max results to return, default 2000 (optional)</td></tr></tbody></table>

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

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userFillsByTime",
    "user": "0x0000000000000000000000000000000000000000",
    "startTime": 1234567890000,
    "endTime": 1234567900000,
    "cursor": "1234567890000_23"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'userFillsByTime',
        'user': '0x0000000000000000000000000000000000000000',
        'startTime': 1234567890000,
        'endTime': 1234567900000,
        'cursor': '1234567890000_12'
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'userFillsByTime',
        user: '0x0000000000000000000000000000000000000000',
        startTime: 1234567890000,
        endTime: 1234567900000,
        cursor: '1234567890000_12'
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}
```

{% endtab %}
{% endtabs %}

***

## Response Fields

| Field           | Type    | Description                                                     |
| --------------- | ------- | --------------------------------------------------------------- |
| `coin`          | string  | Asset symbol                                                    |
| `px`            | string  | Fill price                                                      |
| `sz`            | string  | Fill size                                                       |
| `side`          | string  | `"A"` (sell) or `"B"` (buy)                                     |
| `time`          | int     | Fill timestamp (ms)                                             |
| `startPosition` | string  | Position size before the fill                                   |
| `dir`           | string  | Direction (e.g. `"Open Long"`, `"Close Short"`, `"Settlement"`) |
| `closedPnl`     | string  | Closed PnL from this fill                                       |
| `hash`          | string  | Transaction hash                                                |
| `oid`           | int     | Order ID                                                        |
| `crossed`       | boolean | Whether the order crossed the spread                            |
| `fee`           | string  | Fee amount                                                      |
| `tid`           | int     | Trade ID                                                        |
| `cloid`         | string? | Client order ID (optional)                                      |
| `builderFee`    | string? | Builder fee (optional)                                          |
| `deployerFee`   | string? | Deployer fee (optional, HIP-3 fills only)                       |
| `priorityGas`   | string? | Priority gas fee in HYPE (optional)                             |
| `feeToken`      | string  | Fee token (e.g. `"USDC"`)                                       |
| `twapId`        | int?    | TWAP order ID (null if not a TWAP fill)                         |
| `txIndex`       | int     | Transaction index                                               |

<details>

<summary>Response</summary>

```json
[
  {
    "coin": "hyna:LIT",
    "px": "3.38",
    "sz": "306.0635",
    "side": "A",
    "time": 1766411264116,
    "startPosition": "306.0635",
    "dir": "Settlement",
    "closedPnl": "0.00",
    "hash": "0xe9700f27f4c60944eae90431e255630202d5000d8fc928168d38ba7ab3c9e32f",
    "oid": 276429539434,
    "crossed": false,
    "fee": "0.00",
    "tid": 587851719766407,
    "feeToken": "USDE",
    "twapId": null,
    "txIndex": 1
  }
]
```

</details>