> ## Documentation Index > Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get API public v1 live positioning by entry by coin ## OpenAPI ````yaml /api-reference/openapi.json get /api/public/v1/live/positioning-by-entry/{coin} openapi: 3.1.0 info: title: coinversa-api version: 0.1.0 servers: - url: https://api.coinversa.ai description: Production security: [] paths: /api/public/v1/live/positioning-by-entry/{coin}: get: summary: Get API public v1 live positioning by entry by coin operationId: get-api-public-v1-live-positioning-by-entry-by-coin parameters: - description: >- 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. explode: false in: query name: minRecentSharpe schema: description: >- 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. format: double type: number - description: >- 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. explode: false in: query name: minTotalSharpe schema: description: >- 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. format: double type: number - description: >- Market symbol, e.g. BTC or xyz:GOLD. Case and surrounding whitespace are normalized; the body echoes the canonical spelling. in: path name: coin required: true schema: description: >- Market symbol, e.g. BTC or xyz:GOLD. Case and surrounding whitespace are normalized; the body echoes the canonical spelling. type: string - description: >- 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). explode: false in: query name: tierType schema: default: pnl description: >- 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). enum: - pnl - pnl_recent - size type: string - description: Number of equal-width entry-price bins across the range. explode: false in: query name: buckets schema: default: 60 description: Number of equal-width entry-price bins across the range. format: int32 maximum: 200 minimum: 1 type: integer - description: >- 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. explode: false in: query name: range schema: default: 30 description: >- 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. format: int32 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/PositioningByEntryBody' description: OK headers: X-Billing-Grace-Expires: $ref: '#/components/headers/X-Billing-Grace-Expires' X-Billing-State: $ref: '#/components/headers/X-Billing-State' X-RateLimit-Daily: $ref: '#/components/headers/X-RateLimit-Daily' X-RateLimit-Daily-Reset: $ref: '#/components/headers/X-RateLimit-Daily-Reset' X-RateLimit-Monthly: $ref: '#/components/headers/X-RateLimit-Monthly' X-RateLimit-Monthly-Reset: $ref: '#/components/headers/X-RateLimit-Monthly-Reset' X-RateLimit-Next: $ref: '#/components/headers/X-RateLimit-Next' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-RateLimit-Route: $ref: '#/components/headers/X-RateLimit-Route' X-RateLimit-Scope: $ref: '#/components/headers/X-RateLimit-Scope' X-RateLimit-Tier: $ref: '#/components/headers/X-RateLimit-Tier' X-Request-ID: $ref: '#/components/headers/X-Request-ID' '400': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Bad Request headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '403': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Forbidden headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '404': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Not Found headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '422': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Unprocessable Entity headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '429': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Too Many Requests headers: Retry-After: $ref: '#/components/headers/Retry-After' X-Billing-Grace-Expires: $ref: '#/components/headers/X-Billing-Grace-Expires' X-Billing-State: $ref: '#/components/headers/X-Billing-State' X-RateLimit-Daily: $ref: '#/components/headers/X-RateLimit-Daily' X-RateLimit-Daily-Reset: $ref: '#/components/headers/X-RateLimit-Daily-Reset' X-RateLimit-Monthly: $ref: '#/components/headers/X-RateLimit-Monthly' X-RateLimit-Monthly-Reset: $ref: '#/components/headers/X-RateLimit-Monthly-Reset' X-RateLimit-Next: $ref: '#/components/headers/X-RateLimit-Next' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-RateLimit-Route: $ref: '#/components/headers/X-RateLimit-Route' X-RateLimit-Scope: $ref: '#/components/headers/X-RateLimit-Scope' X-RateLimit-Tier: $ref: '#/components/headers/X-RateLimit-Tier' X-Request-ID: $ref: '#/components/headers/X-Request-ID' '500': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Internal Server Error headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '504': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Gateway Timeout headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' security: - apiKey: [] components: schemas: PositioningByEntryBody: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/PositioningByEntryBody.json format: uri readOnly: true type: string binSize: description: Width of one bin, USD. format: double type: number bins: description: Ascending price bins; empty when there are no positions or no mark. items: $ref: '#/components/schemas/EntryBin' type: - array - 'null' cohortBasis: description: >- Human label of the axis: all_time_pnl, recent_30d_pnl or lifetime_volume. type: string cohorts: description: >- 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. items: $ref: '#/components/schemas/CohortEntrySummary' type: - array - 'null' coin: description: Canonical market symbol. type: string coverage: $ref: '#/components/schemas/PositioningCoverage' long: $ref: '#/components/schemas/PositioningSideTotals' markAsOf: description: >- 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). format: int64 type: integer markDivergencePct: description: >- (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. format: double type: - number - 'null' markMethod: description: >- 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. type: string markPx: description: >- 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). format: double type: - number - 'null' markSource: description: Which feed or table the reference mark came from. type: string nearLiqPct: description: The distance, in percent of mark, that defines nearLiqNotional. format: double type: number notes: description: >- Caveats the chart should label: snapshot not history, mixed observation times, unpriced and untiered positions. items: type: string type: - array - 'null' rangeHigh: description: Highest entry price covered by the bins, USD. format: double type: number rangeLow: description: Lowest entry price covered by the bins, USD. format: double type: number short: $ref: '#/components/schemas/PositioningSideTotals' source: $ref: '#/components/schemas/PositioningSource' storedMark: description: >- 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. format: double type: - number - 'null' storedMarkAsOf: description: >- updated_at of the row the stored mark came from, Unix ms; zero when unknown. format: int64 type: integer tierType: description: 'Cohort axis used: pnl, pnl_recent or size.' type: string tierWindowDays: description: >- Rolling window the tier labels are computed over, days; null for all-time axes (pnl, size). format: int32 type: - integer - 'null' required: - coin - tierType - cohortBasis - tierWindowDays - markPx - markAsOf - markMethod - markSource - storedMark - storedMarkAsOf - markDivergencePct - rangeLow - rangeHigh - binSize - bins - cohorts - long - short - coverage - source - nearLiqPct - notes type: object APIError: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/APIError.json format: uri readOnly: true type: string code: description: Machine-readable error code; retained for compatibility. type: string current_tier: description: Caller's effective tier type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string reason: description: >- More specific recovery reason when available: missing_api_key, invalid_api_key, insufficient_tier, invalid_parameters, or account_suspended. Account suspensions return 403 with code ACCOUNT_SUSPENDED; contact support rather than retrying or upgrading. type: string required_tier: description: Minimum tier for this operation type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upgrade_url: description: Where to upgrade type: string type: object EntryBin: additionalProperties: false properties: longAccounts: description: Long positions with an entry in this bin. format: int64 type: integer longNotional: description: >- All cohorts' open long notional with an entry in this bin, USD. Includes positions whose wallet has no tier. format: double type: number priceHigh: description: >- 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. format: double type: number priceLow: description: Lower bound of the bin, USD per unit (inclusive). format: double type: number shortAccounts: description: Short positions with an entry in this bin. format: int64 type: integer shortNotional: description: All cohorts' open short notional with an entry in this bin, USD. format: double type: number tiers: description: >- Per-cohort split of this bin, most notional first; cohorts with nothing in the bin are omitted. items: $ref: '#/components/schemas/EntryBinTier' type: - array - 'null' required: - priceLow - priceHigh - longNotional - shortNotional - longAccounts - shortAccounts - tiers type: object CohortEntrySummary: additionalProperties: false properties: accounts: description: Open positions (= wallets) on this side. format: int64 type: integer avgEntryPx: description: >- Notional-weighted average entry price over priced positions, USD per unit; null when nothing is priced. format: double type: - number - 'null' avgLeverage: description: >- Notional-weighted average leverage (x) over positions with a stored leverage; null when none has one. format: double type: - number - 'null' flatNotional: description: Priced notional whose entry equals the reference mark, USD. format: double type: number inProfitNotional: description: >- Priced notional strictly on the right side of the reference mark (long: entry < mark; short: entry > mark), USD. Fees and funding are not included. format: double type: number inProfitShare: description: >- inProfitNotional / pricedNotional, 0 to 1; null when nothing is priced or there is no mark. format: double type: - number - 'null' leverageCoveredNotional: description: Notional behind avgLeverage, USD. format: double type: number nearLiqNotional: description: >- Notional whose stored liquidation price is within nearLiqPct of the reference mark, USD. format: double type: number notional: description: >- Open notional, USD, INCLUDING positions without an entry price — reconciles with /live/cohort-bias. format: double type: number outsideRangeNotional: description: Priced notional whose entry falls outside the bin range, USD. format: double type: number pricedNotional: description: >- Notional with a stored entry price, USD: the denominator of avgEntryPx, inProfitShare and the bins. format: double type: number side: description: long or short. type: string tier: description: Legacy tier slug. type: string underwaterNotional: description: >- Priced notional strictly on the wrong side of the reference mark, USD. format: double type: number unknownProfitNotional: description: >- Notional whose side of the mark cannot be told: unpriced positions, or everything when there is no reference mark. USD. format: double type: number unpricedAccounts: description: Positions without a stored entry price. format: int64 type: integer unpricedNotional: description: >- Notional without a stored entry price, USD. In notional, in no bin, and unknownProfitNotional. format: double type: number required: - tier - side - notional - accounts - pricedNotional - unpricedNotional - unpricedAccounts - avgEntryPx - avgLeverage - leverageCoveredNotional - inProfitNotional - underwaterNotional - flatNotional - unknownProfitNotional - inProfitShare - nearLiqNotional - outsideRangeNotional type: object PositioningCoverage: additionalProperties: false properties: positions: description: >- Open positions on the market with notional > 10 (the rows every total is built from). format: int64 type: integer withoutEntry: description: >- Positions with no stored entry price. In notional totals; in no bin; unknownProfitNotional. format: int64 type: integer withoutEntryNotional: description: Their notional, USD. format: double type: number withoutLeverage: description: Positions with no stored leverage, excluded from avgLeverage only. format: int64 type: integer withoutTier: description: >- 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. format: int64 type: integer required: - positions - withoutTier - withoutEntry - withoutEntryNotional - withoutLeverage type: object PositioningSideTotals: additionalProperties: false properties: accounts: description: Positions on this side, market-wide. format: int64 type: integer inRangeAccounts: description: Positions inside the bin range. format: int64 type: integer inRangeNotional: description: >- Priced notional whose entry falls inside the bin range (the sum of the bins), USD. format: double type: number notional: description: >- Open notional on this side, market-wide, including unpriced positions, USD. format: double type: number outsideRangeAccounts: description: Positions whose entry is outside the bin range. format: int64 type: integer outsideRangeNotional: description: Priced notional whose entry is outside the bin range, USD. format: double type: number pricedNotional: description: Notional with a stored entry price, USD. format: double type: number unpricedAccounts: description: Positions without a stored entry price. format: int64 type: integer unpricedNotional: description: Notional without a stored entry price, USD (in no bin). format: double type: number required: - notional - accounts - pricedNotional - unpricedNotional - unpricedAccounts - inRangeNotional - inRangeAccounts - outsideRangeNotional - outsideRangeAccounts type: object PositioningSource: additionalProperties: false properties: asOf: description: >- When this body was computed, Unix ms. Preserved on cache hits (the route cache refreshes every 30 s). format: int64 type: integer cadence: description: How the underlying rows refresh. type: string kind: description: >- Always 'snapshot': the current open book, never history. Do not present as a time series. type: string medianAgeS: description: Median age of the positions' updated_at at compute time, seconds. format: int64 type: integer newestRow: description: >- 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. format: int64 type: integer oldestRow: description: >- Earliest updated_at across the positions used, Unix ms. Rows are refreshed per wallet, so a body mixes observation times. format: int64 type: integer table: description: >- Always live_positions: every open Hyperliquid position, upserted by the syncer as wallets are polled. type: string required: - table - kind - asOf - newestRow - oldestRow - medianAgeS - cadence type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object EntryBinTier: additionalProperties: false properties: longAccounts: description: >- Long positions in this bin. One row per wallet per market, so positions and accounts are the same count. format: int64 type: integer longNotional: description: >- Open long notional with an entry price in this bin, USD (position size x last polled mark). format: double type: number shortAccounts: description: Short positions in this bin. format: int64 type: integer shortNotional: description: Open short notional with an entry price in this bin, USD. format: double type: number tier: description: >- Legacy tier slug (money_printer, exit_liquidity, ...; or leviathan ... shrimp for tierType=size). type: string required: - tier - longNotional - shortNotional - longAccounts - shortAccounts type: object headers: X-Billing-Grace-Expires: description: RFC3339 time when billing grace expires, when applicable. schema: type: string X-Billing-State: description: Billing grace state, when applicable. schema: type: string X-RateLimit-Daily: description: >- Daily account allowance reported by the existing counter check, clamped at zero. Best-effort; present only for a capped tier that reaches the quota check. schema: type: string X-RateLimit-Daily-Reset: description: >- Unix seconds (UTC) after the selected daily quota bucket expires. Not a source-data timestamp. schema: type: string X-RateLimit-Monthly: description: >- Monthly account allowance reported by the existing counter check, clamped at zero. Best-effort; present only for a capped tier that reaches the quota check. schema: type: string X-RateLimit-Monthly-Reset: description: >- Unix seconds (UTC) after the selected monthly quota bucket expires. Follows the existing billing anchor. schema: type: string X-RateLimit-Next: description: >- Legacy Go duration string until the next token is available across the checked buckets; not the daily/monthly reset. schema: type: string X-RateLimit-Remaining: description: >- Minimum remaining tokens across the checked minute and per-route token buckets (account for keys, IP for anonymous requests). Not a fixed-window request allowance. schema: type: string X-RateLimit-Reset: description: >- Unix seconds (UTC), rounded up, when the checked token buckets next permit a request, assuming no competing traffic. Not a full bucket refill. schema: type: string X-RateLimit-Route: description: Remaining tokens in the account's per-route token bucket. schema: type: string X-RateLimit-Scope: description: >- account for authenticated requests (shared across keys); ip for anonymous requests. Describes the limiter scope, not the key's resolved tier. schema: type: string X-RateLimit-Tier: description: Effective tier for this request; only present after access checks pass. schema: type: string X-Request-ID: description: >- Server-generated correlation ID. Include it in a support report; not a guarantee that an unauthenticated request appears in account usage logs. schema: type: string Retry-After: description: >- On HTTP 429, whole seconds to wait before retrying, rounded up. Other traffic may still consume the available allowance. schema: type: string securitySchemes: apiKey: description: >- Create an API key at https://developers.coinversa.ai/keys. REST limits are shared across keys by account; access uses the effective tier of the presented key. in: header name: X-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.