Market Data & Providers - @lifi/perps-sdk

Public endpoints for market information. No authentication is required; an API key is optional.

GET /providers

List available perpetual provider platforms.

GET /v1/perps/providers

Parameters

Name	In	Type	Required	Description
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "providers": [
    {
      "key": "hyperliquid",
      "name": "Hyperliquid",
      "logoURI": "https://raw.githubusercontent.com/lifinance/types/main/src/assets/icons/dexes/hyperliquid.svg",
      "signingMethod": "eip712",
      "active": true,
      "funding": {
        "ratePeriodSeconds": 3600,
        "payoutCadenceSeconds": 3600
      },
      "minDepositUsd": 5,
      "setup": [
        {
          "type": "approveAgent",
          "signers": ["USER"],
          "signingMethod": "eip712",
          "title": "Allow One-Click Trading",
          "description": "Authorise a session signer so LI.FI can place orders on your behalf without prompting your wallet for every trade.",
          "params": []
        },
        {
          "type": "setReferrer",
          "signers": ["SDK"],
          "signingMethod": "eip712",
          "title": "Initialize account via LI.FI",
          "description": "Enable the LI.FI referral code to enable 4% off your fees for your first $25M of volume on Hyperliquid.",
          "params": []
        },
        {
          "type": "approveBuilderFee",
          "signers": ["USER"],
          "signingMethod": "eip712",
          "title": "Approve Builder Fee",
          "description": "Authorise the per-trade builder fee that funds LI.FI infrastructure on Hyperliquid.",
          "params": []
        }
      ],
      "options": [
        {
          "type": "accountMode",
          "signers": ["USER"],
          "signingMethod": "eip712",
          "title": "Account Mode",
          "description": "Choose how this account interacts with Hyperliquid. Unified Account uses a single spot balance for all margin assets.",
          "params": [
            {
              "name": "mode",
              "type": "string",
              "values": [
                { "value": "disabled", "label": "Disabled" },
                { "value": "unifiedAccount", "label": "Unified Account" },
                { "value": "portfolioMargin", "label": "Portfolio Margin" }
              ],
              "default": { "value": "unifiedAccount", "label": "Unified Account" }
            }
          ]
        }
      ],
      "actions": [
        { "type": "placeOrder", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "placeTriggerOrder", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "placeTwapOrder", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "cancelOrder", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "cancelTwapOrder", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "modifyOrder", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "updateLeverage", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "updatePositionMargin", "signers": ["SDK"], "signingMethod": "eip712" },
        { "type": "withdrawal", "signers": ["USER"], "signingMethod": "eip712" },
        { "type": "sendAsset", "signers": ["USER"], "signingMethod": "eip712" }
      ],
      "categories": [
        {
          "id": "hyperliquid",
          "quoteAsset": {
            "providerId": "hyperliquid",
            "id": "USDC",
            "displaySymbol": "USDC",
            "logoURI": "https://assets.li.fi/tokens/usdc.png"
          }
        },
        { "id": "xyz", "quoteAsset": null },
        { "id": "spot", "quoteAsset": null }
      ],
      "wsUrl": "wss://api.hyperliquid.xyz/ws"
    }
  ]
}

Provider Fields

