Get HIP-3 wallet positions

curl --request GET \
  --url https://api.0xarchive.io/v1/hyperliquid/hip3/wallets/{address}/positions \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.0xarchive.io/v1/hyperliquid/hip3/wallets/{address}/positions"

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/hyperliquid/hip3/wallets/{address}/positions', 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/hyperliquid/hip3/wallets/{address}/positions"

	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": {
    "positions": [
      {
        "symbol": "BTC",
        "coin": "BTC",
        "size": "-0.5",
        "side": "short",
        "entry_price": "64210.5",
        "mark_price": "65020.1",
        "mark_time": "2023-11-07T05:31:56Z",
        "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"
        },
        "opened_at": "2023-11-07T05:31:56Z",
        "snapshot_as_of": "2023-11-07T05:31:56Z",
        "quality": "complete",
        "snapshot_ts": "2023-11-07T05:31:56Z",
        "account_index": "281474976710654",
        "account_kind": "user",
        "dex": "xyz",
        "initial_margin_fraction": "0.05",
        "allocated_margin": "1200.5",
        "margin_mode": "cross",
        "mark_source": "mark",
        "finalized": true
      }
    ],
    "account": {
      "total_position_value": "412000.5",
      "total_unrealized_pnl": "2510.25",
      "long_value": "300000",
      "short_value": "112000.5",
      "n_positions": 4,
      "quality": "complete",
      "snapshot_ts": "2023-11-07T05:31:56Z",
      "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",
      "withdrawable": "<string>",
      "account_mode": "standard",
      "snapshot_as_of": "2023-11-07T05:31:56Z"
    },
    "account_seen": "flat"
  },
  "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

hyperliquid

hip3

wallets

{address}

positions

Get HIP-3 wallet positions

curl --request GET \
  --url https://api.0xarchive.io/v1/hyperliquid/hip3/wallets/{address}/positions \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.0xarchive.io/v1/hyperliquid/hip3/wallets/{address}/positions"

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/hyperliquid/hip3/wallets/{address}/positions', 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/hyperliquid/hip3/wallets/{address}/positions"

	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": {
    "positions": [
      {
        "symbol": "BTC",
        "coin": "BTC",
        "size": "-0.5",
        "side": "short",
        "entry_price": "64210.5",
        "mark_price": "65020.1",
        "mark_time": "2023-11-07T05:31:56Z",
        "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"
        },
        "opened_at": "2023-11-07T05:31:56Z",
        "snapshot_as_of": "2023-11-07T05:31:56Z",
        "quality": "complete",
        "snapshot_ts": "2023-11-07T05:31:56Z",
        "account_index": "281474976710654",
        "account_kind": "user",
        "dex": "xyz",
        "initial_margin_fraction": "0.05",
        "allocated_margin": "1200.5",
        "margin_mode": "cross",
        "mark_source": "mark",
        "finalized": true
      }
    ],
    "account": {
      "total_position_value": "412000.5",
      "total_unrealized_pnl": "2510.25",
      "long_value": "300000",
      "short_value": "112000.5",
      "n_positions": 4,
      "quality": "complete",
      "snapshot_ts": "2023-11-07T05:31:56Z",
      "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",
      "withdrawable": "<string>",
      "account_mode": "standard",
      "snapshot_as_of": "2023-11-07T05:31:56Z"
    },
    "account_seen": "flat"
  },
  "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

address

string

required

Wallet address: 0x followed by 40 hex characters (case-insensitive).

Pattern: ^0x[0-9a-fA-F]{40}$

Example:

"0x31ca8395cf837de08b24da3f660e77761dfb974b"

Query Parameters

timestamp

integer<int64>

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.

symbol

string

Only this market, in dex:COIN form (e.g. xyz:TSLA). Must agree with dex when both are set.

dex

string

Restrict to one HIP-3 dex (for example xyz).

Example:

"xyz"

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 HIP-3 wallet positions

Positions of one wallet or account.

success

boolean

required

Example:

true

data

object

required

Positions of one wallet or account at one instant.

Hide child attributes

data.positions

object[]

required

Hide child attributes

data.positions.symbol

string

required

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

Example:

"BTC"

data.positions.coin

string

required

Alias of symbol.

Example:

"BTC"

data.positions.size

string

required

Signed position size in base units (negative is short).

Example:

"-0.5"

data.positions.side

enum<string>

required

Position side.

Available options:

long,

short

Example:

"short"

data.positions.entry_price

string | null

required

Average entry price.

Example:

"64210.5"

data.positions.mark_price

string | null

required

Mark price used for value and PnL. Null when no mark is available.

Example:

"65020.1"

data.positions.mark_time

string<date-time> | null

required

Time of the mark price.

data.positions.position_value

string | null

required

Absolute position value in USD at the mark price.

Example:

"32510.05"

data.positions.unrealized_pnl

string | null

required

Unrealized PnL in USD at the mark price.

Example:

"-404.8"

data.positions.return_on_equity

string | null

required

Return on equity as a decimal ratio. Hyperliquid snapshot rows only.

