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

# HyperCore Fills

> Access Hyperliquid perpetual futures fills data

HyperCore Fills provides access to all trade execution data from Hyperliquid's perpetual futures exchange.

## Network Information

* **Dataset ID**: `hyperliquid-fills`
* **Type**: HyperCore
* **Status**: Real-time
* **Base URL**: `https://portal.sqd.dev/datasets/hyperliquid-fills`

## Available Data

This dataset provides comprehensive fills data including:

* **Trade Fills**: Complete execution data with price, size, side, and direction
* **Position Changes**: Track position sizes and realized PnL on closing trades
* **Builder Routing**: Monitor trades routed through specific builders with fee information
* **User Activity**: Filter by user address to analyze trader behavior

## Quick Start

Query fills for a specific asset:

```bash theme={"system"}
curl --compressed -X POST "https://portal.sqd.dev/datasets/hyperliquid-fills/stream" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "hyperliquidFills",
    "fromBlock": 900000000,
    "toBlock": 900000100,
    "fields": {
      "block": {
        "number": true,
        "timestamp": true
      },
      "fill": {
        "user": true,
        "coin": true,
        "px": true,
        "sz": true,
        "side": true,
        "dir": true,
        "fee": true
      }
    },
    "fills": [{
      "coin": ["BTC"]
    }]
  }'
```

## Fill Fields

Select fill columns under `fields.fill`. A field is only present in the response if you list it here. For example, `coin` is absent unless requested.

| Field       | Meaning                                                                     |
| ----------- | --------------------------------------------------------------------------- |
| `user`      | Trader wallet address                                                       |
| `coin`      | Asset symbol (e.g. `BTC`, `ETH`)                                            |
| `side`      | `A` = ask (sell), `B` = bid (buy)                                           |
| `dir`       | Trade direction: `Open Long`, `Close Long`, `Open Short`, `Close Short`     |
| `px`        | Fill price (decimal string)                                                 |
| `sz`        | Fill size (decimal string)                                                  |
| `fee`       | **Signed** fee: positive = taker fee paid, negative = maker rebate received |
| `closedPnl` | Realized PnL booked on closing fills (zero on opening fills)                |
| `crossed`   | `true` = taker/aggressor side, `false` = resting maker side                 |
| `tid`       | Trade ID **shared by the two sides** of one execution                       |

<Note>
  **Pairing maker and taker.** Each execution produces two fill rows that share the same `tid` at the same `px`/`sz`: one with `crossed: true` (taker) and one with `crossed: false` (maker). `tid` is the reliable key to pair them.

  **Computing net realized PnL.** `closedPnl` is gross of fees. Net realized PnL for a trader is `sum(closedPnl) - sum(fee)`, and because `fee` is signed, maker rebates (negative fees) add to the total automatically. For builder-routed fills, also subtract `sum(builderFee)` (request it with the `builderFee` field), since it is an additional fee charged on top of `fee`.
</Note>

## Resources

<CardGroup cols={2}>
  <Card title="OpenAPI Schema" icon="file-code" href="https://docs.sqd.dev/en/api/catalog/hyperliquid/openapi-fills.yaml">
    Full request and response schema for the fills dataset
  </Card>

  <Card title="Examples" icon="code" href="/en/portal/hyperliquid/examples/track-trader-fills">
    Interactive examples for common use cases
  </Card>
</CardGroup>