Market Data & Providers - @lifi/perps-sdk

Public endpoints for market information. No authentication required beyond the API key header.

GET /providers

List available perpetual provider platforms.

GET /v1/perps/providers

Parameters

Name	In	Type	Required	Description
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

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,
      "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": "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", "AGENT"],
          "signingMethod": "eip712",
          "title": "Account Mode",
          "description": "Choose how this account interacts with Hyperliquid. Defaults to Unified Account, which routes trading and balances through one shared margin pool.",
          "params": [
            {
              "name": "mode",
              "type": "string",
              "values": [
                { "value": "disabled", "label": "Disabled" },
                { "value": "dexAbstraction", "label": "Dex Abstraction" },
                { "value": "unifiedAccount", "label": "Unified Account" }
              ],
              "default": { "value": "unifiedAccount", "label": "Unified Account" }
            }
          ]
        }
      ],
      "actions": [
        { "type": "placeOrder", "signers": ["AGENT"], "signingMethod": "eip712" },
        { "type": "placeTriggerOrder", "signers": ["AGENT"], "signingMethod": "eip712" },
        { "type": "cancelOrder", "signers": ["AGENT"], "signingMethod": "eip712" },
        { "type": "modifyOrder", "signers": ["AGENT"], "signingMethod": "eip712" },
        { "type": "updateLeverage", "signers": ["AGENT"], "signingMethod": "eip712" },
        { "type": "updatePositionMargin", "signers": ["AGENT"], "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
`signingMethod`	`string`	Default signing method for the provider (e.g. `"eip712"`, `"wasmBlob"`)
`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.
`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.

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. 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 /prices. 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`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

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,
      "maxLeverage": 50,
      "onlyIsolated": false
    }
  ]
}

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

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`	Size decimal places
`maxLeverage`	`number?`	Maximum allowed leverage (perps markets only)
`onlyIsolated`	`boolean?`	Whether only isolated margin is supported (perps markets 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`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

{
  "assets": [
    {
      "providerId": "lighter",
      "id": "1",
      "displaySymbol": "USDC",
      "displayName": "USD Coin",
      "logoURI": "https://assets.li.fi/tokens/usdc.png"
    }
  ]
}

Each Asset:

Field	Type	Description
`providerId`	`string`	Provider that owns the asset (e.g., `"lighter"`)
`id`	`string`	Provider-minted asset id (Lighter’s numeric `asset_id` stringified; Hyperliquid coin symbol)
`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"`)

SDK: getAssets()

GET /prices

Get live per-market data for all markets: the mid price, markPrice, prevDayPrice, and volume24h for every market, plus openInterest and funding for perps. Intended for frequent polling; pair it with the static metadata from /markets. Cached for one second.

GET /v1/perps/prices?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`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

Response `200`

{
  "prices": [
    {
      "marketId": "BTC",
      "price": "95000.50",
      "markPrice": "95000.50",
      "prevDayPrice": "94200.00",
      "volume24h": "5000000000",
      "openInterest": "1250000000",
      "funding": {
        "rate": "0.0001",
        "nextFundingTime": 1704110400000
      }
    }
  ]
}

Each MarketPrice:

Field	Type	Description
`marketId`	`string`	Provider market id
`price`	`string`	Current mid price
`markPrice`	`string`	Current mark price
`prevDayPrice`	`string?`	Previous day’s price
`volume24h`	`string?`	24-hour trading volume in USD
`openInterest`	`string?`	Total open interest in USD (perps markets only)
`funding`	`FundingInfo?`	Current funding rate and next funding time (perps markets only)

SDK: getPrices()

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`
`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`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

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)
`x-lifi-api-key`	header	`string`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

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`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

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`	Yes	API key
`x-lifi-integrator`	header	`string`	No	Integrator identifier

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 /providers

​Parameters

​Response 200

​Provider Fields

​GET /markets

​Parameters

​Response 200

​GET /assets

​Parameters

​Response 200

​GET /prices

​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 /providers

Parameters

Response `200`

Provider Fields

GET /markets

Parameters

Response `200`

GET /assets

Parameters

Response `200`

GET /prices

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`