getFills

Fetch historical fills with pagination and time filtering

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

The examples on this page use Hyperliquid (provider: 'hyperliquid'). Replace the provider value with any supported DEX from getProviders().

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.asset.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
asset	AssetDisplay	Asset identity
side	'BUY' | 'SELL'	Order direction
type	OrderType	Order type
size	string	Original order size
price	string	Fill price
status	FillStatus	FILLED, PARTIALLY_FILLED, CANCELLED, REJECTED
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

FillClassification

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?	Full URL for next page (may be absent)

API Reference: GET /fills