📑Positions & Market Exposure
The Positions & Market Exposure endpoints provide comprehensive access to trading position data and market analytics. These endpoints allow you to retrieve detailed position information, analyze market exposure by coin and segment (cohort), rank positions by various metrics, and monitor the overall market landscape across different trader cohorts.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get All Positions (Opened/Closed)
/api/external/positions
Provides a complete historical record of every perpetual position opened or closed on Hyperliquid since April 4, 2025. Each entry includes the venue, symbol, size, cohort and direction, alongside full metrics for valuation and risk-checking like entry price, mark/mid pricing, leverage limits, and margin configuration.
Results also detail accumulated funding, unrealized PnL, and specific lifecycle timestamps where a null closeTime indicates an active position. Liquidation prices were only recorded at closure from April 4 to September 2, 2025, but have updated continuously at each block interval since then. Data for all requested addresses is paginated using the nextCursor field.
Query Parameters
limit
number
Maximum number of positions to return per request.
coin
string
Coin symbol to filter by (for example ETH, BTC, LINEA). If omitted, positions for all coins are returned.
nextCursor
string
Cursor for pagination. Use the nextCursor value from the previous response to fetch the next page.
address
string
One or more wallet addresses to include.
start
string
Start of the time window (ISO 8601, UTC).
end
string
End of the time window (ISO 8601, UTC). If omitted, the API uses “now”.
open
boolean
Filter by position status. true returns only open positions, false returns only closed positions. If omitted, both are returned.
segmentId
number
Filter positions by trader segment (cohort). Available values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16. See Cohorts Legend.
Request Examples
curl --request GET \
--url 'https://api.example.com/api/external/positions?limit=50&orderBy=pnl&order=desc' \
--header 'Authorization: Bearer YOUR_API_TOKEN'const res = await fetch(
'https://api.example.com/api/external/positions?limit=50&orderBy=pnl&order=desc',
{ headers: { Authorization: 'Bearer YOUR_API_TOKEN' } }
);
const data = await res.json();import requests
response = requests.get(
"https://ht-api.coinmarketman.com/api/external/positions",
params={"limit": 50, "orderBy": "pnl", "order": "desc"},
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
},
)
result = response.json()Response
200 Success: Returns a list of positions that match the provided filters. Pagination is supported via
nextCursor.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Positions (Download File)
/api/external/exports/coins/{coin}/positions
Exports position breakdown by size for a selected coin, returning size-segment metrics such as size range, position count, total position value, long position value, value close to liquidation, bias, and past comparison values, along with the export timestamp.
The download link expires quickly (about 120 seconds), so it should be used shortly after it is returned.
Also found on the Downloadable Files subpage here.
Path Parameters
coin
string
Coin symbol (case-insensitive), for example BTC, ETH.
Request Examples
Response
200 Success: Redirects to a temporary pre-signed S3 URL for the requested export file.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Open Position Exposure by Coin
/api/external/positions/coins
Returns a ranked list of all coins currently held in open perpetual positions ordered by total open value descending. Each entry includes the coin ticker, total position value, long and short breakdown, and position counts by side.
Request Examples
Response
200 Success: Returns an array of all coins with open positions on the network, sorted by
totalValuedescending.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Position Breakdown by Cohort (Download File)
/api/external/exports/coins/{coin}/position-breakdown-by-cohort
Exports position breakdown by cohort for the selected coin, returning cohort-level metrics such as segment details, total position value, long position value, position count, value close to liquidation, bias, timestamp, and past comparison values.
The download link expires quickly (about 120 seconds), so it should be used shortly after it is returned.
Also found on the Cohorts subpage here and the Downloadable Files subpage here.
Path Parameters
coin
string
Coin symbol (case-insensitive), for example BTC, ETH.
Request Examples
Response
200 Success: Redirects to a temporary pre-signed S3 URL for the requested export file.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Position Breakdown by Size (Download File)
/api/external/exports/coins/{coin}/position-breakdown-by-size
Returns a 302 redirect to a download link for the Position Breakdown by Size. The downloaded file contains the Positions by Size for the selected coin. The download link expires quickly (about 120 seconds), so it should be used shortly after it is returned.
The download link expires quickly (about 120 seconds), so it should be used shortly after it is returned.
Also found on the Downloadable Files subpage here.
Path Parameters
coin
string
Coin symbol (case-insensitive), for example BTC, ETH.
Request Examples
Response
200 Success: Redirects to a temporary pre-signed S3 URL for the requested export file.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Perpetual Market Overview Metrics
/api/external/position-metrics/general
Returns a time-series of market-wide snapshots powering the Open Interest, Total Open Positions, Open Interest vs Perp Equity, and Positions In Profit charts. Each snapshot includes total open interest with long and short split, total position count with long and short breakdown, total perp equity, and the number of positions currently in profit. Results are paginated using nextCursor.
Query Parameters
limit
string
Maximum number of metric snapshots to return per request.
nextCursor
string
Cursor for pagination. Use the nextCursor value from the previous response to fetch the next page.
start
string
Start of the time window (ISO 8601, UTC).
end
string
End of the time window (ISO 8601, UTC). If omitted, the API uses “now”.
Request Examples
Response
200 Success: Returns a list of general position metric snapshots for the requested time window, plus an optional cursor for pagination.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Position Metrics (Download File)
/api/external/exports/coins/{coin}/position-metrics
Exports position metrics time-series data for the selected coin, including timestamped values for position count, long position count, total position value, and long position value. The columns array defines the order of values in data for easy parsing and analysis.
The download link expires quickly (about 120 seconds), so it should be used shortly after it is returned.
Also found on the Downloadable Files subpage here.
Path Parameters
coin
string
Coin symbol (case-insensitive), for example BTC, ETH.
Request Examples
Response
200 Success: Redirects to a temporary pre-signed S3 URL for the requested export file.
Get Perp Volume Metrics
/api/external/metrics/perp-volume
Returns aggregated perpetual trading volume snapshots over a selected time window. Each entry represents the total perp trading volume observed at a given timestamp, which you can use to build volume charts, compare activity across periods, or power analytics. Results are returned as a time-ordered series and can be paginated using nextCursor.
Query Parameters
limit
number
Maximum number of metric snapshots to return per request.
nextCursor
string
Cursor for pagination. Use the nextCursor value from the previous response to fetch the next page.
start
string
Required. Start of the time window (ISO 8601, UTC).
end
string
End of the time window (ISO 8601, UTC). If omitted, the API uses “now”.
Request Examples
Response
200 Success: Returns perp volume metrics in JSON format, with a cursor for pagination.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Positions Heatmap
/api/external/positions/heatmap
Retrieves a heatmap style overview of open positions across all coins and trader segments (cohorts). This gives you a quick visual snapshot of where different trader groups are positioned, how much value they hold, and whether they are leaning long or short across the market.
Also found on the Cohorts subpage here.
Request Examples
Response
200 Success: Returns an aggregated positional heatmap across coins and segments.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Coin Positioning, PnL and Funding Over Time
/api/external/position-metrics/coin/{coin}
Returns a time-series of aggregated perpetual position data for a specific coin. Each snapshot includes open position count, total notional exposure, and position size with long and short breakdowns, plus cumulative unrealized PnL and funding costs across all positions for that coin. Results are paginated using nextCursor.
Query Parameters
limit
number
Maximum number of metric rows to return in one response.
nextCursor
string
Cursor for pagination. Pass the value from the previous response to fetch the next page.
start
string
Start of the time window (ISO8601).
end
string
End of the time window (ISO 8601, UTC). If omitted, the API uses “now”.
Request Examples
Response
200 Success: Returns a list of metric snapshots for the requested coin, plus an optional cursor for pagination.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Position Metrics by Coin and Segment
/api/external/position-metrics/coin/{coin}/segment/{segment}
Retrieves time-series position metrics for a specific coin within a specific segment (cohort) over a given time window. Use it to analyze how positioning and exposure for one cohort evolves on a single market, and paginate through longer ranges with nextCursor.
Also found on the Cohorts subpage here.
Query Parameters
limit
number
Maximum number of metric rows to return in one response.
nextCursor
string
Cursor for pagination. Pass the value from the previous response to fetch the next page.
start
string
Start of the time window (ISO8601).
end
string
End of the time window (ISO8601).
Request Examples
Response
200 Success: Returns an array of position metric rows plus
nextCursorwhen more results are available.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Position Metrics by Coin and Position Size Buckets
/api/external/position-metrics/coin/{coin}/position-size-bucket/{sizeBucketId}
Returns a time-series of position metrics for a specific coin, filtered by position size bucket. Size buckets segment positions from retail (<$1k) through to whale (>$2.5m), allowing granular analysis of how different trader size groups are positioned in a given asset. Each snapshot includes position count and total position value with long and short breakdown. Results are paginated using nextCursor.
Path Parameters
coin
string
Coin ticker (for example BTC, ETH).
sizeBucketId
number
Position size bucket key. See bucket definitions below.
Query Parameters
limit
number
Maximum number of metric rows to return in one response.
start
string
Start of the time window (ISO8601).
end
string
End of the time window (ISO8601).
nextCursor
string
Cursor for pagination. Pass the value from the previous response to fetch the next page.
Size Bucket Reference
1
<$1k
2
$1k - $10k
3
$10k - $25k
4
$25k - $50k
5
$50k - $100k
6
$100k - $250k
7
$250k - $500k
8
$500k - $1m
9
$1m - $2.5m
10
>$2.5m
Request Examples
Response
200 Success: Returns a paginated array of position metric snapshots for the requested coin and size bucket.
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Liquidation Risk by Asset
api/external/{segmentId}/assets/liquidation-risk
Retrieves the percentage of open interest at high liquidation risk for each asset within a given segment (cohort). It shows how much of the total exposure is close to being liquidated. For example: If BTC has $1,000,000 in total open interest and $100,000 of that is within 75% of the liquidation threshold, then the liquidation risk by asset for XYZ is 10%.
The endpoint can return up to 500 results per request. Lower limits usually result in faster response times.
Also found on the Liquidation Data subpage here and the Cohorts subpage here.
Understanding Liquidation Risk Liquidation risk indicates how close positions are to being liquidated. This data is crucial for monitoring market health and identifying potential cascading liquidation scenarios.
Query Parameters
offset
number
The number of items to skip
limit
number
The maximum number of items to return
Request Examples
Response
200 Success: Returns liquidation risk data by asset
Unique to HyperTracker Users
This endpoint is exclusive to HyperTracker, which independently aggregates and delivers this data beyond what’s available in the standard Hyperliquid API.
Get Liquidation Heatmap (Download File)
/api/external/exports/coins/{coin}/liquidation-heatmap
Exports liquidation heatmap data for the selected coin, returning price-bin ranges with liquidation value, position count, and the most impacted segment for each bin.
The download link expires quickly (about 120 seconds), so it should be used shortly after it is returned.
Also found on the Liquidation Data subpage here and the Downloadable Files subpage here.
Path Parameters
coin
string
Coin symbol (case-insensitive), for example BTC, ETH.
Request Examples
Response
200 Success: Redirects to a temporary pre-signed S3 URL for the requested export file.
Last updated