Get Hyperliquid wallet position history

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

import requests

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

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

	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": [
    {
      "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
    }
  ],
  "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

wallets

{address}

positions

history

Get Hyperliquid wallet position history

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

import requests

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

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

	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": [
    {
      "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
    }
  ],
  "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

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

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 Hyperliquid wallet position history

Hourly position rows.

success

boolean

required

Example:

true

data

object[]

required

Hide child attributes

data.symbol

string

required

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

Example:

"BTC"

data.coin

string

required

Alias of symbol.

Example:

"BTC"

data.size

string

required

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

Example:

"-0.5"

data.side

enum<string>

required

Position side.

Available options:

long,

short

Example:

"short"

data.entry_price

string | null

required

Average entry price.

Example:

"64210.5"

data.mark_price

string | null

required

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

Example:

"65020.1"

data.mark_time

string<date-time> | null

required

Time of the mark price.

data.position_value

string | null

required

Absolute position value in USD at the mark price.

Example:

"32510.05"

data.unrealized_pnl

string | null

required

Unrealized PnL in USD at the mark price.

Example:

"-404.8"

data.return_on_equity

string | null

required

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

Example:

"-0.1245"

data.leverage

object

required

Leverage of a position.

Hide child attributes

data.leverage.type

string

required

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

Example:

"cross"

data.leverage.value

string | null

required

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

Example:

"20"

data.max_leverage

integer | null

required

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

Example:

40

data.margin_used

string | null

required

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

Example:

"1625.5"

data.liquidation_price

string | null

required

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

Example:

"81250"

data.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.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.cum_funding.all_time

string | null

required

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

Example:

"-12.345678"

data.cum_funding.since_open

string | null

required

Funding since the current position opened.

Example:

"-1.25"

data.cum_funding.since_change

string | null

required

Funding since the last change in position size.

Example:

"-0.5"

data.opened_at

string<date-time> | null

required

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

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

string<date-time>

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

data.account_index

string

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

Example:

"281474976710654"

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

string

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

Example:

"xyz"

data.initial_margin_fraction

string | null

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

Example:

"0.05"

data.allocated_margin

string | null

Lighter only: isolated margin allocated to the position.

Example:

"1200.5"

data.margin_mode

string

Lighter only: cross, isolated, or unknown.

Example:

"cross"

data.mark_source

string

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

Example:

"mark"

data.finalized

boolean

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

Example:

true

API reference

SDKs & tooling

AI & agents

Get Hyperliquid wallet position history

Authorizations

Path Parameters

Query Parameters

Response