Get Lighter account position changes

curl --request GET \
  --url https://api.0xarchive.io/v1/lighter/accounts/{account_index}/positions/changes \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.0xarchive.io/v1/lighter/accounts/{account_index}/positions/changes"

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/accounts/{account_index}/positions/changes', 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/accounts/{account_index}/positions/changes"

	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": [
    {
      "timestamp": "2026-09-25T14:03:11.482Z",
      "symbol": "BTC",
      "coin": "BTC",
      "side": "B",
      "price": "65010.2",
      "size": "0.25",
      "start_position": "-0.5",
      "end_position": "-0.25",
      "entry_price_after": "64210.5",
      "event_type": "reduce",
      "cause": "trade",
      "fee": "0.4875",
      "fee_token": "USDC",
      "trade_id": 26121110211,
      "order_id": 844421856609148,
      "opened_at": "2023-11-07T05:31:56Z",
      "continuity": "ok",
      "finalized": true,
      "account_index": "513030",
      "account_kind": "user",
      "dex": "xyz",
      "direction": "Close Short",
      "closed_pnl": "19.9",
      "realized_pnl": "19.9",
      "crossed": true,
      "is_maker": false,
      "seq": 0,
      "block_number": 745512345,
      "event_index": 12,
      "position_size_before": "-0.5",
      "position_size_after": "-0.25",
      "fee_rate": "0.00002",
      "fee_usdc": "0.325",
      "usdc_amount": "16252.55"
    }
  ],
  "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": 429,
  "error": "Rate limit exceeded"
}

{
  "code": 503,
  "error": "Account positions are not available right now.",
  "error_code": "positions_unavailable"
}

GET

https://api.0xarchive.io

lighter

accounts

{account_index}

positions

changes

Get Lighter account position changes

curl --request GET \
  --url https://api.0xarchive.io/v1/lighter/accounts/{account_index}/positions/changes \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.0xarchive.io/v1/lighter/accounts/{account_index}/positions/changes"

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/accounts/{account_index}/positions/changes', 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/accounts/{account_index}/positions/changes"

	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": [
    {
      "timestamp": "2026-09-25T14:03:11.482Z",
      "symbol": "BTC",
      "coin": "BTC",
      "side": "B",
      "price": "65010.2",
      "size": "0.25",
      "start_position": "-0.5",
      "end_position": "-0.25",
      "entry_price_after": "64210.5",
      "event_type": "reduce",
      "cause": "trade",
      "fee": "0.4875",
      "fee_token": "USDC",
      "trade_id": 26121110211,
      "order_id": 844421856609148,
      "opened_at": "2023-11-07T05:31:56Z",
      "continuity": "ok",
      "finalized": true,
      "account_index": "513030",
      "account_kind": "user",
      "dex": "xyz",
      "direction": "Close Short",
      "closed_pnl": "19.9",
      "realized_pnl": "19.9",
      "crossed": true,
      "is_maker": false,
      "seq": 0,
      "block_number": 745512345,
      "event_index": 12,
      "position_size_before": "-0.5",
      "position_size_after": "-0.25",
      "fee_rate": "0.00002",
      "fee_usdc": "0.325",
      "usdc_amount": "16252.55"
    }
  ],
  "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": 429,
  "error": "Rate limit exceeded"
}

{
  "code": 503,
  "error": "Account positions are not available right now.",
  "error_code": "positions_unavailable"
}

API key required. Send X-API-Key with this request. See REST authentication.

Shared request rules

Machine schema

Open the generated operation schema for machine-readable request and response details.

Authorizations

X-API-Key

string

header

required

API key for authentication. Get yours at https://0xarchive.io/dashboard

Path Parameters

account_index

string

required

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

Pattern: ^[0-9]+$

Example:

"513030"

Query Parameters

start

integer<int64>

Inclusive start in Unix milliseconds. Defaults to 24 hours before end.

end

integer<int64>

Exclusive end in Unix milliseconds. Defaults to now.

symbol

string

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

limit

integer

default:500

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

Required range: 1 <= x <= 5000

cursor

string

Cursor from the previous response meta.next_cursor. Keep every other parameter unchanged.

Response

Get Lighter account position changes

