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

# builderFillsByTime

Get fills submitted by a builder in a certain time range.

{% 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" %}
**Data available from 28-07-2025**
{% endhint %}

## POST Request

<table><thead><tr><th width="164.6666259765625">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 "builderFillsByTime"</td></tr><tr><td><code>builder</code></td><td>string</td><td>Ethereum address (0x-prefixed, 42 characters)</td></tr><tr><td><code>startTime</code></td><td>integer</td><td>Start timestamp in milliseconds (skipped when cursor is used)</td></tr><tr><td><code>endTime</code></td><td>integer</td><td>End timestamp in milliseconds (optional)</td></tr><tr><td><code>cursor</code></td><td>string</td><td>Composite of time and txIndex with "_" separator (optional)</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Max results to return, default and max 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": "builderFillsByTime",
    "builder": "0x0000000000000000000000000000000000000000",
    "startTime": 1234567890000,
    "endTime": 1234567900000,
    "cursor": "1234567890000_12"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'builderFillsByTime',
        'builder': '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: 'builderFillsByTime',
        builder: '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"`, `"Open Short"`, `"Short > Long"`) |
| `closedPnl`     | string  | Closed PnL from this fill                                        |
| `hash`          | string  | Transaction hash                                                 |
| `oid`           | int     | Order ID                                                         |
| `crossed`       | boolean | Whether the order crossed the spread                             |
| `cloid`         | string? | Client order ID (optional)                                       |
| `fee`           | string  | Fee amount                                                       |
| `tid`           | int     | Trade ID                                                         |
| `builderFee`    | string? | Builder fee (optional)                                           |
| `deployerFee`   | string? | Deployer fee (HIP-3 fills only)                                  |
| `priorityGas`   | string? | Priority gas fee in HYPE (optional)                              |
| `feeToken`      | string  | Fee token (e.g. `"USDC"`)                                        |
| `user`          | string  | User address who placed the order                                |
| `twapId`        | int     | TWAP order ID (null if not a TWAP fill)                          |
| `txIndex`       | int     | Transaction index                                                |

<details>

<summary>Response</summary>

```json
[
  {
    "coin": "BTC",
    "px": "71070.00",
    "sz": "0.00541",
    "side": "A",
    "time": 1773429781878,
    "startPosition": "0.00",
    "dir": "Open Short",
    "closedPnl": "0.00",
    "hash": "0xa33ab861b80567f1a4b40436ff72410204530047530886c3470363b4770941dc",
    "oid": 348153004784,
    "crossed": true,
    "fee": "0.211467",
    "tid": 491098859095794,
    "builderFee": "0.038448",
    "deployerFee": "0.019224",
    "priorityGas": null,
    "feeToken": "USDC",
    "user": "0x5e24ba0e5753fb533e8ac74c63f00fa73488c484",
    "twapId": null,
    "txIndex": 21
  }
]
```

</details>