# builderLiquidationsByTime - Builder Liquidation Fills by Time

Use `builderLiquidationsByTime` to retrieve builder-attributed liquidation fills inside a bounded time window. Results are ordered by ascending fill time.

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

`builderLiquidationsByTime` responses are billed by the number of fill objects returned, not as one response per HTTP request.
A response with `100` fills 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.

`txIndex` is the fill's block-local position in the `node_fills_by_block` event array. It is exposed as a stable fill pagination key, not as a `replica_cmds`-compatible action index.

## Request Parameters

- `type` (`string, required`): Must be builderLiquidationsByTime for /info REST requests. Omit this field for JSON-RPC.
- `builder` (`string, required`): 0x-prefixed builder 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 time_txIndex format. Resumes after that fill; 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": "builderLiquidationsByTime",
  "builder": "0x2222222222222222222222222222222222222222",
  "coin": "BTC",
  "startTime": 1753606200000,
  "endTime": 1753606300000,
  "limit": 100
}'
```

## Response Fields

- `fills` (`array, required`): Array of fill 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 fill object returned.
- `coin` (`string, required`): Hyperliquid market symbol.
- `px` (`string, required`): Execution price as a decimal string.
- `sz` (`string, required`): Fill size as a decimal string.
- `side` (`string, required`): B for bid/buy side, A for ask/sell side.
- `time` (`number, required`): Fill timestamp in Unix milliseconds.
- `startPosition` (`string, optional`): User position before the fill, when available.
- `dir` (`string, optional`): Position direction.
- `closedPnl` (`string, optional`): Realized PnL as a decimal string.
- `hash` (`string, optional`): Hyperliquid transaction hash.
- `oid` (`number, optional`): Hyperliquid order ID.
- `crossed` (`boolean, required`): Whether the order crossed the spread.
- `fee` (`string, optional`): User fee amount.
- `tid` (`number, optional`): Trade ID, when available.
- `feeToken` (`string, optional`): Token used to pay fees.
- `builder` (`string, optional`): Builder address, when present.
- `builderFee` (`string, optional`): Builder fee amount, when present.
- `user` (`string, optional`): User address; present on global, builder, and liquidation methods.
- `twapId` (`number, optional`): TWAP order ID, when present.
- `cloid` (`string, optional`): Client order ID, when present.
- `txIndex` (`number, optional`): Block-local fill event index from node_fills_by_block. Use with time for stable by-time pagination.
- `liquidation` (`object, required`): Liquidation metadata.
- `liquidation.liquidatedUser` (`string, required`): User account liquidated by the fill.
- `liquidation.markPx` (`string, required`): Mark price at liquidation.
- `liquidation.method` (`string, required`): Liquidation method, such as backstop.

## Successful Response

```json
[
  {
    "coin": "BTC",
    "px": "118136",
    "sz": "0.00009",
    "side": "B",
    "time": 1753606210273,
    "startPosition": "-1.41864",
    "dir": "Close Short",
    "closedPnl": "-0.003753",
    "hash": "0xe7822040155eaa2e737e042854342401120052bbf063906ce8c8f3babe853a79",
    "oid": 121670079265,
    "crossed": true,
    "fee": "0.005316",
    "tid": 707098367501071,
    "feeToken": "USDC",
    "builder": "0x2222222222222222222222222222222222222222",
    "builderFee": "0.000531",
    "user": "0x1111111111111111111111111111111111111111",
    "txIndex": 1,
    "liquidation": {
      "liquidatedUser": "0x3333333333333333333333333333333333333333",
      "markPx": "118000",
      "method": "backstop"
    }
  }
]
```

## 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": "builderLiquidationsByTime",
  "builder": "0x2222222222222222222222222222222222222222",
  "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": "builderLiquidationsByTime",
  "params": {
    "builder": "0x2222222222222222222222222222222222222222",
    "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.