curl --request GET \
--url https://api.0xarchive.io/v1/lighter/positions/{symbol} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.0xarchive.io/v1/lighter/positions/{symbol}"
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.0xarchive.io/v1/lighter/positions/{symbol}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.0xarchive.io/v1/lighter/positions/{symbol}"
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))
}{
"success": true,
"data": [
{
"symbol": "BTC",
"coin": "BTC",
"size": "12.5",
"side": "long",
"entry_price": "64210.5",
"mark_price": "65020.1",
"position_value": "812751.25",
"unrealized_pnl": "10120.2",
"leverage_type": "cross",
"liquidation_price": "51000",
"quality": "complete",
"snapshot_ts": "2023-11-07T05:31:56Z",
"user_address": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
"account_index": "513030",
"account_kind": "user",
"dex": "xyz"
}
],
"meta": {
"count": 123,
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"next_cursor": "<string>",
"as_of": "2023-11-07T05:31:56Z",
"snapshot_ts": "2023-11-07T05:31:56Z",
"source": "snapshot",
"quality": "<string>",
"stale": true,
"built_through": "2023-11-07T05:31:56Z",
"finalized_through": "2023-11-07T05:31:56Z",
"requested_end": "2023-11-07T05:31:56Z",
"clamped_to": "2023-11-07T05:31:56Z",
"totals": {
"snapshot_ts": "2023-11-07T05:31:56Z",
"symbol": "BTC",
"coin": "BTC",
"long_count": 18234,
"short_count": 15102,
"long_size": "8123.45",
"short_size": "8120.1",
"long_value": "528000000.5",
"short_value": "527800000.25",
"long_avg_entry_price": "63120.4",
"short_avg_entry_price": "66210.9",
"long_positions_with_entry": 18230,
"short_positions_with_entry": 15100,
"long_top10_value_share": "0.412345",
"short_top10_value_share": "0.385",
"top10_value_share": "0.301",
"quality": "complete",
"dex": "xyz"
},
"coverage_from": "2023-11-07T05:31:56Z",
"notice": "<string>"
}
}{
"code": 400,
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"error_code": "invalid_query_params",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}{
"code": 401,
"error": "Missing or invalid API key. Provide X-API-Key header."
}{
"code": 404,
"error": "Resource not found"
}{
"code": 409,
"error": "The snapshot this cursor was paging has been replaced or has expired. Restart pagination without a cursor.",
"error_code": "snapshot_advanced"
}{
"code": 429,
"error": "Rate limit exceeded"
}{
"code": 503,
"error": "Account positions are not available right now.",
"error_code": "positions_unavailable"
}Get Lighter market positions
0xArchive API reference for Get Lighter market positions. Includes authentication, parameters, response shape, examples, and route-safe implementation notes.
curl --request GET \
--url https://api.0xarchive.io/v1/lighter/positions/{symbol} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.0xarchive.io/v1/lighter/positions/{symbol}"
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.0xarchive.io/v1/lighter/positions/{symbol}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.0xarchive.io/v1/lighter/positions/{symbol}"
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))
}{
"success": true,
"data": [
{
"symbol": "BTC",
"coin": "BTC",
"size": "12.5",
"side": "long",
"entry_price": "64210.5",
"mark_price": "65020.1",
"position_value": "812751.25",
"unrealized_pnl": "10120.2",
"leverage_type": "cross",
"liquidation_price": "51000",
"quality": "complete",
"snapshot_ts": "2023-11-07T05:31:56Z",
"user_address": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
"account_index": "513030",
"account_kind": "user",
"dex": "xyz"
}
],
"meta": {
"count": 123,
"request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"next_cursor": "<string>",
"as_of": "2023-11-07T05:31:56Z",
"snapshot_ts": "2023-11-07T05:31:56Z",
"source": "snapshot",
"quality": "<string>",
"stale": true,
"built_through": "2023-11-07T05:31:56Z",
"finalized_through": "2023-11-07T05:31:56Z",
"requested_end": "2023-11-07T05:31:56Z",
"clamped_to": "2023-11-07T05:31:56Z",
"totals": {
"snapshot_ts": "2023-11-07T05:31:56Z",
"symbol": "BTC",
"coin": "BTC",
"long_count": 18234,
"short_count": 15102,
"long_size": "8123.45",
"short_size": "8120.1",
"long_value": "528000000.5",
"short_value": "527800000.25",
"long_avg_entry_price": "63120.4",
"short_avg_entry_price": "66210.9",
"long_positions_with_entry": 18230,
"short_positions_with_entry": 15100,
"long_top10_value_share": "0.412345",
"short_top10_value_share": "0.385",
"top10_value_share": "0.301",
"quality": "complete",
"dex": "xyz"
},
"coverage_from": "2023-11-07T05:31:56Z",
"notice": "<string>"
}
}{
"code": 400,
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"error_code": "invalid_query_params",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}{
"code": 401,
"error": "Missing or invalid API key. Provide X-API-Key header."
}{
"code": 404,
"error": "Resource not found"
}{
"code": 409,
"error": "The snapshot this cursor was paging has been replaced or has expired. Restart pagination without a cursor.",
"error_code": "snapshot_advanced"
}{
"code": 429,
"error": "Rate limit exceeded"
}{
"code": 503,
"error": "Account positions are not available right now.",
"error_code": "positions_unavailable"
}X-API-Key with this request. See REST authentication.Shared request rules
Shared request rules
Machine schema
Machine schema
Authorizations
API key for authentication. Get yours at https://0xarchive.io/dashboard
Path Parameters
Lighter perpetual symbol (e.g. BTC). Spot markets have no positions. Pass it exactly as the instruments route lists it, in uppercase.
"BTC"
Query Parameters
Committed hourly snapshot to read, as an exact UTC hour in Unix milliseconds. Echoed as meta.snapshot_ts. Defaults to the latest live snapshot.
Only long or only short positions.
long, short Only positions worth at least this much in USD.
x >= 0Include settlement, insurance, and other system accounts (excluded by default).
Maximum rows per page (default 100, max 2000).
1 <= x <= 2000Cursor from the previous response meta.next_cursor. Keep every other parameter unchanged.
Response
Get Lighter market positions
Open positions in a market or across markets.
true
Hide child attributes
Hide child attributes
Market symbol (HIP-3: dex:COIN).
"BTC"
Alias of symbol.
"BTC"
Signed position size in base units.
"12.5"
long, short "long"
Average entry price.
"64210.5"
Mark price.
"65020.1"
Absolute position value in USD. Listings sort by this value, largest first.
"812751.25"
Unrealized PnL in USD.
"10120.2"
cross, isolated, or unknown (Lighter: the margin mode).
"cross"
Reported liquidation price. Hyperliquid only; null on Lighter.
"51000"
Quality of this row. complete, partial (a mark or entry is missing, so value and PnL fields are null), or degraded. Lighter rows can also read preliminary (built from real-time trades not yet reconciled), unreconciled (a market with no reconciled trades), or incomplete. No row reads complete when its own data is not complete, or when its snapshot has a problem that could not be pinned to specific rows. A small number of Hyperliquid positions around three short windows in June and July 2025, where Hyperliquid's published fill data has gaps, read partial.
"complete"
Hour the row describes. Present on bulk /positions rows.
Hyperliquid and HIP-3 only: wallet address holding the position (lowercase).
"0x31ca8395cf837de08b24da3f660e77761dfb974b"
Lighter only: account index as a string.
"513030"
Lighter only: user, insurance, settlement, or system.
"user"
HIP-3 only: dex of the market.
"xyz"
Response metadata of the account positions routes. Every instant is RFC 3339 UTC with milliseconds and comes from the data, never the request time.
Hide child attributes
Hide child attributes
Number of records returned.
Unique request ID for support.
Signed cursor for the next page, bound to the request. Pass it back with the same parameters. A market cursor pins its snapshot; if that snapshot is replaced or expires the next page answers 409 snapshot_advanced.
Instant the returned state describes: the snapshot tick or hour, or the requested as-of time.
Committed snapshot the response was read from. Market routes echo the resolved hour here.
How the rows were produced: snapshot (live or hourly snapshot), reconstructed (as-of state between snapshots), or changes (change log).
snapshot, reconstructed, changes Completeness of the snapshot the response was read from: complete, partial, or degraded. Rows carry their own quality. On Lighter and Robinhood Chain, snapshots from the latest day, before the venue's daily trade reconcile, can read degraded while their rows read preliminary; they read complete once the reconcile has run.
True on current reads when the latest snapshot is older than 12 minutes; paired with notice.
Every event before this instant is built into the change log and as-of state. Reads are clamped to it.
Every event before this instant is final and will not be re-derived (Lighter: the trade finalization watermark). Never later than built_through.
The end or timestamp the caller asked for, echoed when the read was clamped.
Boundary the read was clamped to (built_through). Present only when clamped.
Market listings, first page only: aggregates over the whole filtered result set, not just this page.
Hide child attributes
Hide child attributes
Snapshot the aggregates describe.
"BTC"
Alias of symbol.
"BTC"
18234
15102
Total long size in base units.
"8123.45"
Total short size in base units.
"8120.1"
Total long value in USD. Null when any long position has no mark.
"528000000.5"
Total short value in USD. Null when any short position has no mark.
"527800000.25"
Size-weighted average entry of long positions with a known entry.
"63120.4"
Size-weighted average entry of short positions with a known entry.
"66210.9"
18230
15100
Share of long value held by the ten largest long positions.
"0.412345"
Share of short value held by the ten largest short positions.
"0.385"
Share of total value held by the ten largest positions.
"0.301"
complete, partial, or degraded, from this market's own rows.
"complete"
HIP-3 only.
"xyz"
Coverage start, present with notice when the request falls before coverage or the address has no recorded activity.
Human-readable advisory: before coverage, no recorded activity, or a stale snapshot.
Was this page helpful?