COcoinversa

Get API public v1 live positioning by entry by coin

Changed on
get/api/public/v1/live/positioning-by-entry/{coin}

Request

Path parameters

coinstring required

Market symbol, e.g. BTC or xyz:GOLD. Case and surrounding whitespace are normalized; the body echoes the canonical spelling.

Query parameters

minRecentSharpenumber double

Optional inclusive minimum stored annualized realized-PnL Sharpe over 30 completed UTC days (refreshed hourly). Finite values only, including zero and negatives. Undefined/unpopulated scores are excluded when set. Fees, funding and unrealized PnL are excluded; this is not equity-return Sharpe. Applied with minTotalSharpe using AND, before limits and aggregation.

minTotalSharpenumber double

Optional inclusive minimum stored annualized realized-PnL Sharpe from first available daily history through yesterday UTC (refreshed daily). Finite values only, including zero and negatives. Undefined/unpopulated scores are excluded when set. Uses the current wallet score, not a historical score. Applied with minRecentSharpe using AND; omitted thresholds do not filter.

tierType'pnl' | 'pnl_recent' | 'size'

Cohort axis: pnl (all-time realized PnL tiers; money_printer = Apex, exit_liquidity = The Crowd), pnl_recent (the same slugs over the wallet's last 30 days of PnL — Apex by recent PnL is who is winning now; traders.pnl_tier_recent, refreshed hourly) or size (lifetime traded-volume tiers). Tiers are the wallet's CURRENT label (tierAssignment current).

bucketsinteger

Number of equal-width entry-price bins across the range.

rangeinteger

Percentage distance below and above the reference mark covered by the bins; 30 means mark x 0.7 .. mark x 1.3. Priced positions whose entry is outside are summed in outsideRange and still count in cohorts and totals.

Response

OK

$schemastring uri

A URL to the JSON Schema for this object.

binSizenumber double required

Width of one bin, USD.

cohortBasisstring required

Human label of the axis: all_time_pnl, recent_30d_pnl or lifetime_volume.

coinstring required

Canonical market symbol.

markAsOfinteger required

When the reference mark was observed, Unix ms: the feed's fetch time (live_mark) or the row's updated_at (newest_position). Zero when unknown: no mark, or weighted_fallback (which only runs when no row with a mark carries a time).

markDivergencePctnumber double nullable required

(markPx - storedMark) / storedMark x 100 when both exist, else null. Above 1 percent in absolute value the stored notionals and liquidation distances are noticeably stale; a note says so.

markMethodstring required

live_mark: Hyperliquid's current mark via the API's cached metaAndAssetCtxs client (preferred when it is at most 60 s old and not older than the newest stored row); newest_position: the mark stored on the most recently flushed row (ties broken by larger notional), used when the feed is unavailable; weighted_fallback: notional-weighted stored mark when no dated row has one; none: no mark.

markPxnumber double nullable required

Reference mark, USD per unit, used for the bin range, in-profit/underwater/flat and near-liquidation: the venue's live mark when the feed answered (markMethod live_mark), else a mark stored on a position row. null when neither exists (then bins are empty and every profit split is unknown).

markSourcestring required

Which feed or table the reference mark came from.

nearLiqPctnumber double required

The distance, in percent of mark, that defines nearLiqNotional.

notesstring[] nullable required

Caveats the chart should label: snapshot not history, mixed observation times, unpriced and untiered positions.

rangeHighnumber double required

Highest entry price covered by the bins, USD.

rangeLownumber double required

Lowest entry price covered by the bins, USD.

storedMarknumber double nullable required

The mark the position rows themselves carry (newest_position or weighted_fallback over stored marks), USD per unit; null when none. Shown so clients can see how stale the stored book is against the reference.

storedMarkAsOfinteger required

updated_at of the row the stored mark came from, Unix ms; zero when unknown.

tierTypestring required

Cohort axis used: pnl, pnl_recent or size.

tierWindowDaysinteger nullable required

Rolling window the tier labels are computed over, days; null for all-time axes (pnl, size).

Example response

{
  "$schema": "https://api.coinversa.ai/schemas/PositioningByEntryBody.json"
}

Changes