Lighter - Positions

Get Lighter account positions

Open positions of one account: the latest live snapshot, or the state at timestamp. The first page of a snapshot read without symbol also returns the account's position aggregates. An empty result reports account_seen. The change log and hourly history start January 17, 2025; live snapshots refresh every 2 minutes. Rows past the trade finalization watermark are preliminary (finalized: false). Billed at 1 credit per 1,000 rows returned, minimum 1 credit per request.

get/v1/lighter/accounts/{account_index}/positions

Request

  • Base URL: https://api.0xarchive.io
  • URL: https://api.0xarchive.io/v1/lighter/accounts/{account_index}/positions
  • Auth: API key in header X-API-Key

Path parameters

account_indexstring required
Example:513030

Lighter account index (an integer). Resolve an L1 address on Lighter mainnet with GET /v1/lighter/accounts?l1_address=0x...

Query parameters

integer

Unix milliseconds.

OR
string date-time

RFC 3339 instant.

Example:1767225600000

As-of instant: the state after every event before it. An exact hour with a committed snapshot serves that snapshot; any other instant is reconstructed (meta.source: reconstructed) and clamped to meta.built_through. Omit for the latest live snapshot. Accepts Unix milliseconds or an RFC 3339 UTC string such as 2026-01-01T00:00:00Z.

symbolstring

Only this perpetual (e.g. BTC). Pass it exactly as the instruments route lists it, in uppercase.

limitinteger

Maximum rows per page (default 500, max 5000).

cursorstring

Opaque pagination cursor: pass meta.next_cursor from the previous page unchanged, with the same filters. Omit it for the first page. Keep every other parameter unchanged.

Response

Get Lighter account positions

successboolean required

Example response

{
  "success": true,
  "data": {
    "positions": [
      {
        "account_index": "281474976710654",
        "account_kind": "user",
        "symbol": "BTC",
        "coin": "BTC",
        "dex": "xyz",
        "size": "-0.5",
        "side": "short",
        "entry_price": "64210.5",
        "mark_price": "65020.1",
        "position_value": "32510.05",
        "unrealized_pnl": "-404.8",
        "return_on_equity": "-0.1245",
        "leverage": {
          "type": "cross",
          "value": "20"
        },
        "max_leverage": 40,
        "margin_used": "1625.5",
        "liquidation_price": "81250",
        "liquidation_price_status": "exact",
        "cum_funding": {
          "all_time": "-12.345678",
          "since_open": "-1.25",
          "since_change": "-0.5"
        },
        "quality": "complete",
        "initial_margin_fraction": "0.05",
        "allocated_margin": "1200.5",
        "margin_mode": "cross",
        "mark_source": "mark",
        "finalized": true
      }
    ],
    "account": {
      "account_index": "513030",
      "dex": "xyz",
      "account_value": "125000.5",
      "cross_account_value": "118000.25",
      "collateral": "100000",
      "total_margin_used": "20500.75",
      "cross_maintenance_margin_used": "6100.2",
      "total_position_value": "412000.5",
      "total_unrealized_pnl": "2510.25",
      "long_value": "300000",
      "short_value": "112000.5",
      "n_positions": 4,
      "account_mode": "standard",
      "quality": "complete"
    }
  },
  "meta": {
    "totals": {
      "symbol": "BTC",
      "coin": "BTC",
      "dex": "xyz",
      "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"
    },
    "symbol": "BTC",
    "venue": "hyperliquid"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.