Field	Type	Description
`key`	`string`	Provider identifier (e.g. `"hyperliquid"`, `"lighter"`)
`name`	`string`	Human-readable name
`logoURI`	`string`	URL to provider logo
`referralCode`	`string?`	LI.FI’s referral code for this provider, for use with the `setReferrer` setup action. Absent when not configured for the provider.
`signingMethod`	`string`	Default signing method for the provider (e.g. `"eip712"`, `"wasmBlob"`, `"evmTx"`, `"hmac"`, `"siwe"`, `"session"`)
`active`	`boolean`	When `false`, the provider is announced but not yet selectable in clients. Gates whether the widget surfaces the provider for trading.
`setup`	`ProviderAction[]`	Mandatory account-setup descriptors. The user MUST satisfy every entry before trading. An empty array means the provider has no setup gates.
`options`	`ProviderAction[]`	Optional post-setup descriptors the user MAY tune (account mode, fee tier, etc.). Never gate trading. An empty array is valid.
`actions`	`ProviderAction[]`	Trading and transfer actions advertised by the provider.
`categories`	`ProviderCategory[]`	Trading categories within the provider.
`wsUrl`	`string?`	WebSocket URL for streaming. Optional — absent for providers without WebSocket support.
`funding`	`ProviderFunding?`	Provider-wide `{ ratePeriodSeconds, payoutCadenceSeconds }` cadence metadata. Both values are seconds.
`minDepositUsd`	`number?`	Minimum deposit amount in USD that the provider’s deposit path will accept. Absent means no minimum is advertised.
`minOrderValueUsd`	`number?`	Minimum order notional value in USD. Absent means no minimum is advertised.
`minReduceOrderValueUsd`	`number?`	Minimum order notional value in USD for reduce-only orders, when the provider applies a lower floor than `minOrderValueUsd`. Absent means reduce-only orders use the same floor.
`chainId`	`number?`	Settlement chain id for the provider’s deposit/withdrawal path. Absent when not applicable.
`minWithdrawalUsd`	`number?`	Minimum withdrawal amount in USD the provider will accept. Absent means no minimum is advertised.
`depositFeeUsd`	`number?`	Flat deposit fee in USD, when the provider charges one.
`withdrawalFeeUsd`	`number?`	Flat withdrawal fee in USD, when the provider charges one.
`supportedIntervals`	`OhlcvInterval[]`	OHLCV candle intervals the provider supports (e.g. `1m`, `1h`, `1d`).

Calling a sub-route (/markets, /assets, createAction, etc.) with the key of an inactive provider fails with 400 and code: 2002 (ValidationError) rather than returning empty data.

Each ProviderCategory in categories describes a trading category within the provider:

Field	Type	Description
`id`	`string`	Category identifier (used as `categoryId` in `MarketRef` / `MarketDisplay`, e.g. `"hyperliquid"`, `"xyz"`, `"spot"`)
`logoURI`	`string?`	Category logo URL (optional)
`quoteAsset`	`Asset \| null`	Quote `Asset` for this category; `null` for the `spot` category, which has no single fixed quote
`tradeNotice`	`TradeNotice?`	Optional provider advisory shown against markets in this category

The same ProviderAction shape backs setup, options, and actions. Entries in setup and options additionally carry UI metadata (title, description) and a params array. Each params[] entry describes one input the widget collects before dispatching the action — its values array enumerates the legal value strings the action accepts, which is the source of truth for things like the mode values on accountMode and the tier values on accountType. A setup or options entry may also carry gatesAccountReads: true, marking the step whose satisfaction lets the venue authenticate account reads and account streams for the address; while that step stays unsatisfied, those reads and streams cannot start. SDK: getProviders()

GET /markets

List the tradeable markets (instruments) for a provider. Returns static instrument metadata only — ids, base/quote assets, decimals, leverage caps, and margin. Live per-market data (mark price, previous-day price, 24h volume, open interest, funding) is served by /marketsContext. Cached for one hour, since instrument metadata changes rarely.

GET /v1/perps/markets?provider=hyperliquid

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`marketIds`	query	`string`	No	Comma-separated list of provider market ids to filter (e.g., `BTC,ETH`). If omitted, every market is returned.
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "markets": [
    {
      "providerId": "hyperliquid",
      "id": "BTC",
      "categoryId": "hyperliquid",
      "baseAsset": {
        "providerId": "hyperliquid",
        "id": "BTC",
        "displaySymbol": "BTC",
        "displayName": "Bitcoin",
        "logoURI": "https://assets.li.fi/tokens/btc.png"
      },
      "quoteAsset": {
        "providerId": "hyperliquid",
        "id": "USDC",
        "displaySymbol": "USDC",
        "logoURI": "https://assets.li.fi/tokens/usdc.png"
      },
      "szDecimals": 5,
      "priceIncrement": "0.1",
      "sizeIncrement": "0.00001",
      "isDelisted": false,
      "maxLeverage": 50,
      "onlyIsolated": false,
      "positionMarginAdjustment": "ADD_AND_REMOVE",
      "maintenanceMarginRate": 0.01
    }
  ]
}