Position change log legs in timestamp order.

success

boolean

required

Example:

true

data

object[]

required

Hide child attributes

data.timestamp

string<date-time>

required

Execution time (UTC).

Example:

"2026-09-25T14:03:11.482Z"

data.symbol

string

required

Market symbol (HIP-3: dex:COIN).

Example:

"BTC"

data.coin

string

required

Alias of symbol.

Example:

"BTC"

data.side

enum<string>

required

Side of this account in the trade, exactly as on the trades routes: B (buy) or A (sell).

Available options:

B,

A

Example:

"B"

data.price

string | null

required

Execution price.

Example:

"65010.2"

data.size

string | null

required

Traded size in base units.

Example:

"0.25"

data.start_position

string | null

required

Signed position size before the leg.

Example:

"-0.5"

data.end_position

string | null

required

Signed position size after the leg.

Example:

"-0.25"

data.entry_price_after

string | null

required

Average entry price after the leg. Null when the position is flat after it.

Example:

"64210.5"

data.event_type

string

required

Effect on the position: open, increase, reduce, close, or flip. Lighter also reports settlement (the settlement counterparty side of a market settlement) and unchanged.

Example:

"reduce"

data.cause

string

required

Why the leg happened: trade, liquidation, liquidation_counterparty, adl, settlement, or unknown.

Example:

"trade"

data.fee

string | null

required

Fee paid for the leg (negative is a rebate).

Example:

"0.4875"

data.fee_token

string

required

Asset the fee is paid in: USDC on Hyperliquid and Lighter mainnet, USDG on Lighter on Robinhood Chain.

Example:

"USDC"

data.trade_id

integer<int64>

required

Trade ID, shared by both legs of a trade.

Example:

26121110211

data.order_id

integer<int64> | null

required

Order ID of this account.

Example:

844421856609148

data.opened_at

string<date-time> | null

required

Start of the position lifecycle this leg belongs to. Null when it opened before coverage.

data.continuity

enum<string>

required

ok when start_position continues the previous leg exactly, inferred when it was bridged, first_seen for the first leg recorded for the account and market, quarantined when the chain is broken and the leg is held out of position state.

Available options:

ok,

inferred,

first_seen,

quarantined

Example:

"ok"

data.finalized

boolean

required

True when the leg is final and will not be re-derived.

Example:

true

data.account_index

string

Lighter only: account index as a string.

Example:

"513030"

data.account_kind

string

Lighter only: user, insurance, settlement, or system.

Example:

"user"

data.dex

string

HIP-3 only: dex of the market.

Example:

"xyz"

data.direction

string

Hyperliquid and HIP-3 only: direction label as reported by Hyperliquid (for example Close Short).

Example:

"Close Short"

data.closed_pnl

string | null

Hyperliquid and HIP-3 only: realized PnL of the leg in USD.

Example:

"19.9"

data.realized_pnl

string

Lighter only: realized PnL of the leg in the quote asset (0 on open and increase).

Example:

"19.9"

data.crossed

boolean

Hyperliquid and HIP-3 only: true when this account was the taker.

Example:

true

data.is_maker

boolean

Lighter only: true when this account was the maker.

Example:

false

data.seq

integer

Hyperliquid and HIP-3 only: order of legs that share a timestamp.

Example:

0

data.block_number

integer<int64>

Hyperliquid and HIP-3 only, present when known (from September 17, 2026): block that executed the leg.

Example:

745512345

data.event_index

integer

Hyperliquid and HIP-3 only, present with block_number: execution order within the block.

Example:

12

data.position_size_before

string

Lighter only: alias of start_position.

Example:

"-0.5"

data.position_size_after

string

Lighter only: alias of end_position.

Example:

"-0.25"

data.fee_rate

string | null

Lighter only: fee rate as a decimal ratio.

Example:

"0.00002"

data.fee_usdc

string | null

Lighter only: fee in the quote asset, computed from the notional and the fee rate.

Example:

"0.325"

data.usdc_amount

string

Lighter only: notional of the leg in the quote asset.

Example:

"16252.55"

API reference

SDKs & tooling

AI & agents

Get Lighter account position changes

Authorizations

Path Parameters

Query Parameters

Response