Assets

Fetch tradeable assets, prices, OHLCV candles, and orderbooks

Fetch asset details, prices, OHLCV chart data, and orderbook snapshots.

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

getAssets

Returns the token/asset registry for a specified DEX — the base entities referenced by markets (as base/quote legs) and by account balances. Static market metadata (leverage, margin) lives on Market via getMarkets; live data (mark price, funding) lives on MarketContext via getMarketsContext.

import { getAssets } from '@lifi/perps-sdk';

const { assets } = await getAssets(client, { provider: 'hyperliquid' });

for (const asset of assets) {
  console.log(asset.id, asset.displaySymbol);
}
// BTC BTC
// ETH ETH

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
options	SDKRequestOptions	No	Request options

Returns

AssetsResponse — { assets: Asset[] }:

Each Asset:

Field	Type	Description
providerId	string	Provider that minted this asset
id	string	Provider’s own asset id. Lighter: numeric asset_id stringified. Hyperliquid spot: the venue token index, never the coin symbol (that lives in displaySymbol).
displaySymbol	string	UI-friendly base symbol (e.g., "BTC", "PURR")
logoURI	string	URL to asset logo
displayName	string?	Full asset name (e.g., "Bitcoin")
tags	string[]?	Curated lowercase-kebab slugs used for search and grouping
aliases	string[]?	Display symbols used by other venues for the same real-world asset
decimals	number?	Venue wire precision for this asset
l1Decimals	number?	L1 token-contract precision, which can differ from venue precision
l1Address	string?	L1 token address; the zero address denotes native gas
minWithdrawalAmount	string?	Venue minimum for one withdrawal, denominated in this asset rather than USD

API Reference: GET /assets

---

getMarkets

Returns all tradeable markets for a specified DEX as static instrument metadata — ids, base/quote assets, decimals, leverage, and margin. Live data (mark price, funding, open interest, volume) comes from getMarketsContext.

import { getMarkets } from '@lifi/perps-sdk';

const { markets } = await getMarkets(client, { provider: 'hyperliquid' });

for (const market of markets) {
  console.log(market.baseAsset.displaySymbol, market.maxLeverage);
}
// BTC 50
// ETH 50

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
params.marketIds	string[]	No	Filter to specific markets by the canonical Market.id (not display symbols)
options	SDKRequestOptions	No	Request options

Returns

MarketsResponse — { markets: Market[] }. A Market is either a PerpsMarket or a SpotMarket; both extend BaseMarket:

Field	Type	Description
providerId	string	Provider that owns this market
id	string	Provider’s canonical, stringified market id that uniquely identifies the trading instrument; referenced elsewhere as marketId
categoryId	string	References a ProviderCategory by id
baseAsset	Asset	Base leg
quoteAsset	Asset	Quote leg
szDecimals	number	Size decimal places
priceDecimals	number?	Price decimal places, when the provider publishes them
isDelisted	boolean?	Whether the venue has delisted the market. Treat only true as delisted.
priceIncrement	string?	Exact price tick as a decimal string when priceDecimals alone cannot describe the venue grid
sizeIncrement	string?	Exact size lot as a decimal string when szDecimals alone cannot describe the venue grid

PerpsMarket adds:

Field	Type	Description
maxLeverage	number	Maximum allowed leverage
onlyIsolated	boolean	Whether only isolated margin is supported
maintenanceMarginRate	number?	Maintenance margin requirement as a fraction (e.g. 0.012 = 1.2%), when the provider publishes it
positionMarginAdjustment	PositionMarginAdjustment	Per-market capability: NONE, ADD_ONLY, or ADD_AND_REMOVE
maxMarketOrderUsd	string?	Maximum market order size in USD, when the venue publishes a cap
maxLimitOrderUsd	string?	Maximum limit order size in USD, when the venue publishes a cap

Live per-market data (mark price, previous-day price, 24h volume, open interest, funding) comes from getMarketsContext.

API Reference: GET /markets

---

getMarket

Returns a single market by its canonical marketId.

import { getMarket } from '@lifi/perps-sdk';