Example:

"-0.1245"

data.positions.leverage

object

required

Leverage of a position.

Hide child attributes

data.positions.leverage.type

string

required

Margin type: cross, isolated, or unknown. On Lighter this is the margin mode of the position.

Example:

"cross"

data.positions.leverage.value

string | null

required

Leverage multiple as a decimal string. Null when unknown (Lighter rows and as-of reconstructions).

Example:

"20"

data.positions.max_leverage

integer | null

required

Maximum leverage allowed for the market. Hyperliquid snapshot rows only.

Example:

40

data.positions.margin_used

string | null

required

Margin allocated to the position in USD. Hyperliquid snapshot rows only.

Example:

"1625.5"

data.positions.liquidation_price

string | null

required

Liquidation price as reported for the position. Hyperliquid snapshot rows only.

Example:

"81250"

data.positions.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).

Example:

"exact"

data.positions.cum_funding

object

required

Cumulative funding in USD (decimal strings). Null when not reported, including every Lighter row and as-of reconstructions.

Hide child attributes

data.positions.cum_funding.all_time

string | null

required

Funding paid or received over the account lifetime for this coin.

Example:

"-12.345678"

data.positions.cum_funding.since_open

string | null

required

Funding since the current position opened.

Example:

"-1.25"

data.positions.cum_funding.since_change

string | null

required

Funding since the last change in position size.

Example:

"-0.5"

data.positions.opened_at

string<date-time> | null

required

Start of the current position lifecycle. Null when it opened before coverage.

data.positions.snapshot_as_of

string<date-time> | null

required

Time the leverage, margin, and funding fields describe, which can differ from the hour. Hyperliquid snapshot rows only.

data.positions.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.

Example:

"complete"

data.positions.snapshot_ts

string<date-time>

Hour the row describes. Present on hourly history rows only.

data.positions.account_index

string

Lighter only: account index, serialized as a string because it can exceed JavaScript integers.

Example:

"281474976710654"

data.positions.account_kind

string

Lighter only: user, insurance, settlement, or system. Non-user accounts appear in market routes only with include_system=true.

Example:

"user"

data.positions.dex

string

HIP-3 only: the dex the position belongs to.

Example:

"xyz"

data.positions.initial_margin_fraction

string | null

Lighter only: initial margin fraction at the last trade, as a decimal ratio.

Example:

"0.05"

data.positions.allocated_margin

string | null

Lighter only: isolated margin allocated to the position.

Example:

"1200.5"

data.positions.margin_mode

string

Lighter only: cross, isolated, or unknown.

Example:

"cross"

data.positions.mark_source

string

Lighter only: where the mark came from: mark, last_trade, stale_mark, or none.

Example:

"mark"

data.positions.finalized

boolean

Lighter only: true when every trade behind the row is final (reconciled).

Example:

true

data.account

object | null

required

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.

Hide child attributes

data.account.total_position_value

string | null

required

Sum of absolute position values in USD.

Example:

"412000.5"

data.account.total_unrealized_pnl

string | null

required

Sum of unrealized PnL in USD.

Example:

"2510.25"

data.account.long_value

string | null

required

Value of long positions in USD.

Example:

"300000"

data.account.short_value

string | null

required

Value of short positions in USD.

Example:

"112000.5"

data.account.n_positions

integer

required

Number of open positions.

Example:

4

data.account.quality

string

required

complete, partial (a total is null because a position has no mark), or degraded.

Example:

"complete"

data.account.snapshot_ts

string<date-time>

Hour the row describes. Present on hourly history rows only.

data.account.account_index

string

Lighter only: account index as a string.

Example:

"513030"

data.account.dex

string

HIP-3 only: dex the account summary belongs to.

Example:

"xyz"

data.account.account_value

string | null

Hyperliquid and HIP-3 only: account value in USD.

Example:

"125000.5"

data.account.cross_account_value

string | null

Hyperliquid and HIP-3 only: cross-margin account value in USD.

Example:

"118000.25"

data.account.collateral

string | null

Hyperliquid and HIP-3 only: collateral in USD.

Example:

"100000"

data.account.total_margin_used

string | null

Hyperliquid and HIP-3 only: total margin used in USD.

Example:

"20500.75"

data.account.cross_maintenance_margin_used

string | null

Hyperliquid and HIP-3 only: cross maintenance margin used in USD.

Example:

"6100.2"

data.account.withdrawable

string | null

Hyperliquid and HIP-3 only: withdrawable amount in USD. Null outside the periods where it was captured.

data.account.account_mode

string

Hyperliquid and HIP-3 only: account abstraction mode, standard, unified, portfolio, dex_abstraction, or unknown.

Example:

"standard"

data.account.snapshot_as_of

string<date-time> | null

Hyperliquid and HIP-3 only: time the clearinghouse fields describe.

data.account_seen

enum<string>

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).

Available options:

flat,

never_seen,

outside_coverage

API reference

SDKs & tooling

AI & agents

Get HIP-3 wallet positions

Authorizations

Path Parameters

Query Parameters

Response