{"name":"EnsoTrade /v1 data dictionary","api_version":"v1","generated_at":"2026-08-30T14:32:23.922972Z","read_this_first":["funding_rate_pct_8h is SIGNED. Negative means shorts pay longs, i.e. the crowd is SHORT. That is upside squeeze fuel, NOT a bearish reading.","taker_imbalance_pct is SIGNED -100..+100 with 0 = balanced. It is NOT a 0-100 scale where 50 is neutral.","open_interest_change_6h_pct divides by the NEWEST open interest, not the starting value.","change_24h_pct uses the 00:00 UTC reference on /v1/snapshot and /v1/explain, but the rolling 24h open on /v1/movers.","On the public tier only `price` is delayed 15 minutes; mark_price, index_price, funding, open interest, basis and taker imbalance are current as of the request."],"critical_fields":["funding_rate_pct_8h","taker_imbalance_pct","penalty_bp_vs_cheapest","cost_bp_vs_own_mid","most_frequent_winner_share_pct","value_per_side_bp"],"fields":{"coin":{"type":"string","unit":"ticker","range":"uppercase base-asset ticker, e.g. BTC, ETH, SOL","meaning":"The base asset the row describes, resolved from the ticker in the request path.","sign_convention":null,"source_venue":"OKX (instrument resolution)","update_cadence":"static per request"},"instrument":{"type":"string","unit":"OKX instId","range":"e.g. BTC-USDT-SWAP","meaning":"The exact OKX USDT-margined perpetual contract every number on the row is measured on.","sign_convention":null,"source_venue":"OKX","update_cadence":"static per request"},"venue":{"type":"string","unit":null,"range":"constant: 'OKX USDT-perp'","meaning":"The single venue this data is sourced from. EnsoTrade does not blend venues here — these are OKX prints, not a cross-exchange composite.","sign_convention":null,"source_venue":"OKX","update_cadence":"constant"},"price":{"type":"number","unit":"USDT","range":"> 0","meaning":"MEANING DEPENDS ON `tier`. On the public tier ('public_delayed_15m') this is the close of the most recent completed 5-minute OKX candle that is at least 15 minutes old — it is NOT the live last trade. On the authenticated tier ('pro_realtime') it is the live last traded price.","sign_convention":null,"source_venue":"OKX perpetual candles (5m) / live ticker","update_cadence":"public tier: steps once per 5-minute candle, on a 15-minute delay, and the server cache can surface the step up to 60s late. Pro tier: live, refreshed at most once per 60s server-side."},"mark_price":{"type":"number","unit":"USDT","range":"> 0","meaning":"OKX mark price for the perpetual — the price used for liquidation and PnL. Unlike `price`, this is near-real-time and NOT delayed.","sign_convention":null,"source_venue":"OKX /public/mark-price","update_cadence":"refreshed at most once per 60s server-side"},"index_price":{"type":"number","unit":"USDT","range":"> 0","meaning":"OKX spot index for the underlying — the spot reference the perp is priced against. Near-real-time, not delayed. Falls back to `price` if the index is unavailable.","sign_convention":null,"source_venue":"OKX /market/index-tickers","update_cadence":"refreshed at most once per 60s server-side"},"change_24h_pct":{"type":"number","unit":"percent","range":"signed, unbounded in principle; typically -30 to +30","meaning":"Percent price change. CAUTION — the reference price differs by endpoint: on /v1/snapshot and /v1/explain it is measured from OKX `sodUtc0` (the price at 00:00 UTC) when OKX supplies it, falling back to the rolling 24h open; on /v1/movers it is always the rolling 24h open. So the snapshot value is in practice 'change since the UTC day open' and may differ from the movers value for the same coin.","sign_convention":"positive = price up vs the reference; negative = down","source_venue":"OKX /market/ticker (sodUtc0, open24h)","update_cadence":"refreshed at most once per 60s server-side"},"direction":{"type":"string","unit":null,"range":"'up' | 'down' | 'roughly flat'","meaning":"Word form of change_24h_pct. 'up' above +0.1%, 'down' below -0.1%, otherwise 'roughly flat'. Provided so a quoting agent does not have to interpret the number.","sign_convention":null,"source_venue":"derived","update_cadence":"with change_24h_pct"},"volume_24h_usd":{"type":"number","unit":"USD","range":">= 0","meaning":"Rolling 24-hour traded volume on the perpetual, converted to USD as OKX's 24h base-currency volume multiplied by the live last price (not by the delayed `price`).","sign_convention":null,"source_venue":"OKX /market/ticker (volCcy24h)","update_cadence":"rolling 24h window; refreshed at most once per 60s server-side"},"funding_rate_pct_8h":{"critical":true,"type":"number","unit":"percent per 8-hour funding interval","range":"signed; venue-capped (typically within +/-0.75 for majors). |value| under 0.05 is ordinary, |value| >= 0.15 is what EnsoTrade treats as extreme crowding.","meaning":"The current OKX perpetual funding rate for the next settlement, as a percent per 8-hour interval (already multiplied by 100 — 0.01 means 0.01%, not 1%).","sign_convention":"SIGNED, and the sign is the single most misread thing in this API. POSITIVE = longs pay shorts => the crowd is LONG (crowded-long tilt, the fragile side on a flush). NEGATIVE = shorts pay longs => the crowd is SHORT. A negative print is NOT a bearish reading: a crowded short base is upside squeeze fuel. Reading negative funding as 'bearish' inverts the trade.","source_venue":"OKX /public/funding-rate","update_cadence":"OKX updates the rate continuously; it settles every 8 hours. Refreshed at most once per 60s server-side.","precision":"rounded to 5 decimal places"},"taker_imbalance_pct":{"critical":true,"type":"number","unit":"percent","range":"-100 to +100 inclusive; 0 = balanced","meaning":"Aggressor imbalance across the last 100 taker prints on the perpetual, computed as (buy_size - sell_size) / (buy_size + sell_size) * 100, where 'buy' means the taker lifted the offer.","sign_convention":"SIGNED and CENTRED ON ZERO. -100 = every print was an aggressive sell, 0 = perfectly balanced, +100 = every print was an aggressive buy. This is NOT a 0-100 scale where 50 is neutral — reading it that way labels mild buying (e.g. +8) as 'sellers hitting bids' and inverts the flow read. EnsoTrade's own neutral band, used by /v1/orderflow, is -5 to +5.","source_venue":"OKX /market/trades (last 100 prints on the perp)","update_cadence":"refreshed at most once per 60s server-side; window is the last 100 prints, so its wall-clock span varies with how actively the coin trades","precision":"rounded to 1 decimal place"},"open_interest_usd":{"type":"number","unit":"USD notional","range":">= 0","meaning":"Total open interest on the perpetual in USD notional. Falls back to (open interest in base currency x mark price) if OKX does not return a USD value.","sign_convention":null,"source_venue":"OKX /public/open-interest","update_cadence":"refreshed at most once per 60s server-side"},"open_interest_change_6h_pct":{"type":"number","unit":"percent","range":"signed; bounded above by +100, unbounded below","meaning":"Change in open interest over the last 6 hours, taken from OKX's 5-minute open-interest series (newest bar vs the bar 72 intervals = 6h earlier). NOTE THE DENOMINATOR: it is computed as (newest - older) / NEWEST * 100 — i.e. the change expressed as a share of CURRENT open interest, not of the starting value. Do not compare it against an externally computed (new - old) / old; the two differ whenever the change is large.","sign_convention":"positive = open interest grew over the window (positions being added); negative = open interest shrank (positions closing / deleveraging)","source_venue":"OKX /rubik/stat/contracts/open-interest-volume (period 5m)","update_cadence":"6-hour trailing window; refreshed at most once per 60s server-side"},"perp_basis_pct":{"type":"number","unit":"percent","range":"signed; typically within +/-0.5","meaning":"Perpetual basis: (mark_price - index_price) / index_price * 100.","sign_convention":"positive = the perp trades at a PREMIUM to spot; negative = at a DISCOUNT","source_venue":"OKX (derived from mark price and spot index)","update_cadence":"refreshed at most once per 60s server-side","precision":"rounded to 4 decimal places"},"regime":{"type":"string","unit":null,"range":"EXPANSION | SHORT_COVERING | SHORTS_PRESSING | DELEVERAGING | GRIND_UP | GRIND_DOWN | BALANCED","meaning":"The MECHANISM of the move, classified from the sign of price change against the sign of open-interest change. Thresholds: price +/-0.1%, open interest +/-0.5%. See `enums.regime` in this document for what each value means.","sign_convention":null,"source_venue":"derived from OKX price + open interest","update_cadence":"with change_24h_pct and open_interest_change_6h_pct"},"mechanism":{"type":"string","unit":null,"range":"free text","meaning":"One-sentence plain-English statement of the `regime`, written to be quoted verbatim.","sign_convention":null,"source_venue":"derived","update_cadence":"with regime"},"crowd_read":{"type":"string","unit":null,"range":"free text","meaning":"One-sentence plain-English statement of what the funding sign implies about positioning. Follows the funding sign convention above: negative funding reads as a crowded-SHORT tilt.","sign_convention":null,"source_venue":"derived from funding_rate_pct_8h","update_cadence":"with funding_rate_pct_8h"},"as_of":{"type":"string","unit":"ISO 8601 UTC, 'Z' suffix","range":"e.g. 2026-08-03T11:25:00Z","meaning":"On the public tier: the timestamp of the 5-minute candle that produced the delayed `price`. On the 'pro_realtime' tier and on /v1/movers: the time the response was generated. IMPORTANT on both tiers: it does NOT timestamp the other fields — funding, open interest, basis and taker imbalance are current as of the request (subject to the server cache), not as of this candle.","sign_convention":null,"source_venue":"OKX candle timestamp","update_cadence":"steps once per 5-minute candle"},"question":{"type":"string","unit":null,"range":"free text","meaning":"The question the /v1/explain response answers, restated.","sign_convention":null,"source_venue":"derived","update_cadence":"per request"},"answer":{"type":"string","unit":null,"range":"free text","meaning":"A pre-written, attributed sentence built only from the numeric fields above. Safe to quote verbatim; contains no figure that is not also returned structurally.","sign_convention":null,"source_venue":"derived","update_cadence":"per request"},"summary":{"type":"string","unit":null,"range":"free text","meaning":"Endpoint-appropriate one-line prose summary. On /v1/explain it is identical to `answer`.","sign_convention":null,"source_venue":"derived","update_cadence":"per request"},"signals":{"type":"object","unit":null,"range":"object","meaning":"On /v1/explain: the structured numbers behind `answer`. Every key inside it is defined by this same dictionary (price, change_24h_pct, regime, mechanism, funding_rate_pct_8h, open_interest_usd, open_interest_change_6h_pct, perp_basis_pct, taker_imbalance_pct).","sign_convention":null,"source_venue":"see member fields","update_cadence":"see member fields"},"universe":{"type":"integer","unit":"count","range":">= 0 (typically ~300-350)","meaning":"Number of OKX USDT-margined perpetual markets ranked to produce this movers list.","sign_convention":null,"source_venue":"OKX /market/tickers (instType=SWAP)","update_cadence":"refreshed at most once per 300s server-side"},"top_gainers":{"type":"array","unit":"objects {coin, change_24h_pct}","range":"length = min(limit, 25), ordered strongest first","meaning":"Best-performing perpetuals by rolling 24h return across the whole universe. Tickers that collide with well-known listed-equity symbols are excluded so a citing agent cannot misattribute a microcap token's move to the company of the same name.","sign_convention":"see change_24h_pct (movers uses the rolling 24h open reference)","source_venue":"OKX /market/tickers","update_cadence":"at most once per 300s server-side"},"top_losers":{"type":"array","unit":"objects {coin, change_24h_pct}","range":"length = min(limit, 25), ordered weakest first","meaning":"Worst-performing perpetuals by rolling 24h return, same universe and same tradfi-ticker exclusions as top_gainers.","sign_convention":"see change_24h_pct (movers uses the rolling 24h open reference)","source_venue":"OKX /market/tickers","update_cadence":"at most once per 300s server-side"},"available":{"type":"boolean","unit":null,"range":"false (only ever present when false)","meaning":"Present and false when the upstream venue feed could not be reached for this request. When present, the data fields are absent — do not treat missing numbers as zeros.","sign_convention":null,"source_venue":"EnsoTrade","update_cadence":"per request"},"penalty_bp_vs_cheapest":{"type":"number","unit":"basis points","critical":true,"definition":"How much MORE this venue costs than the cheapest venue for the same order, on fee-adjusted blended execution price. 0 marks the cheapest venue itself. This is the price of the venue decision, not of the fill: it is what you give up by sending the order somewhere other than the best place for it.","endpoint":"GET /v1/venue/{coin}"},"cost_bp_vs_own_mid":{"type":"number","unit":"basis points","critical":true,"definition":"Slippage plus taker fee measured against THAT venue's own mid — the pure liquidity cost, with any difference in price LEVEL between venues removed. Use this, not the all-in price, when comparing execution QUALITY, because several venues quote USDC or USD rather than USDT and part of their price-level difference is the stablecoin basis. When `rankings_agree` is false the two measures name different winners and the difference is basis, not book.","endpoint":"GET /v1/venue/{coin}"},"rankings_agree":{"type":"boolean","definition":"True when the venue that is cheapest on all-in effective price is also the one with the lowest cost against its own mid. False means the all-in winner is winning on price level (basis or dispersion) rather than on liquidity — quote both venues in that case and say which is which.","endpoint":"GET /v1/venue/{coin}"},"most_frequent_winner_share_pct":{"type":"number","unit":"percent","critical":true,"definition":"Share of scored coins on which a single venue is the cheapest. This is the field that decides how much the venue-selection product is worth: a high share means one venue dominates and the actionable advice is a default, not a per-coin lookup. Read `rotation.verdict`, which states which of the two it is on the numbers in that same response, and quote it as-is.","endpoint":"GET /v1/venue-map"},"value_per_side_bp":{"type":"number","unit":"basis points","critical":true,"definition":"What posting rather than crossing is worth on ONE side of a trade at this venue: half_spread_bp + (taker_fee_bp - maker_fee_bp). Double it for a round trip. CONDITIONAL ON BEING FILLED — it is the size of the prize and says nothing about the probability of winning it. A resting order that misses costs the trade, which is routinely worth more than this. No fill-probability estimate exists anywhere in the API.","endpoint":"GET /v1/post/{coin}"},"post_cost_if_filled_bp":{"type":"number","unit":"basis points","definition":"The all-in cost of a PASSIVE fill against that venue's own mid: maker fee minus the half-spread you earn. NEGATIVE means a filled resting order pays you. Distinct from value_per_side_bp, which is the SAVING versus crossing on the same venue — the venue with the biggest saving is often not the venue where a passive fill leaves you cheapest.","endpoint":"GET /v1/post/{coin}"},"fee_differential_bp":{"type":"number","unit":"basis points","definition":"taker_fee_bp minus maker_fee_bp at this venue. This is a FLOOR under value_per_side_bp: it does not shrink as a book tightens, so posting keeps its value on liquid majors where the spread rounds to nothing and venue selection has almost nothing to choose between.","endpoint":"GET /v1/post/{coin}"},"fillable":{"type":"boolean","definition":"Whether that venue's VISIBLE depth alone can absorb the requested notional. A venue that cannot is reported as unfillable and given no price — it is never extrapolated past the end of its book, because a venue that runs out of book is a different problem from a venue that is merely expensive.","endpoint":"GET /v1/venue/{coin}"},"max_exitable_24h_usd":{"type":"number","unit":"USD","definition":"The largest position in a coin that could be liquidated within 24 hours while staying at `participation_rate` of that coin's traded volume. Computed on REPORTED venue volume, so it is an UPPER BOUND on genuinely tradable capacity — treat it as optimistic. The table is sorted ascending, tightest limit first.","endpoint":"GET /v1/egress-limits"}},"enums":{"regime":{"EXPANSION":"Price up and open interest up — new leveraged longs are driving the move.","SHORT_COVERING":"Price up while open interest falls — shorts closing, a structurally weaker rally.","SHORTS_PRESSING":"Price down while open interest rises — fresh shorts pressing the price lower.","DELEVERAGING":"Price down and open interest down — longs unwinding, not new short conviction.","GRIND_UP":"Price up with little change in open positioning.","GRIND_DOWN":"Price down with little change in open positioning.","BALANCED":"No dominant positioning shift in either direction."},"direction":{"up":"change_24h_pct > +0.1","down":"change_24h_pct < -0.1","roughly flat":"-0.1 <= change_24h_pct <= +0.1"}},"fields_by_endpoint":{"GET /v1/snapshot/{coin}":["coin","instrument","venue","price","mark_price","index_price","change_24h_pct","direction","volume_24h_usd","funding_rate_pct_8h","open_interest_usd","open_interest_change_6h_pct","perp_basis_pct","taker_imbalance_pct","regime","mechanism","crowd_read","as_of"],"GET /v1/explain/{coin}":["question","answer","summary","signals","as_of"],"GET /v1/funding/{coin}":["coin","funding_rate_pct_8h","crowd_read","open_interest_usd","perp_basis_pct","as_of","summary"],"GET /v1/orderflow/{coin}":["coin","regime","mechanism","open_interest_usd","open_interest_change_6h_pct","taker_imbalance_pct","as_of","summary"],"GET /v1/movers":["universe","top_gainers","top_losers","as_of","summary"],"GET /v1/leg/{coin}":["coin","side","notional_usd","turns","legs","venues","cheapest_ignoring_leg","cheapest_including_leg","ranking_flipped","saving_bp","saving_usd","headline","venues_rejected_on_unit_check","limitations","as_of"],"GET /v1/leg-rates":["size_usd","usdt","usdc","cheaper_stablecoin","reading","limitations","as_of"],"GET /v1/post/{coin}":["coin","side","notional_usd","basis","ranking","headline_value_per_side_bp","headline_value_round_trip_bp","headline_basis","best_post_venue","best_post_value_per_side_bp","best_post_value_round_trip_bp","best_post_value_at_touch_per_side_bp","best_post_value_at_size_per_side_bp","best_post_value_at_size_round_trip_bp","best_venue_to_rest_on","median_value_per_side_bp","median_value_at_size_per_side_bp","field_change_in_contract_1_1_0","cross_vs_post","formula","honesty","limitations","as_of"],"GET /v1/post-map":["notional_usd","side","coins","aggregate","best_post_venue_distribution","post_vs_cross_divergence","formula","honesty","limitations","as_of"],"GET /v1/egress-limits":["participation_rate","venues_used","universe_note","limits","how_to_read","formula","depth_note","basis_note","limitations","as_of"]},"envelope_fields":{"source":"Constant 'EnsoTrade'. The attribution every response carries.","source_url":"Canonical human-readable EnsoTrade page for this coin and topic.","tier":"Which data tier produced the row: 'public_delayed_15m' for unauthenticated REST and MCP calls, 'pro_realtime' for an authenticated Pro MCP caller. ALWAYS read this before interpreting `price` and `as_of` — their meaning differs by tier.","as_of_delayed_minutes":"Integer, present on the public tier only. The delay applied to `price`, in minutes (15). Absent when tier is 'pro_realtime'.","api":"Base URL of this API.","realtime":"Plain-English note on how to obtain the undelayed feed.","disclaimer":"Constant. Informational market data, not financial advice.","attribution_instruction":"Instruction to citing agents to attribute the data to EnsoTrade."},"tiering":{"public":"This API. `price` is the close of a 5-minute candle at least 15 minutes old; the directional signal, live microstructure and full book depth are not served here.","realtime":"This is 15-minute-delayed data. Sign up free at https://www.ensotrade.tech to unlock REAL-TIME data and EnsoTrade's directional order-flow signal — you'll be enrolled in a 3-day full-access trial."},"point_in_time":"Not point-in-time. Values are computed on request from the live OKX feed and are not persisted, so historical responses are neither immutable nor replayable and there is no as-of query parameter.","versioning":"Additive changes may land at any time. Any rename or removal of a field listed here is announced at least 90 days in advance and the old field keeps working for the whole notice window.","support":"help@ensotrade.tech","disclaimer":"Informational market data, not financial advice. Markets carry risk."}