const btc = await getMarket(client, { provider: 'hyperliquid', marketId: 'BTC' });
console.log(btc.baseAsset.displaySymbol, btc.maxLeverage);
// BTC 50

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
params.marketId	string	Yes	The canonical Market.id (not the display symbol)
options	SDKRequestOptions	No	Request options

Returns

Market — single market object (same shape as above).

API Reference: GET /markets

---

Default market

DEFAULT_MARKET_ID gives the market a caller lands on when it names none, keyed by provider and given as the venue’s own Market.id:

import { DEFAULT_MARKET_ID, getDefaultMarketId } from '@lifi/perps-sdk';

DEFAULT_MARKET_ID.hyperliquid; // 'BTC'
DEFAULT_MARKET_ID.lighter;     // '1'
DEFAULT_MARKET_ID.ondo;        // 'BTC-USD.P'

getDefaultMarketId('hyperliquid'); // 'BTC'

getDefaultMarketId(provider: DefaultMarketProvider): string reads a single provider’s default market id from DEFAULT_MARKET_ID. DefaultMarketProvider is 'hyperliquid' | 'lighter' | 'ondo'. Each value is a fixed deployment fact, so it needs no runtime lookup.

---

getMarketsContext

Returns live per-market context for all markets: midPrice, markPrice, and (where the venue publishes it) oraclePrice; prevDayPrice, priceChange24h, and volume24h for every market; marketCap where the venue publishes circulating supply; and openInterest and funding for perps. Intended for frequent polling; pair it with the static metadata from getMarkets.

import { getMarketsContext } from '@lifi/perps-sdk';

const { prices } = await getMarketsContext(client, { provider: 'hyperliquid' });
for (const p of prices) {
  console.log(p.marketId, p.midPrice, p.markPrice);
}
// 0 95000.50 95000.50
// 1 3200.25 3200.25

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
params.marketIds	string[]	No	Filter to specific markets by the canonical Market.id (not display symbols)
options	SDKRequestOptions	No	Request options

Returns

PricesResponse — { prices: MarketContext[] }:

Each MarketContext:

Field	Type	Description
marketId	string	The canonical Market.id
midPrice	string	Current mid price
markPrice	string	Current mark price
oraclePrice	string?	Venue oracle/index price, where the venue publishes one
prevDayPrice	string?	Previous day’s price
priceChange24h	string?	24-hour price change
volume24h	string?	24-hour trading volume in USD
marketCap	string?	Market capitalization, where the venue publishes circulating supply
openInterest	string?	Total open interest in USD (perps markets only)
funding	FundingInfo?	Current funding rate and next funding time (perps markets only)

API Reference: GET /marketsContext

---

getOhlcv

Returns OHLCV candle data for charts.

import { getOhlcv } from '@lifi/perps-sdk';

const { candles } = await getOhlcv(client, {
  provider: 'hyperliquid',
  marketId: 'BTC',
  interval: '1h',
  limit: 100,
});

for (const candle of candles) {
  console.log(candle.t, candle.o, candle.h, candle.l, candle.c, candle.v);
}

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
params.marketId	string	Yes	The canonical Market.id
params.interval	string	Yes	Candle interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M. Each provider supports only a subset — see the provider’s page (for example Lighter or Ondo) for the intervals it accepts
params.startTime	number	No	Start timestamp in milliseconds
params.endTime	number	No	End timestamp in milliseconds
params.limit	number	No	Max candles to return (default 100, max 1000)
options	SDKRequestOptions	No	Request options

Returns

OhlcvResponse:

Field	Type	Description
provider	string	Provider identifier
marketId	string	The canonical Market.id
interval	string	Candle interval
candles	Candle[]	Array of candle data

Each Candle:

Field	Type	Description
t	number	Timestamp in milliseconds
o	string	Open price
h	string	High price
l	string	Low price
c	string	Close price
v	string	Volume

API Reference: GET /ohlcv

---

getOrderbook

Returns current orderbook snapshot with bids and asks.

import { getOrderbook } from '@lifi/perps-sdk';

const book = await getOrderbook(client, {
  provider: 'hyperliquid',
  marketId: 'BTC',
  depth: 20,
});

