HIP-3 Builder Perps - Positions

Get HIP-3 wallet position history

Hourly position rows of one wallet in [start, end), one row per open position per committed hour, each with snapshot_ts. 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.

get/v1/hyperliquid/hip3/wallets/{address}/positions/history

Request

  • Base URL: https://api.0xarchive.io
  • URL: https://api.0xarchive.io/v1/hyperliquid/hip3/wallets/{address}/positions/history
  • Auth: API key in header X-API-Key

Path parameters

addressstring required
Example:0x31ca8395cf837de08b24da3f660e77761dfb974b

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

Query parameters

startinteger

Inclusive start in Unix milliseconds. Defaults to 24 hours before end.

endinteger

Exclusive end in Unix milliseconds. Defaults to now.

symbolstring

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

dexstring
Example:xyz

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

limitinteger

Maximum rows per page (default 500, max 5000).

cursorstring

Cursor from the previous response meta.next_cursor. Keep every other parameter unchanged.

Response

Get HIP-3 wallet position history

successboolean required

Example response

{
  "success": true,
  "data": [
    {
      "account_index": "281474976710654",
      "account_kind": "user",
      "symbol": "BTC",
      "coin": "BTC",
      "dex": "xyz",
      "size": "-0.5",
      "side": "short",
      "entry_price": "64210.5",
      "mark_price": "65020.1",
      "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"
      },
      "quality": "complete",
      "initial_margin_fraction": "0.05",
      "allocated_margin": "1200.5",
      "margin_mode": "cross",
      "mark_source": "mark",
      "finalized": true
    }
  ],
  "meta": {
    "totals": {
      "symbol": "BTC",
      "coin": "BTC",
      "dex": "xyz",
      "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"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.