(1) A ccy-level account ratio across expiry and perpetual futures; (2) an account ratio for one instId; (3) a Top Trader account ratio for one instId; and (4) a Top Trader position ratio for one instId. Top Trader means the top 5% by open position value. This API group does not provide an exchange-wide position ratio.
The currency account ratio aggregates expiry and perpetual futures, while the other three use a specified contract. The Top Trader series further restrict the sample to the top 5% by open position value. Different scope, sample and denominator can produce different readings; none of the ratios alone proves incremental buying or selling.
Record the endpoint, ccy or instId, period and sample time, then compare like with like. A ratio above 1 only means the numerator exceeds the denominator in that sample; a ratio below 1 means the reverse. Levels such as 2.5 or 0.5 are not official OKX trading thresholds.
No. OKX defines it as net-long divided by net-short accounts across expiry and perpetual futures for a currency; it does not label the sample as retail. Any contrarian value has to be tested separately with the same endpoint and parameters.
It describes long versus short position value among the top 5% of accounts by open position value for one contract. That makes it useful for observing this sample, not for predicting direction. The ranking does not screen for win rate, and larger positions are not evidence of better forecasts.
First check that both series refer to the same instId. If a contract's Top Trader account ratio is above 1 while its Top Trader position ratio is below 1, more sampled accounts are net long but short position value is larger. That does not by itself reveal who added or closed positions, or where price goes next.
Save the endpoint, parameters, raw response and sample time, then record price, volume, funding and open interest separately. Test a predefined horizon afterward. LSR describes a sample distribution; agreement with other indicators does not automatically create an entry, exit or stop instruction.
OKX ships four long/short feeds, not one
OKX publishes four related feeds, but they do not share one scope. Read the parameter and sample with the value.
Currency long/short account ratio. Queried with ccy, this counts net-long accounts against net-short accounts across expiry and perpetual futures for that currency.
Contract long/short account ratio. Queried with instId, this counts net-long against net-short accounts for one specified contract such as BTC-USDT-SWAP.
Top Trader account ratio. Also contract-specific, but restricted to the top 5% of accounts by open position value. The cut is on position size, not trading volume or profitability.
Top Trader position ratio. For that same contract and Top Trader sample, this divides long position value by short position value. It is the only position-value ratio among these four endpoints.
The full schema is in OKX's API documentation under the Rubik (data) namespace.
The account ratio counts heads, the position ratio counts dollars
Account ratios compare account counts. The Top Trader position ratio compares long and short position value within the top-5% sample for one contract.
When comparing an account ratio with a position ratio, first make sure both refer to the same contract and sample. A Top Trader account ratio above 1 and position ratio below 1 means more sampled accounts are net long while short position value is larger. The ratios alone do not show whether either side added or closed positions.
What the Top Trader filter selects, and what it cannot show
The currency and contract account ratios count accounts without a Top Trader filter. OKX does not label that population "retail", so treat it as an account distribution rather than a verified retail sample.
Top Trader feeds keep only the accounts in the top 5% by open position value. What you get is a view of where the largest books are sitting — which is worth knowing, but it is worth being precise about what it is not. Size is not correctness. There is no win-rate screen anywhere in that cut: an account that opened a large position ten minutes ago and an account that has held one for three months are the same entry on that list.
The Top Trader sample is only 5% of accounts by open position value, so its readings cannot be substituted for the broader account ratios. As for which line is "more accurate" — OKX has not published that kind of study, and any claimed lead time needs reproducible data.
The unfiltered currency and contract account ratios are not "retail LSR" either. OKX describes net-long and net-short accounts but does not attach an identity label. The broader and Top Trader samples can be observed side by side, but they are not a verified retail-versus-whale contest.
Reading high and low values without inventing causality
Read each series against its own retained history. A value above 1 means the numerator exceeds the denominator for that endpoint; below 1 means the reverse. Labels such as 0.7-1.5 "neutral" or 2.5 "extreme" are informal conventions, not official OKX thresholds or findings from a dataset published here.
An extreme ratio only establishes that the measured distribution is uneven. It does not directly measure new flow and does not make a reversal inevitable. Any claim about what happens next needs a reproducible study using the same endpoint and parameters.
Position risk should be calculated separately from LSR. In a pure hypothetical, buy Q=0.05 BTC at 70,000 USDT and mark it at 63,000. Ignoring fees and funding, gross PnL is Q × (63,000 − 70,000) = −350 USDT.
If half is closed while price is still 70,000, the closed half realizes zero in this example and the remaining Q=0.025 BTC loses 175 USDT on the same path. This only shows that linear PnL halves when quantity halves; it does not use LSR to forecast price or establish that trimming was the right decision.
Liquidation needs separate inputs: margin mode, margin retained with the open leg, maintenance margin and fees. Halving both quantity and margin leaves margin per unit unchanged, so the liquidation boundary does not improve automatically. Changing a leverage setting is also not the same as reducing quantity or adding margin.
Pulling live LSR off the OKX API onto your own machine
The endpoints are public, with no API key. The currency account series takes ccy; the contract and Top Trader series take instId.
Currency account ratio (expiry + perpetual futures): GET /api/v5/rubik/stat/contracts/long-short-account-ratio?ccy=BTC&period=5m
Per-contract account ratio: GET /api/v5/rubik/stat/contracts/long-short-account-ratio-contract?instId=BTC-USDT-SWAP
Top Trader account ratio: GET /api/v5/rubik/stat/contracts/long-short-account-ratio-contract-top-trader?instId=BTC-USDT-SWAP
Top Trader position ratio: GET /api/v5/rubik/stat/contracts/long-short-position-ratio-contract-top-trader?instId=BTC-USDT-SWAP
The limits that trip people up: the currency series supports 5m / 1H / 1D with 2-day / 30-day / 180-day lookbacks, and is limited to 5 requests per 2 seconds per IP. Each contract endpoint can retrieve the latest 1,440 entries, but limit defaults to 100 and is capped at 100 per request; its rate limit is 5 requests per 2 seconds per IP plus instrument ID. Top Trader data starts on 2024-03-22.
What comes back is a two-dimensional array shaped like [[timestamp, longShortRatio], ...]. Which end holds the newest row is something to check by printing the timestamps once rather than assuming. Also note that OKX does not document a refresh interval for these statistics, so do not hard-code "there is a new value every 5 minutes" into your polling loop.
The two-day 5m lookback applies to the currency account endpoint. The three contract endpoints use their own latest-1,440-record range, 100-record per-request cap and pagination conditions. Archive each endpoint and parameter set separately if you need history beyond the documented window.
You can also open our long/short ratio data page for six cards: currency account, Top Trader account and Top Trader position ratios for BTC and ETH, each showing roughly 150 minutes of 5-minute points.
How to verify a historical LSR claim
We do not have the raw API responses needed to verify the old market story previously told here. We therefore do not retain specific dates, prices, ratio paths or claims that one account group was right. A recollection of a dashboard is not evidence.
A defensible historical test needs the full endpoint, ccy/instId, period, pagination and UTC sample time; an unedited response or timestamped snapshot; contemporaneous price, volume, funding and OI; and a rule fixed before outcomes are inspected. Report only the distribution the ratio supports, not inferred entries, exits, liquidations or profits.
When samples diverge, check scope before direction
Suppose the currency account ratio is 1.9 while a contract's Top Trader position ratio is 0.6. The first describes account counts across expiry and perpetual futures; the second describes position value in the Top Trader sample for one contract. They use different populations, parameters and units.
Align timestamps and instruments, identify whether each series counts accounts or position value, and treat any directional or timing story as a hypothesis for a separate test. A stable ratio can hide both sides doubling, while a rising position ratio can reflect longs rising, shorts falling, or both falling at different rates.
Turning LSR into a reproducible research log
Use LSR as a structured observation variable. Save the endpoint, parameters, raw value and UTC timestamp, then record price, volume, funding and OI separately. These measures describe different things; agreement does not automatically create a trade signal.
Before viewing outcomes, state a testable hypothesis, horizon, fee assumption and missing-data rule. Keep losing and null observations as well as the memorable ones. A single snapshot can describe relative distribution at that moment; it cannot choose an entry, stop or position size for you.