console.log('Best bid:', book.bids[0].price, book.bids[0].size);
console.log('Best ask:', book.asks[0].price, book.asks[0].size);

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.provider	string	Yes	Provider identifier
params.marketId	string	Yes	The canonical Market.id
params.depth	number	No	Number of price levels. The default varies by DEX; there is no fixed maximum.
options	SDKRequestOptions	No	Request options

Returns

OrderbookResponse:

Field	Type	Description
provider	string	Provider identifier
marketId	string	The canonical Market.id
bids	OrderbookLevel[]	Bid price levels (descending)
asks	OrderbookLevel[]	Ask price levels (ascending)
timestamp	number	Snapshot timestamp in milliseconds

Each OrderbookLevel:

Field	Type	Description
price	string	Price level
size	string	Size at this price level

API Reference: GET /orderbook

---

getMeta

Get platform metadata: the backend version and the list of active platform-level notices. Provider-independent — reads the platform meta surface, so it takes no provider.

import { getMeta } from '@lifi/perps-sdk';

const { version, notices } = await getMeta(client);

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
options	SDKRequestOptions	No	Request options

Returns

Meta — { version: string; notices: Notice[] }.

API Reference: GET /meta

getTermsAcceptance

Get the current terms-of-service document (version + full content) and whether a given address has accepted that version. Provider-independent — reads the platform meta surface.

import { getTermsAcceptance } from '@lifi/perps-sdk';

const terms = await getTermsAcceptance(client, '0x1234...');
if (!terms.accepted) {
  // prompt the user to accept terms.content (version terms.termsVersion)
}

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
address	Address	Yes	Address whose acceptance status to resolve
options	SDKRequestOptions	No	Request options

Returns

TermsAcceptanceStatus — { termsVersion: string; content: string; accepted: boolean; acceptedAt?: number }.

API Reference: GET /meta/terms

getReferralStatus

Get an address’s onboarding and internal-referral state: terms acceptance, its attached and owned codes, whether it may create a code, and the verdict on a candidate code. Provider-independent — reads the platform meta surface.

import { getReferralStatus } from '@lifi/perps-sdk';

const status = await getReferralStatus(client, { address: userAddress, code: 'ABC123' });

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.address	Address	Yes	Address to resolve
params.code	string	No	Candidate code to validate in the same read; reflected in the response’s candidate verdict
options	SDKRequestOptions	No	Request options

Returns

ReferralStatus — { address, termsVersion, termsAccepted, attachedCode?, ownedCode?, ownedCodeEligibility, candidate?, onboarding? }. An address the backend holds no record for resolves to termsAccepted: false with the optional fields absent.

Referral code validation

candidate is a ReferralCodeValidation verdict on the code query param: { code, valid, normalizedCode?, rejection? }. code echoes the candidate, valid reports whether the backend accepts it, normalizedCode carries the backend’s canonical form when it differs from code, and rejection names the reason when valid is false.

rejection is a ReferralCodeRejection value:

Value	Description
MALFORMED	The code fails the wire format the backend requires
NOT_FOUND	No owned code matches the candidate
INACTIVE	The matching code exists but is not currently active
SELF_REFERRAL	The candidate is the querying address’s own code
ALREADY_ATTACHED	The address already has a code attached
NOT_ELIGIBLE	The address does not meet the backend’s eligibility requirements for attaching a code

getReferralActivity

Get the addresses attached to address’s owned internal referral code, paginated. Provider-independent — reads the platform meta surface.

import { getReferralActivity } from '@lifi/perps-sdk';

const { items, pagination } = await getReferralActivity(client, { address: userAddress, limit: 50 });

Parameters

Parameter	Type	Required	Description
client	PerpsSDKClient	Yes	SDK client
params.address	Address	Yes	Address whose owned code’s attachments to list
params.limit	number	No	Maximum items returned; backend defaults and caps apply
params.cursor	string	No	Pagination cursor from the previous response
options	SDKRequestOptions	No	Request options

Returns

ReferralActivityResponse — { items: ReferralActivityItem[]; pagination: Pagination }. Each item is { address, attachedAt, notional }. An address that owns no code resolves to items: [].