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 provider 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.price, 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	Provider identifier
params.address	Address	Yes	User’s wallet address (viem 0x${string})
params.cursor	string	No	Pagination cursor from previous response
params.limit	number	No	Items per page. Hyperliquid: default 50, max 200. Other providers: provider-defined.
params.startTime	number	No	Filter: fills at or after this timestamp (ms)
params.endTime	number	No	Filter: fills at or 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	Executed size of this fill, in base-asset units
price	string	Fill price
liquidity	LiquidityRole	'maker' or 'taker' — whether the fill provided or removed liquidity
filledSize	string?	Same as size where the venue reports it
fee	Fee?	Fee the venue charged, as { amount, asset }. Absent when the venue reports no fee for the fill. Format amount against fee.asset, never against the fill’s quote asset.
builderFee	Fee?	Portion of fee the venue reports as the builder portion, in its own asset. Absent when the venue reports no builder portion.
clientOrderId	string?	Client order ID of the order that produced the fill, as the venue echoes it. Absent when the order carried none or the venue omits it.
leverage	DecimalString?	Leverage the account had set on the fill’s market at the moment the venue executed the fill (e.g. '10' means 10x). Absent when the venue reports no leverage on its fill payload.
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 fill’s transaction. Absent when the venue row carries no transaction hash.

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
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
"Buy"	Buy fill whose classification the SDK cannot derive (FillClassification.BUY). classifyFillFromPosition returns it for a malformed decimal.
"Sell"	Sell fill whose classification the SDK cannot derive (FillClassification.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

Throws

PerpsError with one code for the account’s access state. See Account access.

• SetupRequired — the venue needs a credential (a Lighter auth token or an Ondo session) and none is stored.
• Unauthorized — the venue rejects the credential.
• AccountNotFound — the wallet has no venue account.

An account with no fills returns an empty items list.

Data shapes: getFills — a direct-to-provider read, not a LI.FI HTTP endpoint.