Each Market carries static metadata only — live data lives on MarketContext:

Field	Type	Description
`providerId`	`string`	Provider that owns the market (e.g., `"hyperliquid"`)
`id`	`string`	Provider’s canonical, stringified market id that uniquely identifies the trading instrument (e.g., `"BTC"`, `"xyz:PURR"`, `"@142"`; numeric on Lighter)
`categoryId`	`string`	References a `ProviderCategory` by id (e.g., `"hyperliquid"`, `"xyz"`, `"spot"`)
`baseAsset`	`Asset`	Base leg of the market (see `/assets`)
`quoteAsset`	`Asset`	Quote leg of the market
`szDecimals`	`number`	Maximum fractional precision for sizes
`priceDecimals`	`number?`	Maximum decimal places for prices, when published
`priceIncrement`	`string?`	Exact price tick when decimal places alone cannot describe the grid
`sizeIncrement`	`string?`	Exact size lot when decimal places alone cannot describe the grid
`isDelisted`	`boolean?`	`true` when the venue has delisted the market
`maxLeverage`	`number?`	Maximum allowed leverage (perps markets only)
`onlyIsolated`	`boolean?`	Whether only isolated margin is supported (perps markets only)
`positionMarginAdjustment`	`'NONE' \| 'ADD_ONLY' \| 'ADD_AND_REMOVE'`	Per-market individual margin capability (perps only)
`maintenanceMarginRate`	`number?`	Venue maintenance-margin rate as a fraction (perps only)
`maxMarketOrderUsd`	`string?`	Maximum market order size in USD, when the venue publishes a cap (perps only)
`maxLimitOrderUsd`	`string?`	Maximum limit order size in USD, when the venue publishes a cap (perps only)

SDK: getMarkets()

GET /assets

List the underlying asset registry for a provider. An asset is a transferable balance unit (Lighter’s asset_id namespace), not a tradable market — markets reference assets as their base/quote legs. Providers whose ledger deltas already carry the asset symbol inline (Hyperliquid) return an empty array.

GET /v1/perps/assets?provider=lighter

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "assets": [
    {
      "providerId": "lighter",
      "id": "1",
      "displaySymbol": "USDC",
      "displayName": "USD Coin",
      "logoURI": "https://assets.li.fi/tokens/usdc.png",
      "decimals": 6,
      "l1Decimals": 6,
      "l1Address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "minWithdrawalAmount": "1.0"
    }
  ]
}

Each Asset:

Field	Type	Description
`providerId`	`string`	Provider that owns the asset (e.g., `"lighter"`)
`id`	`string`	Provider 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., `"USDC"`, `"BTC"`)
`logoURI`	`string`	URL to asset logo
`displayName`	`string?`	Full asset name (e.g., `"USD Coin"`)
`tags`	`string[]?`	Curated search/grouping slugs
`aliases`	`string[]?`	Other venues’ display symbols for the same asset
`decimals`	`number?`	Venue integer-wire precision
`l1Decimals`	`number?`	L1 token contract precision
`l1Address`	`string?`	L1 token address; zero address denotes native gas
`minWithdrawalAmount`	`string?`	Per-withdrawal venue minimum in this asset’s units

SDK: getAssets()

GET /marketsContext

Get 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 /markets. Cached for one second.

