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

timestampinteger

As-of instant in Unix milliseconds: 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.

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

Cursor from the previous response meta.next_cursor. 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"
    }
  }
}

Changes

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