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.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. 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)
TWAP	Read-side only — a running TWAP parent/child surfaced in the venue’s order feed. Placement always goes through placeTwapOrder, never a type on placeOrder.

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