# 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
FieldTypeDescription
typestringMust be "builderOrdersByTime"
builderstringEthereum address (0x-prefixed, 42 characters)
startTimeintegerStart timestamp in milliseconds (skipped when cursor is used)
endTimeintegerEnd timestamp in milliseconds (optional, defaults to now)
cursorstringComposite of statusTimestamp and txIndex with "_" separator (optional)
{% 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) |
Response ```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 } ] ```
Status values **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
Pagination * 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}"
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hydromancer.xyz/readme/rest-api/historical-data/builderordersbytime.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.