curl --request GET \
--url https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"binSize": 123,
"bins": [
{
"longAccounts": 123,
"longNotional": 123,
"priceHigh": 123,
"priceLow": 123,
"shortAccounts": 123,
"shortNotional": 123,
"tiers": [
{
"longAccounts": 123,
"longNotional": 123,
"shortAccounts": 123,
"shortNotional": 123,
"tier": "<string>"
}
]
}
],
"cohortBasis": "<string>",
"cohorts": [
{
"accounts": 123,
"avgEntryPx": 123,
"avgLeverage": 123,
"flatNotional": 123,
"inProfitNotional": 123,
"inProfitShare": 123,
"leverageCoveredNotional": 123,
"nearLiqNotional": 123,
"notional": 123,
"outsideRangeNotional": 123,
"pricedNotional": 123,
"side": "<string>",
"tier": "<string>",
"underwaterNotional": 123,
"unknownProfitNotional": 123,
"unpricedAccounts": 123,
"unpricedNotional": 123
}
],
"coin": "<string>",
"coverage": {
"positions": 123,
"withoutEntry": 123,
"withoutEntryNotional": 123,
"withoutLeverage": 123,
"withoutTier": 123
},
"long": {
"accounts": 123,
"inRangeAccounts": 123,
"inRangeNotional": 123,
"notional": 123,
"outsideRangeAccounts": 123,
"outsideRangeNotional": 123,
"pricedNotional": 123,
"unpricedAccounts": 123,
"unpricedNotional": 123
},
"markAsOf": 123,
"markDivergencePct": 123,
"markMethod": "<string>",
"markPx": 123,
"markSource": "<string>",
"nearLiqPct": 123,
"notes": [
"<string>"
],
"rangeHigh": 123,
"rangeLow": 123,
"short": {
"accounts": 123,
"inRangeAccounts": 123,
"inRangeNotional": 123,
"notional": 123,
"outsideRangeAccounts": 123,
"outsideRangeNotional": 123,
"pricedNotional": 123,
"unpricedAccounts": 123,
"unpricedNotional": 123
},
"source": {
"asOf": 123,
"cadence": "<string>",
"kind": "<string>",
"medianAgeS": 123,
"newestRow": 123,
"oldestRow": 123,
"table": "<string>"
},
"storedMark": 123,
"storedMarkAsOf": 123,
"tierType": "<string>",
"tierWindowDays": 123,
"$schema": "https://api.coinversa.ai/schemas/PositioningByEntryBody.json"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}Get API public v1 live positioning by entry by coin
curl --request GET \
--url https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coinversa.ai/api/public/v1/live/positioning-by-entry/{coin}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"binSize": 123,
"bins": [
{
"longAccounts": 123,
"longNotional": 123,
"priceHigh": 123,
"priceLow": 123,
"shortAccounts": 123,
"shortNotional": 123,
"tiers": [
{
"longAccounts": 123,
"longNotional": 123,
"shortAccounts": 123,
"shortNotional": 123,
"tier": "<string>"
}
]
}
],
"cohortBasis": "<string>",
"cohorts": [
{
"accounts": 123,
"avgEntryPx": 123,
"avgLeverage": 123,
"flatNotional": 123,
"inProfitNotional": 123,
"inProfitShare": 123,
"leverageCoveredNotional": 123,
"nearLiqNotional": 123,
"notional": 123,
"outsideRangeNotional": 123,
"pricedNotional": 123,
"side": "<string>",
"tier": "<string>",
"underwaterNotional": 123,
"unknownProfitNotional": 123,
"unpricedAccounts": 123,
"unpricedNotional": 123
}
],
"coin": "<string>",
"coverage": {
"positions": 123,
"withoutEntry": 123,
"withoutEntryNotional": 123,
"withoutLeverage": 123,
"withoutTier": 123
},
"long": {
"accounts": 123,
"inRangeAccounts": 123,
"inRangeNotional": 123,
"notional": 123,
"outsideRangeAccounts": 123,
"outsideRangeNotional": 123,
"pricedNotional": 123,
"unpricedAccounts": 123,
"unpricedNotional": 123
},
"markAsOf": 123,
"markDivergencePct": 123,
"markMethod": "<string>",
"markPx": 123,
"markSource": "<string>",
"nearLiqPct": 123,
"notes": [
"<string>"
],
"rangeHigh": 123,
"rangeLow": 123,
"short": {
"accounts": 123,
"inRangeAccounts": 123,
"inRangeNotional": 123,
"notional": 123,
"outsideRangeAccounts": 123,
"outsideRangeNotional": 123,
"pricedNotional": 123,
"unpricedAccounts": 123,
"unpricedNotional": 123
},
"source": {
"asOf": 123,
"cadence": "<string>",
"kind": "<string>",
"medianAgeS": 123,
"newestRow": 123,
"oldestRow": 123,
"table": "<string>"
},
"storedMark": 123,
"storedMarkAsOf": 123,
"tierType": "<string>",
"tierWindowDays": 123,
"$schema": "https://api.coinversa.ai/schemas/PositioningByEntryBody.json"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}{
"$schema": "https://api.coinversa.ai/schemas/APIError.json",
"code": "<string>",
"current_tier": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"reason": "<string>",
"required_tier": "<string>",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upgrade_url": "<string>"
}Authorizations
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.
Path Parameters
Market symbol, e.g. BTC or xyz:GOLD. Case and surrounding whitespace are normalized; the body echoes the canonical spelling.
Query Parameters
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.
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.
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).
pnl, pnl_recent, size Number of equal-width entry-price bins across the range.
1 <= x <= 200Percentage 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.
1 <= x <= 100Response
OK
Width of one bin, USD.
Ascending price bins; empty when there are no positions or no mark.
Show child attributes
Show child attributes
Human label of the axis: all_time_pnl, recent_30d_pnl or lifetime_volume.
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.
Show child attributes
Show child attributes
Canonical market symbol.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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).
(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.
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.
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).
Which feed or table the reference mark came from.
The distance, in percent of mark, that defines nearLiqNotional.
Caveats the chart should label: snapshot not history, mixed observation times, unpriced and untiered positions.
Highest entry price covered by the bins, USD.
Lowest entry price covered by the bins, USD.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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.
updated_at of the row the stored mark came from, Unix ms; zero when unknown.
Cohort axis used: pnl, pnl_recent or size.
Rolling window the tier labels are computed over, days; null for all-time axes (pnl, size).
A URL to the JSON Schema for this object.
"https://api.coinversa.ai/schemas/PositioningByEntryBody.json"