> ## 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. # WalletPositions Schema > Positions of one wallet or account at one instant. Includes parameters, response shapes, examples, and implementation notes from the 0xArchive contract. Source OpenAPI: 0xArchive API 1.7.0; 218 paths; 210 component schemas. Positions of one wallet or account at one instant. ## Required Fields | Field | Type | Description | | - | - | - | | `account` | allOf | Account summary on the first page of a snapshot read. | | `positions` | array\ | Defined by the generated JSON Schema block. | ## JSON Schema ```json theme={"theme":"github-dark"} { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "WalletPositions", "description": "Positions of one wallet or account at one instant.", "type": "object", "required": [ "account", "positions" ], "properties": { "account": { "description": "Account summary on the first page of a snapshot read. Hyperliquid core: the wallet's summary when the snapshot holds one. HIP-3: when the request is scoped to one dex. Lighter: position aggregates when no `symbol` filter is set. Null otherwise, on later pages, and on as-of reconstructions.", "nullable": true, "allOf": [ { "description": "Account summary. Hyperliquid and HIP-3 carry the perp clearinghouse fields of one account (HIP-3: one per dex). Lighter carries position aggregates only (`account_index`, totals, and counts). A total is null when any position in it has no mark, never a partial sum.", "type": "object", "required": [ "long_value", "n_positions", "quality", "short_value", "total_position_value", "total_unrealized_pnl" ], "properties": { "account_index": { "description": "Lighter only: account index as a string.", "type": "string", "example": "513030" }, "account_mode": { "description": "Hyperliquid and HIP-3 only: account abstraction mode, `standard`, `unified`, `portfolio`, `dex_abstraction`, or `unknown`.", "type": "string", "example": "standard" }, "account_value": { "description": "Hyperliquid and HIP-3 only: account value in USD.", "type": "string", "nullable": true, "example": "125000.5" }, "collateral": { "description": "Hyperliquid and HIP-3 only: collateral in USD.", "type": "string", "nullable": true, "example": "100000" }, "cross_account_value": { "description": "Hyperliquid and HIP-3 only: cross-margin account value in USD.", "type": "string", "nullable": true, "example": "118000.25" }, "cross_maintenance_margin_used": { "description": "Hyperliquid and HIP-3 only: cross maintenance margin used in USD.", "type": "string", "nullable": true, "example": "6100.2" }, "dex": { "description": "HIP-3 only: dex the account summary belongs to.", "type": "string", "example": "xyz" }, "long_value": { "description": "Value of long positions in USD.", "type": "string", "nullable": true, "example": "300000" }, "n_positions": { "description": "Number of open positions.", "type": "integer", "example": 4 }, "quality": { "description": "`complete`, `partial` (a total is null because a position has no mark), or `degraded`.", "type": "string", "example": "complete" }, "short_value": { "description": "Value of short positions in USD.", "type": "string", "nullable": true, "example": "112000.5" }, "snapshot_as_of": { "description": "Hyperliquid and HIP-3 only: time the clearinghouse fields describe.", "type": "string", "format": "date-time", "nullable": true }, "snapshot_ts": { "description": "Hour the row describes. Present on hourly history rows only.", "type": "string", "format": "date-time" }, "total_margin_used": { "description": "Hyperliquid and HIP-3 only: total margin used in USD.", "type": "string", "nullable": true, "example": "20500.75" }, "total_position_value": { "description": "Sum of absolute position values in USD.", "type": "string", "nullable": true, "example": "412000.5" }, "total_unrealized_pnl": { "description": "Sum of unrealized PnL in USD.", "type": "string", "nullable": true, "example": "2510.25" }, "withdrawable": { "description": "Hyperliquid and HIP-3 only: withdrawable amount in USD. Null outside the periods where it was captured.", "type": "string", "nullable": true } } } ] }, "account_seen": { "description": "Present only when `positions` is empty: `flat` (activity is recorded but no position is open), `never_seen` (no recorded activity in the covered history, with `meta.notice` and `meta.coverage_from`), or `outside_coverage` (the requested instant is before coverage).", "type": "string", "enum": [ "flat", "never_seen", "outside_coverage" ] }, "positions": { "type": "array", "items": { "description": "One open position. Numbers are decimal strings (sizes to the market size precision, prices to the market price precision, USD values to 6 decimals); a flat position serializes as `\"0\"`. Hyperliquid rows carry `dex` on HIP-3; Lighter rows carry `account_index`, `account_kind`, and the Lighter fields at the end. Fields a source does not report are null, never estimated.", "type": "object", "required": [ "coin", "cum_funding", "entry_price", "leverage", "liquidation_price", "liquidation_price_status", "margin_used", "mark_price", "mark_time", "max_leverage", "opened_at", "position_value", "quality", "return_on_equity", "side", "size", "snapshot_as_of", "symbol", "unrealized_pnl" ], "properties": { "account_index": { "description": "Lighter only: account index, serialized as a string because it can exceed JavaScript integers.", "type": "string", "example": "281474976710654" }, "account_kind": { "description": "Lighter only: `user`, `insurance`, `settlement`, or `system`. Non-user accounts appear in market routes only with `include_system=true`.", "type": "string", "example": "user" }, "allocated_margin": { "description": "Lighter only: isolated margin allocated to the position.", "type": "string", "nullable": true, "example": "1200.5" }, "coin": { "description": "Alias of `symbol`.", "type": "string", "example": "BTC" }, "cum_funding": { "description": "Cumulative funding in USD (decimal strings). Null when not reported, including every Lighter row and as-of reconstructions.", "type": "object", "required": [ "all_time", "since_change", "since_open" ], "properties": { "all_time": { "description": "Funding paid or received over the account lifetime for this coin.", "type": "string", "nullable": true, "example": "-12.345678" }, "since_change": { "description": "Funding since the last change in position size.", "type": "string", "nullable": true, "example": "-0.5" }, "since_open": { "description": "Funding since the current position opened.", "type": "string", "nullable": true, "example": "-1.25" } } }, "dex": { "description": "HIP-3 only: the dex the position belongs to.", "type": "string", "example": "xyz" }, "entry_price": { "description": "Average entry price.", "type": "string", "nullable": true, "example": "64210.5" }, "finalized": { "description": "Lighter only: true when every trade behind the row is final (reconciled).", "type": "boolean", "example": true }, "initial_margin_fraction": { "description": "Lighter only: initial margin fraction at the last trade, as a decimal ratio.", "type": "string", "nullable": true, "example": "0.05" }, "leverage": { "description": "Leverage of a position.", "type": "object", "required": [ "type", "value" ], "properties": { "type": { "description": "Margin type: `cross`, `isolated`, or `unknown`. On Lighter this is the margin mode of the position.", "type": "string", "example": "cross" }, "value": { "description": "Leverage multiple as a decimal string. Null when unknown (Lighter rows and as-of reconstructions).", "type": "string", "nullable": true, "example": "20" } } }, "liquidation_price": { "description": "Liquidation price as reported for the position. Hyperliquid snapshot rows only.", "type": "string", "nullable": true, "example": "81250" }, "liquidation_price_status": { "description": "How `liquidation_price` should be read: `exact`, `not_published_cross`, `changed_since_snapshot`, or `unavailable` (always `unavailable` on Lighter and on as-of reconstructions).", "type": "string", "example": "exact" }, "margin_mode": { "description": "Lighter only: `cross`, `isolated`, or `unknown`.", "type": "string", "example": "cross" }, "margin_used": { "description": "Margin allocated to the position in USD. Hyperliquid snapshot rows only.", "type": "string", "nullable": true, "example": "1625.5" }, "mark_price": { "description": "Mark price used for value and PnL. Null when no mark is available.", "type": "string", "nullable": true, "example": "65020.1" }, "mark_source": { "description": "Lighter only: where the mark came from: `mark`, `last_trade`, `stale_mark`, or `none`.", "type": "string", "example": "mark" }, "mark_time": { "description": "Time of the mark price.", "type": "string", "format": "date-time", "nullable": true }, "max_leverage": { "description": "Maximum leverage allowed for the market. Hyperliquid snapshot rows only.", "type": "integer", "nullable": true, "example": 40 }, "opened_at": { "description": "Start of the current position lifecycle. Null when it opened before coverage.", "type": "string", "format": "date-time", "nullable": true }, "position_value": { "description": "Absolute position value in USD at the mark price.", "type": "string", "nullable": true, "example": "32510.05" }, "quality": { "description": "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`.", "type": "string", "example": "complete" }, "return_on_equity": { "description": "Return on equity as a decimal ratio. Hyperliquid snapshot rows only.", "type": "string", "nullable": true, "example": "-0.1245" }, "side": { "description": "Position side.", "type": "string", "enum": [ "long", "short" ], "example": "short" }, "size": { "description": "Signed position size in base units (negative is short).", "type": "string", "example": "-0.5" }, "snapshot_as_of": { "description": "Time the leverage, margin, and funding fields describe, which can differ from the hour. Hyperliquid snapshot rows only.", "type": "string", "format": "date-time", "nullable": true }, "snapshot_ts": { "description": "Hour the row describes. Present on hourly history rows only.", "type": "string", "format": "date-time" }, "symbol": { "description": "Market symbol (HIP-3: `dex:COIN`).", "type": "string", "example": "BTC" }, "unrealized_pnl": { "description": "Unrealized PnL in USD at the mark price.", "type": "string", "nullable": true, "example": "-404.8" } } } } } } ``` ## 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.