> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Hyperliquid fills query builder

> Fields, filters, and ranges supported by HyperliquidFillsQueryBuilder.

`hyperliquidFillsQuery()` returns a typed `HyperliquidFillsQueryBuilder`.

```ts theme={"system"}
import { hyperliquidFillsQuery } from '@subsquid/pipes/hyperliquid'

const query = hyperliquidFillsQuery()
  .addFields({
    block: { number: true, timestamp: true },
    fill: { user: true, coin: true, px: true, sz: true, side: true },
  })
  .addFillRequest({
    range: { from: 1_057_000_000 },
    request: { coin: ['BTC'] },
  })
```

## Methods

```ts theme={"system"}
class HyperliquidFillsQueryBuilder<F extends FieldSelection = {}> {
  addFields<T>(fields: T): HyperliquidFillsQueryBuilder<F & T>
  addFillRequest(options: RequestOptions<FillRequest>): this
  includeAllBlocks(range?: Range): this
  addRange(range: PortalRange): this
  merge(query?: HyperliquidFillsQueryBuilder<F>): this
  build(options?: { setupQuery?: SetupQueryFn<HyperliquidFillsQueryBuilder<F>> }): QueryAwareTransformer
}
```

`addFields()` narrows both the TypeScript output and the fields requested from Portal. The stream always adds `block.number` and `block.hash` for cursor handling.

## Fields

| Group   | Fields                                                                                                                                                                                       |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `block` | `number`, `hash`, `parentHash`, `timestamp`                                                                                                                                                  |
| `fill`  | `fillIndex`, `user`, `coin`, `px`, `sz`, `side`, `time`, `startPosition`, `dir`, `closedPnl`, `hash`, `oid`, `crossed`, `fee`, `builderFee`, `tid`, `cloid`, `feeToken`, `builder`, `twapId` |

The fills dataset currently starts at block 750,000,000. Earlier ranges contain no records.

## Fill filters

`addFillRequest()` accepts these exact-match list filters:

| Filter     | Meaning                                            |
| ---------- | -------------------------------------------------- |
| `user`     | Trader address. Normalize user input to lowercase. |
| `coin`     | Market identifier such as `BTC`.                   |
| `dir`      | Hyperliquid direction string.                      |
| `cloid`    | Client order ID.                                   |
| `feeToken` | Fee denomination.                                  |
| `builder`  | Builder address.                                   |

Values inside one filter list are ORed. Different fields in one request are ANDed. An empty request selects all fills in the range.

## Ranges

Request ranges accept block numbers, formatted block-number strings, ISO dates, `Date` objects, and `'latest'` for `from`.

```ts theme={"system"}
type PortalRange = {
  from?: number | string | 'latest' | Date
  to?: number | string | Date
}
```

Dates are resolved through the dataset's timestamp endpoint before streaming. Resolution is at Portal chunk granularity, so a date is a coarse starting point rather than an exact timestamp boundary. Use numeric block bounds when the range must be precise. If `from` is `'latest'`, `to` must be a block number.

Use `.build()` when you want to append a query-specific `.pipe()` transform. A query builder can also be passed directly to `outputs`.

See [Handling Hyperliquid fills](../../guides/basic-development/handling-fills) for volume and row-identity guidance.


## Related topics

- [Hyperliquid fills quickstart](/en/sdk/pipes-sdk/hyperliquid/quickstart.md)
- [Handling Hyperliquid fills](/en/sdk/pipes-sdk/hyperliquid/guides/basic-development/handling-fills.md)
- [Hyperliquid](/en/data/hyperliquid/hyperliquid-fills.md)
- [Hyperliquid fills portal stream](/en/sdk/pipes-sdk/hyperliquid/reference/basic-components/source.md)
- [Hyperliquid Portal API](/en/portal/hyperliquid/overview.md)