> 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 is fully available from 28-07-2025. Hydromancer performed a full backfill of fills offered by the native Hyperliquid API. The result includes full historical data for most traders, except 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 (or send <code>null</code>) for no filtering. A malformed, empty or non-string value is a <code>400</code> rather than a silently unfiltered result (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>venue</code></td><td>string</td><td>Only fills on outcome markets deployed by this permissionless venue, e.g. <code>"skew"</code>. 2–4 ASCII letters, case-insensitive; an unknown venue returns an empty list (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                                                                                                     |
| `venue`         | string? | HIP-4 venue of an outcome (`#NNNN`) market, e.g. `"out"`. Omitted for validator-deployed outcomes and all other coins |

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