> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PositionChange Schema

> One leg of the position change log: a trade, liquidation, auto-deleverage, or settlement that changed (or touched) a position, with the position before.

Source OpenAPI: 0xArchive API 1.7.0; 218 paths; 210 component schemas.

One leg of the position change log: a trade, liquidation, auto-deleverage, or settlement that changed (or touched) a position, with the position before and after. Hyperliquid legs carry `direction`, `closed_pnl`, `crossed`, and `seq`; Lighter legs carry `realized_pnl`, `is_maker`, and the Lighter fields at the end.

## Required Fields

| Field | Type | Description |
| - | - | - |
| `cause` | string | Why the leg happened: `trade`, `liquidation`, `liquidation_counterparty`, `adl`, `settlement`, or `unknown`. |
| `coin` | string | Alias of `symbol`. |
| `continuity` | string | `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. |
| `end_position` | string | Signed position size after the leg. |
| `entry_price_after` | string | Average entry price after the leg. |
| `event_type` | string | Effect on the position: `open`, `increase`, `reduce`, `close`, or `flip`. |
| `fee` | string | Fee paid for the leg (negative is a rebate). |
| `fee_token` | string | Asset the fee is paid in: USDC on Hyperliquid and Lighter mainnet, USDG on Lighter on Robinhood Chain. |
| `finalized` | boolean | True when the leg is final and will not be re-derived. |
| `opened_at` | string:date-time | Start of the position lifecycle this leg belongs to. |
| `order_id` | integer:int64 | Order ID of this account. |
| `price` | string | Execution price. |
| `side` | string | Side of this account in the trade, exactly as on the trades routes: `B` (buy) or `A` (sell). |
| `size` | string | Traded size in base units. |
| `start_position` | string | Signed position size before the leg. |
| `symbol` | string | Market symbol (HIP-3: `dex:COIN`). |
| `timestamp` | string:date-time | Execution time (UTC). |
| `trade_id` | integer:int64 | Trade ID, shared by both legs of a trade. |

## JSON Schema

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PositionChange",
  "description": "One leg of the position change log: a trade, liquidation, auto-deleverage, or settlement that changed (or touched) a position, with the position before and after. Hyperliquid legs carry `direction`, `closed_pnl`, `crossed`, and `seq`; Lighter legs carry `realized_pnl`, `is_maker`, and the Lighter fields at the end.",
  "type": "object",
  "required": [
    "cause",
    "coin",
    "continuity",
    "end_position",
    "entry_price_after",
    "event_type",
    "fee",
    "fee_token",
    "finalized",
    "opened_at",
    "order_id",
    "price",
    "side",
    "size",
    "start_position",
    "symbol",
    "timestamp",
    "trade_id"
  ],
  "properties": {
    "account_index": {
      "description": "Lighter only: account index as a string.",
      "type": "string",
      "example": "513030"
    },
    "account_kind": {
      "description": "Lighter only: `user`, `insurance`, `settlement`, or `system`.",
      "type": "string",
      "example": "user"
    },
    "block_number": {
      "description": "Hyperliquid and HIP-3 only, present when known (from September 17, 2026): block that executed the leg.",
      "type": "integer",
      "format": "int64",
      "example": 745512345
    },
    "cause": {
      "description": "Why the leg happened: `trade`, `liquidation`, `liquidation_counterparty`, `adl`, `settlement`, or `unknown`.",
      "type": "string",
      "example": "trade"
    },
    "closed_pnl": {
      "description": "Hyperliquid and HIP-3 only: realized PnL of the leg in USD.",
      "type": "string",
      "nullable": true,
      "example": "19.9"
    },
    "coin": {
      "description": "Alias of `symbol`.",
      "type": "string",
      "example": "BTC"
    },
    "continuity": {
      "description": "`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.",
      "type": "string",
      "enum": [
        "ok",
        "inferred",
        "first_seen",
        "quarantined"
      ],
      "example": "ok"
    },
    "crossed": {
      "description": "Hyperliquid and HIP-3 only: true when this account was the taker.",
      "type": "boolean",
      "example": true
    },
    "dex": {
      "description": "HIP-3 only: dex of the market.",
      "type": "string",
      "example": "xyz"
    },
    "direction": {
      "description": "Hyperliquid and HIP-3 only: direction label as reported by Hyperliquid (for example `Close Short`).",
      "type": "string",
      "example": "Close Short"
    },
    "end_position": {
      "description": "Signed position size after the leg.",
      "type": "string",
      "nullable": true,
      "example": "-0.25"
    },
    "entry_price_after": {
      "description": "Average entry price after the leg. Null when the position is flat after it.",
      "type": "string",
      "nullable": true,
      "example": "64210.5"
    },
    "event_index": {
      "description": "Hyperliquid and HIP-3 only, present with `block_number`: execution order within the block.",
      "type": "integer",
      "example": 12
    },
    "event_type": {
      "description": "Effect on the position: `open`, `increase`, `reduce`, `close`, or `flip`. Lighter also reports `settlement` (the settlement counterparty side of a market settlement) and `unchanged`.",
      "type": "string",
      "example": "reduce"
    },
    "fee": {
      "description": "Fee paid for the leg (negative is a rebate).",
      "type": "string",
      "nullable": true,
      "example": "0.4875"
    },
    "fee_rate": {
      "description": "Lighter only: fee rate as a decimal ratio.",
      "type": "string",
      "nullable": true,
      "example": "0.00002"
    },
    "fee_token": {
      "description": "Asset the fee is paid in: USDC on Hyperliquid and Lighter mainnet, USDG on Lighter on Robinhood Chain.",
      "type": "string",
      "example": "USDC"
    },
    "fee_usdc": {
      "description": "Lighter only: fee in the quote asset, computed from the notional and the fee rate.",
      "type": "string",
      "nullable": true,
      "example": "0.325"
    },
    "finalized": {
      "description": "True when the leg is final and will not be re-derived.",
      "type": "boolean",
      "example": true
    },
    "is_maker": {
      "description": "Lighter only: true when this account was the maker.",
      "type": "boolean",
      "example": false
    },
    "opened_at": {
      "description": "Start of the position lifecycle this leg belongs to. Null when it opened before coverage.",
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "order_id": {
      "description": "Order ID of this account.",
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "example": 844421856609148
    },
    "position_size_after": {
      "description": "Lighter only: alias of `end_position`.",
      "type": "string",
      "example": "-0.25"
    },
    "position_size_before": {
      "description": "Lighter only: alias of `start_position`.",
      "type": "string",
      "example": "-0.5"
    },
    "price": {
      "description": "Execution price.",
      "type": "string",
      "nullable": true,
      "example": "65010.2"
    },
    "realized_pnl": {
      "description": "Lighter only: realized PnL of the leg in the quote asset (0 on open and increase).",
      "type": "string",
      "example": "19.9"
    },
    "seq": {
      "description": "Hyperliquid and HIP-3 only: order of legs that share a timestamp.",
      "type": "integer",
      "example": 0
    },
    "side": {
      "description": "Side of this account in the trade, exactly as on the trades routes: `B` (buy) or `A` (sell).",
      "type": "string",
      "enum": [
        "B",
        "A"
      ],
      "example": "B"
    },
    "size": {
      "description": "Traded size in base units.",
      "type": "string",
      "nullable": true,
      "example": "0.25"
    },
    "start_position": {
      "description": "Signed position size before the leg.",
      "type": "string",
      "nullable": true,
      "example": "-0.5"
    },
    "symbol": {
      "description": "Market symbol (HIP-3: `dex:COIN`).",
      "type": "string",
      "example": "BTC"
    },
    "timestamp": {
      "description": "Execution time (UTC).",
      "type": "string",
      "format": "date-time",
      "example": "2026-09-25T14:03:11.482Z"
    },
    "trade_id": {
      "description": "Trade ID, shared by both legs of a trade.",
      "type": "integer",
      "format": "int64",
      "example": 26121110211
    },
    "usdc_amount": {
      "description": "Lighter only: notional of the leg in the quote asset.",
      "type": "string",
      "example": "16252.55"
    }
  }
}
```

## Referenced By

Use this shared schema with the generated component index and route-specific endpoint pages during implementation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.