# historicalOrdersByTime - Historical Orders by Time

Use `historicalOrdersByTime` to retrieve order status updates for one Hyperliquid user inside a bounded time window. Results are ordered by ascending status timestamp.

## Endpoints

REST-style Info API:

```text
POST https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/info
```

JSON-RPC:

```text
POST https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/jsonrpc
```

## Billing

`historicalOrdersByTime` responses are billed by the number of order status objects returned, not as one response per HTTP request.
A response with `100` orders counts as `100` responses/API credits.

Requests that return an empty array are billed as `0` responses/API credits and do not count against usage. Error responses are not charged.

Use the last row from the previous page and pass `cursor` as `statusTimestamp_txIndex_oid`. The `oid` suffix prevents rows with the same status timestamp and `txIndex` from being skipped across pages.

## Request Parameters

- `type` (`string, required`): Must be historicalOrdersByTime for /info REST requests. Omit this field for JSON-RPC.
- `user` (`string, required`): 0x-prefixed Hyperliquid user address.
- `coin` (`string, optional`): Exact Hyperliquid market symbol, for example BTC. When supplied, only rows for that market are returned.
- `startTime` (`number, optional`): Inclusive Unix timestamp in milliseconds. Required unless cursor is supplied.
- `endTime` (`number, optional`): Exclusive Unix timestamp in milliseconds.
- `cursor` (`string, optional`): Pagination cursor in statusTimestamp_txIndex_oid format. Resumes after that order status update; startTime is skipped when cursor is supplied.
- `limit` (`number, optional`): Maximum rows to return, capped at 2000.

## Request Example

```bash
curl -X POST "https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/info" \
  -H "content-type: application/json" \
  -d '{
  "type": "historicalOrdersByTime",
  "user": "0x1111111111111111111111111111111111111111",
  "coin": "BTC",
  "startTime": 1753606200000,
  "endTime": 1753606300000,
  "limit": 100
}'
```

## Response Fields

- `orders` (`array, required`): Array of order status objects. /info returns this array directly; JSON-RPC returns it under result. Empty matches return an empty array and are billed as 0 responses/API credits. Billing counts one response/API credit per order object returned.
- `builder` (`string, optional`): Builder address, when present.
- `txIndex` (`number, optional`): Block-local order status event index, when available.
- `status` (`string, required`): Order status for this update.
- `statusTimestamp` (`number, required`): Order status timestamp in Unix milliseconds.
- `order` (`object, required`): Nested order details.
- `order.coin` (`string, required`): Hyperliquid market symbol.
- `order.side` (`string, required`): B for bid/buy side, A for ask/sell side.
- `order.limitPx` (`string, required`): Limit price as a decimal string.
- `order.sz` (`string, required`): Order size as a decimal string.
- `order.oid` (`number, required`): Hyperliquid order ID.
- `order.timestamp` (`number, required`): Original order timestamp in Unix milliseconds.
- `order.triggerCondition` (`string, optional`): Trigger condition, when present.
- `order.isTrigger` (`boolean, required`): Whether this is a trigger order.
- `order.triggerPx` (`string, optional`): Trigger price as a decimal string.
- `order.children` (`array, required`): Child orders associated with this order.
- `order.isPositionTpsl` (`boolean, required`): Whether this is a position take-profit or stop-loss order.
- `order.reduceOnly` (`boolean, required`): Whether the order is reduce-only.
- `order.orderType` (`string, required`): Order type, such as Limit.
- `order.origSz` (`string, optional`): Original order size as a decimal string.
- `order.tif` (`string, optional`): Time-in-force value, when present.
- `order.cloid` (`string, optional`): Client order ID, when present.

## Successful Response

```json
[
  {
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
    "txIndex": 8,
    "status": "filled",
    "statusTimestamp": 1753606200000,
    "order": {
      "coin": "BTC",
      "side": "B",
      "limitPx": "45000",
      "sz": "0.5",
      "oid": 1234,
      "timestamp": 1753606100000,
      "triggerCondition": "N/A",
      "isTrigger": false,
      "triggerPx": "0",
      "children": [],
      "isPositionTpsl": false,
      "reduceOnly": true,
      "orderType": "Limit",
      "origSz": "0.5",
      "tif": "Gtc",
      "cloid": "0xabc"
    }
  }
]
```

## Error Responses

### Error

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "invalid request"
  }
}
```

## REST-style Example

```bash
curl -X POST "https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/info" \
  -H "content-type: application/json" \
  -d '{
  "type": "historicalOrdersByTime",
  "user": "0x1111111111111111111111111111111111111111",
  "coin": "BTC",
  "startTime": 1753606200000,
  "endTime": 1753606300000,
  "limit": 100
}'
```

## JSON-RPC Example

```bash
curl -X POST "https://api-hyperliquid-index.n.dwellir.com/YOUR_API_KEY/jsonrpc" \
  -H "content-type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "historicalOrdersByTime",
  "params": {
    "user": "0x1111111111111111111111111111111111111111",
    "coin": "BTC",
    "startTime": 1753606200000,
    "endTime": 1753606300000,
    "limit": 100
  }
}'
```

## Response

REST `/info` responses return an array directly. JSON-RPC responses return the same array under `result`. Empty matches return `[]`; they are not errors.