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

# builderOrdersByTime

{% 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" %}
Historical data is available from August 7th, 2025. Users who had >100k orders between Aug 7 and Nov 4, 2025 will have only last 100k orders available. All orders are retained indefinitely going forward.
{% 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 <code>"builderOrdersByTime"</code></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, defaults to now)</td></tr><tr><td><code>cursor</code></td><td>string</td><td>Composite of statusTimestamp and txIndex with "_" separator (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": "builderOrdersByTime",
    "builder": "0x0000000000000000000000000000000000000000",
    "startTime": 1234567890000,
    "endTime": 1234567900000
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'builderOrdersByTime',
        'builder': '0x0000000000000000000000000000000000000000',
        'startTime': 1234567890000,
        'endTime': 1234567900000
    },
    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: 'builderOrdersByTime',
        builder: '0x0000000000000000000000000000000000000000',
        startTime: 1234567890000,
        endTime: 1234567900000
    }, {
        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                                              |
| ------------------------ | ------- | -------------------------------------------------------- |
| `user`                   | string  | User address who placed the order                        |
| `builderFee`             | int     | Builder fee in basis points                              |
| `txIndex`                | int     | Transaction index                                        |
| `order`                  | object  | Order details (see Order Object below)                   |
| `status`                 | string  | Order status (see status values below)                   |
| `statusTimestamp`        | int     | Timestamp of status update in milliseconds               |
| `order.coin`             | string  | Asset symbol                                             |
| `order.side`             | string  | `"A"` (sell) or `"B"` (buy)                              |
| `order.limitPx`          | string  | Limit price                                              |
| `order.sz`               | string  | Order size                                               |
| `order.oid`              | int     | Order ID                                                 |
| `order.timestamp`        | int     | Order creation timestamp in milliseconds                 |
| `order.triggerCondition` | string  | Trigger condition if applicable                          |
| `order.isTrigger`        | boolean | Whether order is a trigger order                         |
| `order.triggerPx`        | string  | Trigger price                                            |
| `order.children`         | array   | Child orders for take profit/stop loss orders            |
| `order.isPositionTpsl`   | boolean | Whether order is position TP/SL                          |
| `order.reduceOnly`       | boolean | Whether order is reduce-only                             |
| `order.orderType`        | string  | Order type (e.g. `"Limit"`, `"Market"`)                  |
| `order.origSz`           | string  | Original order size                                      |
| `order.tif`              | string  | Time in force, e.g. `"Gtc"`, `"Ioc"`, `"Alo"` (optional) |
| `order.cloid`            | string  | Client order ID (optional, null if not set)              |

<details>

<summary>Response</summary>

```json
[
  {
    "user": "0x...",
    "builderFee": 100, // optional
    "txIndex": 12,
    "order": {
      "coin": "BTC",
      "side": "B",
      "limitPx": "45000.00",
      "sz": "0.5",
      "oid": 123456,
      "timestamp": 1234567890123,
      "triggerCondition": "tp",
      "isTrigger": false,
      "triggerPx": "0.00",
      "children": [],
      "isPositionTpsl": false,
      "reduceOnly": false,
      "orderType": "Limit",
      "origSz": "0.5",
      "tif": "Gtc", // optional
      "cloid": "client-order-123" // optional
    },
    "status": "filled",
    "statusTimestamp": 1234567890123
  }
]
```

</details>

<details>

<summary>Status values</summary>

**Active:**

* `open` - Order is resting on the orderbook
* `triggered` - Stop/trigger order was triggered
* `scheduledCancel` - Order is scheduled for cancellation

**Filled:**

* `filled` - Order completely filled

**Canceled:**

* `canceled` - Canceled by user
* `marginCanceled` - Insufficient margin
* `liquidatedCanceled` - Position was liquidated
* `delistedCanceled` - Asset was delisted
* `reduceOnlyCanceled` - Reduce-only order canceled (no position)
* `selfTradeCanceled` - Would have resulted in self-trade
* `siblingFilledCanceled` - Sibling TP/SL order filled
* `vaultWithdrawalCanceled` - Vault withdrawal triggered cancellation
* `openInterestCapCanceled` - Open interest cap reached

**Rejected:**

* `badAloPxRejected` - ALO price would cross the book
* `iocCancelRejected` - IOC order couldn't fill
* `reduceOnlyRejected` - Reduce-only order rejected
* `oracleRejected` - Oracle price check failed
* `perpMarginRejected` - Insufficient perp margin
* `perpMaxPositionRejected` - Max position size exceeded
* `openInterestIncreaseRejected` - Open interest increase rejected
* `positionFlipAtOpenInterestCapRejected` - Position flip at OI cap rejected
* `positionIncreaseAtOpenInterestCapRejected` - Position increase at OI cap rejected
* `tooAggressiveAtOpenInterestCapRejected` - Too aggressive at OI cap
* `minTradeNtlRejected` - Below minimum trade notional
* `insufficientSpotBalanceRejected` - Insufficient spot balance

</details>

<details>

<summary>Pagination</summary>

* When a cursor is provided, `startTime` is ignored
* Results are ordered by timestamp
* For pagination construct the cursor with the statusTimestamp and txIndex of the last order returned in the previous fetch like "cursor":"{statusTimestamp}\_{txIndex}"

</details>