Market Data & Providers

Public endpoints for provider discovery, market information, prices, OHLCV, and orderbooks

Public endpoints for market information. No authentication is required on Production; an API key is optional there. Development and Staging reject any request with no key.

---

​

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 on Production, required on Development and Staging). See Authentication.
x-lifi-integrator	header	string	No	Optional integrator assertion (non-authoritative). See Authentication.

​

Response 200

{
  "providers": [
    {
      "key": "hyperliquid",
      "name": "Hyperliquid",
      "logoURI": "https://static.debank.com/image/hyper_token/logo_url/hyper/0b3e288cfe418e9ce69eef4c96374583.png",
      "signingMethod": "eip712",
      "active": true,
      "funding": {
        "ratePeriodSeconds": 3600,
        "payoutCadenceSeconds": 3600
      },
      "minDepositUsd": "5",
      "minOrderValueUsd": "10",
      "withdrawalFeeUsd": "1",
      "chainId": 1337,
      "supportedIntervals": ["1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "8h", "12h", "1d", "3d", "1w", "1M"],
      "setup": [
        {
          "type": "revokeAgent",
          "signer": "USER",
          "signingMethod": "eip712",
          "relay": "API",
          "sequence": 5,
          "title": "Free a trading authorisation",
          "description": "Your account holds the maximum number of trading authorisations. This step removes the one that expires soonest so a new one fits.",
          "params": [],
          "options": null,
          "revoke": null
        },
        {
          "type": "approveAgent",
          "signer": "USER",
          "signingMethod": "eip712",
          "relay": "API",
          "sequence": 10,
          "title": "Allow one-click trading",
          "description": "Authorise a session signer to place orders on your behalf without prompting your wallet for every trade.",
          "docsUrl": "https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets",
          "params": [],
          "options": null,
          "revoke": "revokeSessionAgent"
        },
        {
          "type": "accountMode",
          "signer": "USER",
          "signingMethod": "eip712",
          "relay": "API",
          "sequence": 12,
          "title": "Account mode",
          "description": "Your account mode sets how Hyperliquid combines your spot and perps balances, and which assets back your perps positions.",
          "docsUrl": "https://hyperliquid.gitbook.io/hyperliquid-docs/trading/account-abstraction-modes",
          "options": [
            {
              "title": "Manual",
              "description": "Separate spot and perps balances. (shortened)",
              "type": "accountMode",
              "params": { "mode": "disabled" }
            },
            {
              "title": "Unified Account",
              "description": "One balance per quote asset, shared by spot and perps. (shortened)",
              "type": "accountMode",
              "params": { "mode": "unifiedAccount" },
              "default": true
            },
            {
              "title": "Portfolio Margin",
              "description": "One portfolio margins your spot and perps positions on every DEX. (shortened)",
              "type": "accountMode",
              "params": { "mode": "portfolioMargin" }
            }
          ],
          "revoke": null
        },
        {
          "type": "setReferrer",
          "signer": "SDK",
          "signingMethod": "eip712",
          "relay": "API",
          "sequence": 15,
          "title": "Authorise referral code",
          "description": "Authorise the LI.FI referral code on your account.",
          "params": [],
          "options": null,
          "revoke": null
        },
        {
          "type": "approveBuilderFee",
          "signer": "USER",
          "signingMethod": "eip712",
          "relay": "API",
          "sequence": 20,
          "title": "Approve builder allowance",
          "description": "Authorise the builder allowance on trades",
          "docsUrl": "https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes",
          "params": [],
          "options": null,
          "revoke": "revokeBuilderFee"
        }
      ],
      "actions": [
        { "type": "placeOrder", "signer": "SDK", "signingMethod": "eip712", "relay": "API" },
        { "type": "placeTriggerOrder", "signer": "SDK", "signingMethod": "eip712", "relay": "API" },
        {
          "type": "placeTwapOrder",
          "signer": "SDK",
          "signingMethod": "eip712",
          "relay": "API",
          "params": [
            {
              "name": "randomize",
              "type": "boolean",
              "values": [
                { "value": "false", "label": "Off" },
                { "value": "true", "label": "On" }
              ],
              "default": { "value": "false", "label": "Off" }
            }
          ]
        },
        { "type": "cancelOrder", "signer": "SDK", "signingMethod": "eip712", "relay": "API" },
        { "type": "cancelTwapOrder", "signer": "SDK", "signingMethod": "eip712", "relay": "API" },
        { "type": "modifyOrder", "signer": "SDK", "signingMethod": "eip712", "relay": "API" },
        { "type": "updateLeverage", "signer": "SDK", "signingMethod": "eip712", "relay": "API" },
        { "type": "updatePositionMargin", "signer": "SDK", "signingMethod": "eip712", "relay": "API" },
        { "type": "withdrawal", "signer": "USER", "signingMethod": "eip712", "relay": "API" },
        { "type": "sendAsset", "signer": "USER", "signingMethod": "eip712", "relay": "API" },
        { "type": "revokeSessionAgent", "signer": "USER", "signingMethod": "eip712", "relay": "API", "title": "Disable one-click trading", "description": "Removes the session signer from your account. You need to approve it again before one-click trading works.", "docsUrl": "https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets" },
        { "type": "revokeBuilderFee", "signer": "USER", "signingMethod": "eip712", "relay": "API", "title": "Revoke builder fee", "description": "Sets your approved builder fee to 0%. You need to approve it again before you can place orders here.", "docsUrl": "https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes" }
      ],
      "categories": [
        {
          "id": "hyperliquid",
          "quoteAsset": {
            "providerId": "hyperliquid",
            "id": "0",
            "displaySymbol": "USDC",
            "logoURI": "https://assets.li.fi/tokens/usdc.png"
          }
        },
        {
          "id": "xyz",
          "quoteAsset": {
            "providerId": "hyperliquid",
            "id": "0",
            "displaySymbol": "USDC",
            "logoURI": "https://assets.li.fi/tokens/usdc.png"
          },
          "tradeNotice": {
            "level": "warn",
            "message": "{displaySymbol} is a perp market deployed independently by its deployer. Beware of low liquidity, high volatility, and increased liquidation risk."
          }
        },
        { "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
shortName	string?	Short display name. A client shows this value in a compact place, and shows name when this value is absent.
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 your UI surfaces the provider for trading.
setup	SetupAction[]	Account-setup steps in sequence order. The user MUST satisfy every non-conditional step before trading. An empty array means the provider has no setup gates.
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	string?	Minimum deposit amount in USD that the provider’s deposit path will accept, as a plain decimal string. Absent means no minimum is advertised.
minOrderValueUsd	string?	Minimum order notional value in USD, as a plain decimal string. Absent means no minimum is advertised.
minReduceOrderValueUsd	string?	Minimum order notional value in USD for reduce-only orders, as a plain decimal string, 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	string?	Minimum withdrawal amount in USD the provider will accept, as a plain decimal string. Absent means no minimum is advertised.
depositFeeUsd	string?	Flat deposit fee in USD, as a plain decimal string, when the provider charges one.
withdrawalFeeUsd	string?	Flat withdrawal fee in USD, as a plain decimal string, when the provider charges one.
leveragePrecision	number?	Number of decimal places a client may use for leverage on this provider. Absent means integer leverage (0).
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

setup and actions share the ProviderAction shape. A setup entry is a SetupAction: a ProviderAction with two extra fields, options and revoke. Both fields are always present. The example above shortens the option descriptions.

ProviderAction field	Type	Description
type	ActionType	The action this entry describes. Send it as action to createAction.
signer	USER | SDK	USER: the user’s wallet or consent must act. SDK: the SDK fulfils the step with its own credentials.
signingMethod	SigningMethod	How the step is signed: eip712, wasmBlob, evmTx, hmac, siwe, or session.
relay	API | CLIENT	API: submit the signed step to POST /executeAction. CLIENT: the client submits the step to the venue itself, and nothing reaches LI.FI. For evmTx (Lighter deposit), the user’s wallet broadcasts each leg. The signed steps that carry txHash go to /executeAction as the acknowledgement.
title, description	string?	Display text for the step. For a choice step, description is the general prose for the whole choice.
docsUrl	string?	A link to the venue’s own documentation for the action.
params	Param[]?	Inputs the client collects before it calls the action. Each params[].values array lists the legal value strings. A choice step declares no params.
sequence	number?	Ascending order in which the user satisfies the setup steps. A lower sequence runs first.
gatesAccountReads	boolean?	true marks the step whose satisfaction lets the venue authenticate account reads and account streams for the address. Until that step is satisfied, those reads and streams cannot start.

SetupAction field	Type	Description
options	SetupOption[] | null	The selectable options when the step is a choice. null when the step is not a choice.
revoke	ActionType | null	The actions entry that undoes the satisfied step. null when a satisfied step cannot be undone.

Each SetupOption binds one selectable value to the action that applies it:

SetupOption field	Type	Description
title	string	Display title, for example Plus.
description	string?	The option’s own prose.
type	ActionType	The action to send to createAction when the user picks the option.
params	object	The action params, already bound to this option, for example { "tier": "plus" }.
default	true?	Marks the recommended option. Present only as true. At most one option of a step has it.

A choice step changes nothing by itself. The client sends the chosen option’s type and params to createAction. No option runs automatically, and the recommended option is only a suggestion. For the full direct-call flow, see Integrating without the SDK.

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 on Production, required on Development and Staging). 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": "0",
        "displaySymbol": "USDC",
        "logoURI": "https://assets.li.fi/tokens/usdc.png"
      },
      "szDecimals": 5,
      "priceDecimals": 1,
      "isDelisted": false,
      "maxLeverage": 50,
      "onlyIsolated": false,
      "positionMarginAdjustment": "ADD_AND_REMOVE",
      "defaultLeverage": 20,
      "maintenanceMarginRate": "0.012"
    }
  ]
}

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
minOrderValueUsd	string?	Per-market minimum order notional in USD as a decimal string (perps markets only). Separate from the venue-wide Provider.minOrderValueUsd, which covers every market
maxLeverage	number	Maximum allowed leverage (perps markets only; absent on spot)
defaultLeverage	number?	Leverage the venue applies to the market before the user sets one (perps markets only)
onlyIsolated	boolean	Whether only isolated margin is supported (perps markets only; absent on spot)
positionMarginAdjustment	'NONE' | 'ADD_ONLY' | 'ADD_AND_REMOVE'	Per-market individual margin capability (perps markets only; absent on spot)
maintenanceMarginRate	string?	Venue maintenance-margin rate as a fraction, as a decimal string (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)

​

Response 404

MarketNotFound (2023) — the provider has no markets, or marketIds matches none of them. A partial match returns only the matching markets.

SDK: getMarkets()

---

​

GET /assets

List the underlying asset registry for a provider. An asset is a transferable balance unit, not a tradable market — markets reference assets as their base/quote legs. Hyperliquid returns its spot token registry (id = venue token index). Lighter returns its asset_id registry. Ondo returns its token config.

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 on Production, required on Development and Staging). 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 on Production, required on Development and Staging). 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.

​

Response 404

MarketNotFound (2023) — marketIds is supplied and matches none of the markets. A partial match returns only the matching subset.

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). Defaults to endTime minus the larger of 24 hours and one candle. Must be before endTime, otherwise 400.
endTime	query	integer	No	End timestamp (ms). Defaults to the next candle boundary after now.
limit	query	integer	No	Max candles (1–1000, default 100)
x-lifi-api-key	header	string	No	API key (optional on Production, required on Development and Staging). 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 on Production, required on Development and Staging). 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 on Production, required on Development and Staging). 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 on Production, required on Development and Staging). 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 on Production, required on Development and Staging). 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 on Production, required on Development and Staging). 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?, nextUrl? }. nextUrl is set only when hasMore is true

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.