--- title: "Get HIP-3 wallet positions" method: GET path: "/v1/hyperliquid/hip3/wallets/{address}/positions" tags: ["HIP-3 Builder Perps - Positions"] --- # Get HIP-3 wallet positions `GET /v1/hyperliquid/hip3/wallets/{address}/positions` ## Request - Base URL: `https://api.0xarchive.io` - URL: `https://api.0xarchive.io/v1/hyperliquid/hip3/wallets/{address}/positions` - Auth: API key in header `X-API-Key` Open positions of one wallet: the latest live snapshot, or the state at `timestamp`. Scope to one dex with `dex` to also get that dex's account summary. An empty result reports `account_seen`. The change log starts October 13, 2025; hourly history starts June 7, 2026 18:00 UTC (later for some dexes); live snapshots refresh every 5 minutes. Billed at 1 credit per 1,000 rows returned, minimum 1 credit per request. ## Path parameters - `address` string, required ## Query parameters - `timestamp` union: An instant: Unix milliseconds, or an RFC 3339 string such as `2026-01-01T00:00:00Z` (encode a `+` offset as `%2B`). An unparsable value answers 400 `invalid_time_range`. - integer: Unix milliseconds. - string, date-time: RFC 3339 instant. - `symbol` string - `dex` string - `limit` integer - `cursor` string ## Response `200` Get HIP-3 wallet positions - ApiResponseWalletPositions: Positions of one wallet or account. - `success` boolean, required - `data` WalletPositions, required: Positions of one wallet or account at one instant. - `positions` Position[], required - `snapshot_ts` string, date-time: Hour the row describes. Present on hourly history rows only. - `account_index` string: Lighter only: account index, serialized as a string because it can exceed JavaScript integers. - `account_kind` string: Lighter only: `user`, `insurance`, `settlement`, or `system`. Non-user accounts appear in market routes only with `include_system=true`. - `symbol` string, required: Market symbol (HIP-3: `dex:COIN`). - `coin` string, required: Alias of `symbol`. - `dex` string: HIP-3 only: the dex the position belongs to. - `size` string, required: Signed position size in base units (negative is short). - `side` 'long' | 'short', required: Position side. - `entry_price` string, nullable, required: Average entry price. - `mark_price` string, nullable, required: Mark price used for value and PnL. Null when no mark is available. - `mark_time` string, date-time, nullable, required: Time of the mark price. - `position_value` string, nullable, required: Absolute position value in USD at the mark price. - `unrealized_pnl` string, nullable, required: Unrealized PnL in USD at the mark price. - `return_on_equity` string, nullable, required: Return on equity as a decimal ratio. Hyperliquid snapshot rows only. - `leverage` PositionLeverage, required: Leverage of a position. - `type` string, required: Margin type: `cross`, `isolated`, or `unknown`. On Lighter this is the margin mode of the position. - `value` string, nullable, required: Leverage multiple as a decimal string. Null when unknown (Lighter rows and as-of reconstructions). - `max_leverage` integer, nullable, required: Maximum leverage allowed for the market. Hyperliquid snapshot rows only. - `margin_used` string, nullable, required: Margin allocated to the position in USD. Hyperliquid snapshot rows only. - `liquidation_price` string, nullable, required: Liquidation price as reported for the position. Hyperliquid snapshot rows only. - `liquidation_price_status` string, required: How `liquidation_price` should be read: `exact`, `not_published_cross`, `changed_since_snapshot`, or `unavailable` (always `unavailable` on Lighter and on as-of reconstructions). - `cum_funding` PositionCumulativeFunding, required: Cumulative funding in USD (decimal strings). Null when not reported, including every Lighter row and as-of reconstructions. - `all_time` string, nullable, required: Funding paid or received over the account lifetime for this coin. - `since_open` string, nullable, required: Funding since the current position opened. - `since_change` string, nullable, required: Funding since the last change in position size. - `opened_at` string, date-time, nullable, required: Start of the current position lifecycle. Null when it opened before coverage. - `snapshot_as_of` string, date-time, nullable, required: Time the leverage, margin, and funding fields describe, which can differ from the hour. Hyperliquid snapshot rows only. - `quality` string, required: 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`. - `initial_margin_fraction` string, nullable: Lighter only: initial margin fraction at the last trade, as a decimal ratio. - `allocated_margin` string, nullable: Lighter only: isolated margin allocated to the position. - `margin_mode` string: Lighter only: `cross`, `isolated`, or `unknown`. - `mark_source` string: Lighter only: where the mark came from: `mark`, `last_trade`, `stale_mark`, or `none`. - `finalized` boolean: Lighter only: true when every trade behind the row is final (reconciled). - `account` AccountSummary, required: 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. - `snapshot_ts` string, date-time: Hour the row describes. Present on hourly history rows only. - `account_index` string: Lighter only: account index as a string. - `dex` string: HIP-3 only: dex the account summary belongs to. - `account_value` string, nullable: Hyperliquid and HIP-3 only: account value in USD. - `cross_account_value` string, nullable: Hyperliquid and HIP-3 only: cross-margin account value in USD. - `collateral` string, nullable: Hyperliquid and HIP-3 only: collateral in USD. - `total_margin_used` string, nullable: Hyperliquid and HIP-3 only: total margin used in USD. - `cross_maintenance_margin_used` string, nullable: Hyperliquid and HIP-3 only: cross maintenance margin used in USD. - `withdrawable` string, nullable: Hyperliquid and HIP-3 only: withdrawable amount in USD. Null outside the periods where it was captured. - `total_position_value` string, nullable, required: Sum of absolute position values in USD. - `total_unrealized_pnl` string, nullable, required: Sum of unrealized PnL in USD. - `long_value` string, nullable, required: Value of long positions in USD. - `short_value` string, nullable, required: Value of short positions in USD. - `n_positions` integer, required: Number of open positions. - `account_mode` string: Hyperliquid and HIP-3 only: account abstraction mode, `standard`, `unified`, `portfolio`, `dex_abstraction`, or `unknown`. - `snapshot_as_of` string, date-time, nullable: Hyperliquid and HIP-3 only: time the clearinghouse fields describe. - `quality` string, required: `complete`, `partial` (a total is null because a position has no mark), or `degraded`. - `account_seen` 'flat' | 'never_seen' | 'outside_coverage': 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). - `meta` PositionsMeta, required: Response metadata of the account positions routes. Every instant is RFC 3339 UTC with milliseconds and comes from the data, never the request time. - `count` integer, required: Number of records returned. - `next_cursor` string, nullable: Signed, opaque cursor for the next page, bound to the request; present exactly when `has_more` is `true`. Pass it back with the same parameters. A market cursor pins its snapshot; if that snapshot is replaced or expires the next page answers 409 `snapshot_advanced`. - `request_id` string, uuid, required: Unique request ID for support. - `as_of` string, date-time: Instant the returned state describes: the snapshot tick or hour, or the requested as-of time. - `snapshot_ts` string, date-time: Committed snapshot the response was read from. Market routes echo the resolved `hour` here. - `source` 'snapshot' | 'reconstructed' | 'changes': How the rows were produced: `snapshot` (live or hourly snapshot), `reconstructed` (as-of state between snapshots), or `changes` (change log). - `quality` string: Completeness of the snapshot the response was read from: `complete`, `partial`, or `degraded`. Rows carry their own `quality`. On Lighter and Robinhood Chain, snapshots from the latest day, before the venue's daily trade reconcile, can read `degraded` while their rows read `preliminary`; they read `complete` once the reconcile has run. - `stale` boolean: True on current reads when the latest snapshot is older than 12 minutes; paired with `notice`. - `built_through` string, date-time: Every event before this instant is built into the change log and as-of state. Reads are clamped to it. - `finalized_through` string, date-time: Every event before this instant is final and will not be re-derived (Lighter: the trade finalization watermark). Never later than `built_through`. - `requested_end` string, date-time: The `end` or `timestamp` the caller asked for, echoed when the read was clamped. - `clamped_to` string, date-time: Boundary the read was clamped to (`built_through`). Present only when clamped. - `totals` MarketPositionsSummary: Long and short aggregates of every open position in one market at one snapshot. Averages cover only positions with a known entry (`*_positions_with_entry`). Shares are decimal ratios of the side or total value held by the ten largest positions. - `snapshot_ts` string, date-time, nullable, required: Snapshot the aggregates describe. - `symbol` string, required - `coin` string, required: Alias of `symbol`. - `dex` string: HIP-3 only. - `long_count` integer, required - `short_count` integer, required - `long_size` string, required: Total long size in base units. - `short_size` string, required: Total short size in base units. - `long_value` string, nullable, required: Total long value in USD. Null when any long position has no mark. - `short_value` string, nullable, required: Total short value in USD. Null when any short position has no mark. - `long_avg_entry_price` string, nullable, required: Size-weighted average entry of long positions with a known entry. - `short_avg_entry_price` string, nullable, required: Size-weighted average entry of short positions with a known entry. - `long_positions_with_entry` integer, required - `short_positions_with_entry` integer, required - `long_top10_value_share` string, nullable, required: Share of long value held by the ten largest long positions. - `short_top10_value_share` string, nullable, required: Share of short value held by the ten largest short positions. - `top10_value_share` string, nullable, required: Share of total value held by the ten largest positions. - `quality` string, required: `complete`, `partial`, or `degraded`, from this market's own rows. - `coverage_from` string, date-time: Coverage start, present with `notice` when the request falls before coverage or the address has no recorded activity. - `notice` string: Human-readable advisory: before coverage, no recorded activity, or a stale snapshot. - `has_more` boolean: Cursor-paged routes: whether another page follows. `next_cursor` is present exactly when this is `true`. A final page can be empty when the previous page was exactly full; `has_more` is `false` on it. - `symbol` string: Per-symbol routes: the canonical public symbol the response describes (for example `BTC`, `xyz:TSLA`, `HYPE-USDC`, `#0`). - `venue` 'hyperliquid' | 'hip3' | 'hip4' | 'spot' | 'lighter' | 'rh-lighter': Per-symbol routes: the venue the response describes. ## Other responses - `400`: Invalid request: a parameter, symbol, interval, cursor or time range failed validation. See `error_code`. - `401`: Authentication required: the API key is missing or invalid. - `403`: The request is outside the plan's history window or per-request span, or the key is not allowed to make it. - `404`: Not found. `not_found`: the resource id is unknown. `unsupported_for_venue`: the venue does not offer this datatype (`available_on` names where it is served). `route_not_found`: no route matches the path. - `429`: Rate limit, concurrency limit or monthly credits exceeded. See `error_code`. - `503`: Positions, pagination, or an as-of reconstruction are temporarily unavailable (`error_code` `positions_unavailable`, `pagination_unavailable`, or `reconstruction_unavailable`). Retry shortly. - `default`: Any other error. The body is an `ErrorResponse`; branch on `error_code`. A 503 (`upstream_unavailable`) carries `Retry-After`. --- [API](https://skmtc.dev/0xarchive/apis/0xarchive-api-2.md) · [All operations](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/revisions/27076f55595f?raw)