GET /v1/perps/marketsContext?provider=hyperliquid

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`marketIds`	query	`string`	No	Comma-separated list of provider market ids to filter (e.g., `BTC,ETH`)
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "prices": [
    {
      "marketId": "BTC",
      "midPrice": "95000.50",
      "markPrice": "95000.50",
      "oraclePrice": "95001.00",
      "prevDayPrice": "94200.00",
      "priceChange24h": "800.50",
      "volume24h": "5000000000",
      "marketCap": "1870000000000",
      "openInterest": "1250000000",
      "funding": {
        "rate": "0.0001",
        "nextFundingTime": 1704110400000
      }
    }
  ]
}

Each MarketContext:

Field	Type	Description
`marketId`	`string`	Provider 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). `funding.nextFundingTime` is `0` when the venue does not expose this timestamp for the market.

SDK: getMarketsContext()

GET /ohlcv

Get OHLCV candle data for charts.

GET /v1/perps/ohlcv?provider=hyperliquid&marketId=BTC&interval=1h&limit=100

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`marketId`	query	`string`	Yes	Provider market id
`interval`	query	`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
`startTime`	query	`integer`	No	Start timestamp (ms)
`endTime`	query	`integer`	No	End timestamp (ms)
`limit`	query	`integer`	No	Max candles (default 100, max 1000)
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "provider": "hyperliquid",
  "marketId": "BTC",
  "interval": "1h",
  "candles": [
    {
      "t": 1704067200000,
      "o": "94500.00",
      "h": "95200.00",
      "l": "94300.00",
      "c": "95000.50",
      "v": "125000000"
    }
  ]
}

Response `404`

Market not found error. SDK: getOhlcv()

GET /orderbook

Get current orderbook snapshot.

GET /v1/perps/orderbook?provider=hyperliquid&marketId=BTC&depth=20

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Provider identifier
`marketId`	query	`string`	Yes	Provider market id
`depth`	query	`integer`	No	Price levels (default 20, max 100)
`priceStep`	query	`number`	No	Price-bucket size, in quote units, to aggregate levels into. Only honored by providers that support server-side orderbook aggregation (e.g. Hyperliquid); ignored elsewhere.
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "provider": "hyperliquid",
  "marketId": "BTC",
  "bids": [
    { "price": "94999.00", "size": "1.5" },
    { "price": "94998.00", "size": "2.3" }
  ],
  "asks": [
    { "price": "95001.00", "size": "0.8" },
    { "price": "95002.00", "size": "1.2" }
  ],
  "timestamp": 1704067200000
}

Response `404`

Market not found error. SDK: getOrderbook()

GET /meta

Get read-only platform metadata: the backend version and the list of active platform-level notices (advisories shown to all users, independent of any provider or market). Cached for one minute.

GET /v1/perps/meta

Parameters

Name	In	Type	Required	Description
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "version": "1.4.2",
  "notices": [
    {
      "timestamp": 1704067200000,
      "title": "Scheduled maintenance",
      "message": "Trading will pause briefly at 02:00 UTC.",
      "link": "https://status.li.fi"
    }
  ]
}

Meta:

Field	Type	Description
`version`	`string`	Backend version
`notices`	`Notice[]`	Active platform-level advisories

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; rendered as a hyperlink when present

GET /meta/terms

Get the current terms-of-service document and whether an address has accepted that version. When the address has not accepted, accepted is false and acceptedAt is omitted.

GET /v1/perps/meta/terms?address=0x1234567890abcdef1234567890abcdef12345678

Parameters

Name	In	Type	Required	Description
`address`	query	`string`	Yes	Wallet address to check acceptance for
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "termsVersion": "2026-01-01",
  "content": "By using this service you agree to ...",
  "accepted": true,
  "acceptedAt": 1704067200000
}

TermsAcceptanceStatus:

Field	Type	Description
`termsVersion`	`string`	Backend-owned version identifier for the current terms
`content`	`string`	Full current terms-of-service text
`accepted`	`boolean`	Whether the queried address has accepted `termsVersion`
`acceptedAt`	`number?`	Unix epoch milliseconds the address accepted; absent when not accepted

GET /meta/referral

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.

GET /v1/perps/meta/referral?address=0x1234567890abcdef1234567890abcdef12345678

Parameters

Name	In	Type	Required	Description
`address`	query	`string`	Yes	Address to resolve
`code`	query	`string`	No	Candidate code to validate in the same read; reflected in the response’s `candidate` verdict
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "termsVersion": "2026-01-01",
  "termsAccepted": true,
  "ownedCodeEligibility": { "eligible": true }
}

ReferralStatus:

Field	Type	Description
`address`	`string`	Queried address
`termsVersion`	`string`	Backend-owned version identifier for the current terms
`termsAccepted`	`boolean`	Whether the address has accepted `termsVersion`
`attachedCode`	`{ code, attachedAt }?`	The referral code attached to this address, when one is
`ownedCode`	`{ code, createdAt, attachedCount }?`	The referral code this address owns, when it has created one
`ownedCodeEligibility`	`{ eligible, requiredNotional?, currentNotional? }`	Whether the address may create an owned code
`candidate`	`{ code, valid, normalizedCode?, rejection? }?`	Verdict on the `code` query param, when supplied — see Referral code validation
`onboarding`	`{ termsVersion?, referralCode? }?`	Composite onboarding state for `metaOnboard`, when applicable

Response `400`

ValidationError — malformed address or code.

GET /meta/referral/activity

Get the addresses attached to address’s owned internal referral code, paginated. Provider-independent.

GET /v1/perps/meta/referral/activity?address=0x1234567890abcdef1234567890abcdef12345678&limit=50

Parameters

Name	In	Type	Required	Description
`address`	query	`string`	Yes	Address whose owned code’s attachments to list
`limit`	query	`integer`	No	Maximum items returned (0-100); backend default and cap apply
`cursor`	query	`string`	No	Pagination cursor from the previous response
`x-lifi-api-key`	header	`string`	No	API key (optional). See Authentication.
`x-lifi-integrator`	header	`string`	No	Optional integrator assertion (non-authoritative). See Authentication.

Response `200`

{
  "items": [
    { "address": "0xabcdef1234567890abcdef1234567890abcdef12", "attachedAt": 1704067200000, "notional": "15000.00" }
  ],
  "pagination": { "limit": 50, "hasMore": false }
}

ReferralActivityResponse:

Field	Type	Description
`items`	`ReferralActivityItem[]`	Addresses attached to the owned code, most recent first. Empty when the address owns no code.
`pagination`	`Pagination`	`{ limit, hasMore, cursor? }`

Each ReferralActivityItem:

Field	Type	Description
`address`	`string`	Attached address
`attachedAt`	`number`	Unix epoch milliseconds the code was attached
`notional`	`string`	Cumulative traded notional attributed to the attachment

Response `400`

ValidationError — malformed address, limit, or cursor.

​GET /providers

​Parameters

​Response 200

​Provider Fields

​GET /markets

​Parameters

​Response 200

​GET /assets

​Parameters

​Response 200

​GET /marketsContext

​Parameters

​Response 200

​GET /ohlcv

​Parameters

​Response 200

​Response 404

​GET /orderbook

​Parameters

​Response 200

​Response 404

​GET /meta

​Parameters

​Response 200

​GET /meta/terms

​Parameters

​Response 200

​GET /meta/referral

​Parameters

​Response 200

​Response 400

​GET /meta/referral/activity

​Parameters

​Response 200

​Response 400

GET /providers

Parameters

Response `200`

Provider Fields

GET /markets

Parameters

Response `200`

GET /assets

Parameters

Response `200`

GET /marketsContext

Parameters

Response `200`

GET /ohlcv

Parameters

Response `200`

Response `404`

GET /orderbook

Parameters

Response `200`

Response `404`

GET /meta

Parameters

Response `200`

GET /meta/terms

Parameters

Response `200`

GET /meta/referral

Parameters

Response `200`

Response `400`

GET /meta/referral/activity

Parameters

Response `200`

Response `400`