Market Data

Fetch markets, prices, OHLCV candles, orderbooks, platform metadata, and referral state

Fetch asset and market details, prices, OHLCV chart data, orderbook snapshots, platform metadata, and referral state.

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

​

getAssets

Returns the token/asset registry for a specified provider — 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 issues 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 the active markets for a specified provider as static instrument metadata — ids, base/quote assets, decimals, leverage, and margin. Delisted markets are dropped by the SDK and never appear in the result. 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) {
  if ('maxLeverage' in market) {
    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. getMarkets and getMarket never return a delisted market; the flag matters on market objects obtained elsewhere, such as those embedded in positions.
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

Do not apply priceDecimals, priceIncrement, or sizeIncrement directly to order values. Prices and sizes must sit on the venue grid or the order is rejected, so format them through the provider plugin — see Provider plugin snapping.

PerpsMarket adds:

Field	Type	Description
maxLeverage	number	Maximum allowed leverage
onlyIsolated	boolean	Whether only isolated margin is supported
maintenanceMarginRate	DecimalString?	Maintenance margin requirement as a fraction (e.g. '0.012' = 1.2%), when the provider publishes it
defaultLeverage	number?	Leverage the venue applies to the market before the user sets one, 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
minOrderValueUsd	string?	Per-market minimum order notional in USD, as a decimal string. Lighter applies it to resting (post-only) orders only. Separate from the venue-wide Provider.minOrderValueUsd, which is also a decimal string; parse both before you compare them.
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. The result is the Market union (PerpsMarket | SpotMarket), so narrow it before reading perps-only fields such as maxLeverage. Throws PerpsError with code MarketNotFound (2023) when the id is unknown or the market is delisted.

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

const btc = await getMarket(client, { provider: 'hyperliquid', marketId: 'BTC' });
if ('maxLeverage' in 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);
}
// BTC 95000.50 95000.50
// ETH 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	OhlcvInterval	Yes	Candle interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M. Each provider supports only a subset — see Provider.supportedIntervals and 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	OhlcvInterval	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: an integer from 1 to 100. Defaults to 20.
params.priceStep	number	No	Price-bucket width in quote units. Honoured by providers that aggregate server-side (Hyperliquid); ignored otherwise.
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[] }. Each Notice:

Field	Type	Description
timestamp	number	Unix epoch milliseconds
title	string	Notice title
message	string	Notice body
link	string?	URL the notice links to

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.

onboarding is the one onboarding step the address still has to sign: { termsVersion?, referralCode? }, where each present field is carried by the step. Pass the same values to submitOnboarding. It is absent when the backend requires no consent from this address.

​

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: [].