---
title: "Get API public v1 live positioning by entry by coin"
method: GET
path: "/api/public/v1/live/positioning-by-entry/{coin}"
---

# Get API public v1 live positioning by entry by coin

`GET /api/public/v1/live/positioning-by-entry/{coin}`

## Request

- Base URL: `https://api.coinversa.ai`
- URL: `https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/coinversa/apis/coinversa-api/docs/api/public/v1/live/positioning-by-entry/:coin/get.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

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

## Query parameters

- `minRecentSharpe` number, 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.
- `minTotalSharpe` number, 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).
- `buckets` integer: Number of equal-width entry-price bins across the range.
- `range` integer: 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 `200`

OK

- PositioningByEntryBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `binSize` number, double, required: Width of one bin, USD.
  - `bins` EntryBin[], nullable, required: Ascending price bins; empty when there are no positions or no mark.
    - `longAccounts` integer, required: Long positions with an entry in this bin.
    - `longNotional` number, double, required: All cohorts' open long notional with an entry in this bin, USD. Includes positions whose wallet has no tier.
    - `priceHigh` number, double, required: Upper bound of the bin, USD per unit (exclusive, inclusive on the last bin). Bounds come from one shared edge array, so an entry equal to a lower bound is in that bin.
    - `priceLow` number, double, required: Lower bound of the bin, USD per unit (inclusive).
    - `shortAccounts` integer, required: Short positions with an entry in this bin.
    - `shortNotional` number, double, required: All cohorts' open short notional with an entry in this bin, USD.
    - `tiers` EntryBinTier[], nullable, required: Per-cohort split of this bin, most notional first; cohorts with nothing in the bin are omitted.
      - `longAccounts` integer, required: Long positions in this bin. One row per wallet per market, so positions and accounts are the same count.
      - `longNotional` number, double, required: Open long notional with an entry price in this bin, USD (position size x last polled mark).
      - `shortAccounts` integer, required: Short positions in this bin.
      - `shortNotional` number, double, required: Open short notional with an entry price in this bin, USD.
      - `tier` string, required: Legacy tier slug (money_printer, exit_liquidity, ...; or leviathan ... shrimp for tierType=size).
  - `cohortBasis` string, required: Human label of the axis: all_time_pnl, recent_30d_pnl or lifetime_volume.
  - `cohorts` CohortEntrySummary[], nullable, required: One row per (tier, side) with any open notional, in tier order (most profitable or largest first), long before short. Market-wide, not limited to the bin range.
    - `accounts` integer, required: Open positions (= wallets) on this side.
    - `avgEntryPx` number, double, nullable, required: Notional-weighted average entry price over priced positions, USD per unit; null when nothing is priced.
    - `avgLeverage` number, double, nullable, required: Notional-weighted average leverage (x) over positions with a stored leverage; null when none has one.
    - `flatNotional` number, double, required: Priced notional whose entry equals the reference mark, USD.
    - `inProfitNotional` number, double, required: Priced notional strictly on the right side of the reference mark (long: entry < mark; short: entry > mark), USD. Fees and funding are not included.
    - `inProfitShare` number, double, nullable, required: inProfitNotional / pricedNotional, 0 to 1; null when nothing is priced or there is no mark.
    - `leverageCoveredNotional` number, double, required: Notional behind avgLeverage, USD.
    - `nearLiqNotional` number, double, required: Notional whose stored liquidation price is within nearLiqPct of the reference mark, USD.
    - `notional` number, double, required: Open notional, USD, INCLUDING positions without an entry price — reconciles with /live/cohort-bias.
    - `outsideRangeNotional` number, double, required: Priced notional whose entry falls outside the bin range, USD.
    - `pricedNotional` number, double, required: Notional with a stored entry price, USD: the denominator of avgEntryPx, inProfitShare and the bins.
    - `side` string, required: long or short.
    - `tier` string, required: Legacy tier slug.
    - `underwaterNotional` number, double, required: Priced notional strictly on the wrong side of the reference mark, USD.
    - `unknownProfitNotional` number, double, required: Notional whose side of the mark cannot be told: unpriced positions, or everything when there is no reference mark. USD.
    - `unpricedAccounts` integer, required: Positions without a stored entry price.
    - `unpricedNotional` number, double, required: Notional without a stored entry price, USD. In notional, in no bin, and unknownProfitNotional.
  - `coin` string, required: Canonical market symbol.
  - `coverage` PositioningCoverage, required
    - `positions` integer, required: Open positions on the market with notional > 10 (the rows every total is built from).
    - `withoutEntry` integer, required: Positions with no stored entry price. In notional totals; in no bin; unknownProfitNotional.
    - `withoutEntryNotional` number, double, required: Their notional, USD.
    - `withoutLeverage` integer, required: Positions with no stored leverage, excluded from avgLeverage only.
    - `withoutTier` integer, required: Of those, positions whose wallet has no cohort label yet. They are in the bins' totals and in long/short, but in no cohort row.
  - `long` PositioningSideTotals, required
    - `accounts` integer, required: Positions on this side, market-wide.
    - `inRangeAccounts` integer, required: Positions inside the bin range.
    - `inRangeNotional` number, double, required: Priced notional whose entry falls inside the bin range (the sum of the bins), USD.
    - `notional` number, double, required: Open notional on this side, market-wide, including unpriced positions, USD.
    - `outsideRangeAccounts` integer, required: Positions whose entry is outside the bin range.
    - `outsideRangeNotional` number, double, required: Priced notional whose entry is outside the bin range, USD.
    - `pricedNotional` number, double, required: Notional with a stored entry price, USD.
    - `unpricedAccounts` integer, required: Positions without a stored entry price.
    - `unpricedNotional` number, double, required: Notional without a stored entry price, USD (in no bin).
  - `markAsOf` integer, 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).
  - `markDivergencePct` number, 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.
  - `markMethod` string, 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.
  - `markPx` number, 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).
  - `markSource` string, required: Which feed or table the reference mark came from.
  - `nearLiqPct` number, double, required: The distance, in percent of mark, that defines nearLiqNotional.
  - `notes` string[], nullable, required: Caveats the chart should label: snapshot not history, mixed observation times, unpriced and untiered positions.
  - `rangeHigh` number, double, required: Highest entry price covered by the bins, USD.
  - `rangeLow` number, double, required: Lowest entry price covered by the bins, USD.
  - `short` PositioningSideTotals, required
    - `accounts` integer, required: Positions on this side, market-wide.
    - `inRangeAccounts` integer, required: Positions inside the bin range.
    - `inRangeNotional` number, double, required: Priced notional whose entry falls inside the bin range (the sum of the bins), USD.
    - `notional` number, double, required: Open notional on this side, market-wide, including unpriced positions, USD.
    - `outsideRangeAccounts` integer, required: Positions whose entry is outside the bin range.
    - `outsideRangeNotional` number, double, required: Priced notional whose entry is outside the bin range, USD.
    - `pricedNotional` number, double, required: Notional with a stored entry price, USD.
    - `unpricedAccounts` integer, required: Positions without a stored entry price.
    - `unpricedNotional` number, double, required: Notional without a stored entry price, USD (in no bin).
  - `source` PositioningSource, required
    - `asOf` integer, required: When this body was computed, Unix ms. Preserved on cache hits (the route cache refreshes every 30 s).
    - `cadence` string, required: How the underlying rows refresh.
    - `kind` string, required: Always 'snapshot': the current open book, never history. Do not present as a time series.
    - `medianAgeS` integer, required: Median age of the positions' updated_at at compute time, seconds.
    - `newestRow` integer, required: Latest updated_at across the positions used, Unix ms. updated_at is the syncer's batch flush time, so equal values do not order polls. Zero when there are none.
    - `oldestRow` integer, required: Earliest updated_at across the positions used, Unix ms. Rows are refreshed per wallet, so a body mixes observation times.
    - `table` string, required: Always live_positions: every open Hyperliquid position, upserted by the syncer as wallets are polled.
  - `storedMark` number, 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.
  - `storedMarkAsOf` integer, required: updated_at of the row the stored mark came from, Unix ms; zero when unknown.
  - `tierType` string, required: Cohort axis used: pnl, pnl_recent or size.
  - `tierWindowDays` integer, nullable, required: Rolling window the tier labels are computed over, days; null for all-time axes (pnl, size).

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `504`: Gateway Timeout

## Changes

- **2026-10-14** `e668ee30bd24`: 2 info
  - added the new optional `query` request parameter `minRecentSharpe`
  - added the new optional `query` request parameter `minTotalSharpe`
- **2026-10-12** `7aae8c32ff78`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/coinversa/apis/coinversa-api/changes/api/public/v1/live/positioning-by-entry/:coin/get.md)

---

[API](https://skmtc.dev/coinversa/apis/coinversa-api.md) - [All operations](https://skmtc.dev/coinversa/apis/coinversa-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coinversa/apis/coinversa-api/revisions/3454317a5830?raw)