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

# getFills

> Fetch historical fills with pagination and time filtering

Returns paginated historical fills. Results are sorted by creation time, newest first.

<Info>
  The examples on this page use **Hyperliquid** (`provider: 'hyperliquid'`). Replace the `provider` value with any supported DEX from `getProviders()`.
</Info>

```typescript theme={null}
import { getFills } from '@lifi/perps-sdk';

const fills = await getFills(client, {
  provider: 'hyperliquid',
  address: userAddress,
  limit: 50,
});

for (const item of fills.items) {
  console.log(item.market.baseAsset.displaySymbol, item.side, item.status, item.classification);
}

// Pagination
if (fills.pagination.hasMore) {
  const nextPage = await getFills(client, {
    provider: 'hyperliquid',
    address: userAddress,
    cursor: fills.pagination.cursor,
  });
}
```

## Parameters

| Parameter          | Type                | Required | Description                              |
| ------------------ | ------------------- | -------- | ---------------------------------------- |
| `client`           | `PerpsSDKClient`    | Yes      | SDK client                               |
| `params.provider`  | `string`            | Yes      | DEX identifier                           |
| `params.address`   | `string`            | Yes      | User's wallet address                    |
| `params.cursor`    | `string`            | No       | Pagination cursor from previous response |
| `params.limit`     | `number`            | No       | Items per page (default 50, max 100)     |
| `params.startTime` | `number`            | No       | Filter: fills after this timestamp (ms)  |
| `params.endTime`   | `number`            | No       | Filter: fills before this timestamp (ms) |
| `options`          | `SDKRequestOptions` | No       | Request options                          |

## Returns

`FillsResponse`:

| Field        | Type         | Description         |
| ------------ | ------------ | ------------------- |
| `provider`   | `string`     | Provider identifier |
| `items`      | `Fill[]`     | Historical fills    |
| `pagination` | `Pagination` | Pagination metadata |

## Fill fields

| Field            | Type                 | Description                                                                                                                                                  |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | `string`             | Fill ID                                                                                                                                                      |
| `orderId`        | `string`             | ID of the parent order                                                                                                                                       |
| `market`         | `MarketDisplay`      | Market identity. Display symbol is `market.baseAsset.displaySymbol`.                                                                                         |
| `side`           | `'BUY' \| 'SELL'`    | Order direction                                                                                                                                              |
| `type`           | `OrderType?`         | Order type — see [OrderType](#ordertype). Absent when the provider's fill payload doesn't carry it and it can't be inferred (e.g. a Hyperliquid taker fill). |
| `size`           | `string`             | Original order size                                                                                                                                          |
| `price`          | `string`             | Fill price                                                                                                                                                   |
| `status`         | `FillStatus`         | `FILLED`, `PARTIALLY_FILLED`, `CANCELLED`, `REJECTED`                                                                                                        |
| `liquidity`      | `LiquidityRole`      | `'maker'` or `'taker'` — whether the fill provided or removed liquidity                                                                                      |
| `filledSize`     | `string?`            | Amount filled (absent if no fills yet)                                                                                                                       |
| `fee`            | `string?`            | Total fees paid (absent if no fills yet)                                                                                                                     |
| `realizedPnl`    | `string \| null?`    | Realized PnL (present only when closing a position, `null` otherwise)                                                                                        |
| `startPosition`  | `string?`            | Position size before this fill                                                                                                                               |
| `classification` | `FillClassification` | How this fill affected the position                                                                                                                          |
| `createdAt`      | `string`             | ISO 8601 timestamp                                                                                                                                           |
| `explorerLink`   | `string?`            | Block-explorer URL for the settling on-chain tx. Absent when the fill has no on-chain tx (every Hyperliquid fill is off-chain).                              |

## OrderType

| Value                | Description                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `MARKET`             | Market order — executes immediately at the best available price                                                                           |
| `LIMIT`              | Limit order — rests until filled, cancelled, or expired                                                                                   |
| `STOP_MARKET`        | Stop-market — converts to a market order when the trigger price is hit                                                                    |
| `STOP_LIMIT`         | Stop-limit — converts to a limit order when the trigger price is hit                                                                      |
| `TAKE_PROFIT_MARKET` | Take-profit market order                                                                                                                  |
| `TAKE_PROFIT_LIMIT`  | Take-profit limit order                                                                                                                   |
| `TRIGGER_ONLY`       | Trigger-only order (provider-specific; e.g., Lighter's bare-trigger marker for orders whose final type is decided when the trigger fires) |

## FillClassification

Wire values are Title Case strings; the SDK exports the `FillClassification` enum from `@lifi/perps-sdk` (keys: `OPENED_LONG`, `OPENED_SHORT`, ...) whose values match these strings.

| Value               | Description                           |
| ------------------- | ------------------------------------- |
| `"Opened Long"`     | Opened a new long position from zero  |
| `"Opened Short"`    | Opened a new short position from zero |
| `"Increased Long"`  | Added to an existing long position    |
| `"Increased Short"` | Added to an existing short position   |
| `"Reduced Long"`    | Partially closed a long position      |
| `"Reduced Short"`   | Partially closed a short position     |
| `"Closed Long"`     | Fully closed a long position          |
| `"Closed Short"`    | Fully closed a short position         |
| `"Switched Long"`   | Closed a short and opened a long      |
| `"Switched Short"`  | Closed a long and opened a short      |
| `"Spot Buy"`        | Spot market buy                       |
| `"Spot Sell"`       | Spot market sell                      |

## Pagination fields

| Field     | Type      | Description                                                    |
| --------- | --------- | -------------------------------------------------------------- |
| `limit`   | `number`  | Items per page                                                 |
| `hasMore` | `boolean` | Whether more pages exist — use this as the authoritative check |
| `cursor`  | `string?` | Cursor for next page (pass to `getFills` for the next page)    |
| `nextUrl` | `string?` | Pre-built URL for the next page, when the provider returns one |

**API Reference:** [GET /fills](/api-reference/account#getfills)