Address Perp Positions

Common Scenarios

Usecase
Required Parameters
Optional Filters
Expected Output

Check current perp positions for a single address

address ="0xa312114b5795dff9b8db50474dd57701aa78ad1e"

filters ={"position_value_usd": {"min": 1000}}

List of open perpetual positions with entry price, mark price, leverage, PnL, and margin info for the address

Get all perp positions with negative PnL for an address

address ="0xa312114b5795dff9b8db50474dd57701aa78ad1e"

filters ={"unrealized_pnl_usd": {"max": 0}}

List of positions with negative unrealized PnL

Get Perpetual Positions Data

post

Get perpetual positions data for a user by calling the Hyperliquid API directly. This endpoint provides real-time position information including entry price, mark price, PnL, leverage, and other position details.

What it helps to answer:

  1. What are the current perpetual positions for a specific user address?

  2. What is the unrealized PnL and performance of each position?

  3. What are the leverage levels and margin requirements for each position?

  4. What are the liquidation prices and risk levels for each position?

Authorizations
Body

Request model for Perp Positions endpoint.

addressstring · min: 42 · max: 42Required

User's Hyperliquid address in 42-character hexadecimal format

Example: 0xa312114b5795dff9b8db50474dd57701aa78ad1e
filtersany ofOptional

Additional filters to apply to the query.

Example: {"position_value_usd":{"min":1000},"unrealized_pnl_usd":{"max":0}}
order_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

  • [{"field": "position_value_usd", "direction": "DESC"}] - Sort by position value descending
  • [{"field": "unrealized_pnl_usd", "direction": "ASC"}] - Sort by unrealized PnL ascending

If not provided, positions are sorted by position value descending.

Example: [{"direction":"DESC","field":"position_value_usd"}]
Responses
200

Perpetual positions data for the user

application/json
post
/api/v1/profiler/perp-positions
POST /api/v1/profiler/perp-positions HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 196

{
  "address": "0xa312114b5795dff9b8db50474dd57701aa78ad1e",
  "filters": {
    "position_value_usd": {
      "min": 1000
    },
    "unrealized_pnl_usd": {
      "max": 0
    }
  },
  "order_by": [
    {
      "direction": "DESC",
      "field": "position_value_usd"
    }
  ]
}
{
  "data": {
    "asset_positions": [
      {
        "position": {
          "cumulative_funding_all_time_usd": "-623.219722",
          "cumulative_funding_since_change_usd": "-618.925976",
          "cumulative_funding_since_open_usd": "-623.219722",
          "entry_price_usd": "0.43499",
          "leverage_type": "cross",
          "leverage_value": 3,
          "liquidation_price_usd": "66.817537196",
          "margin_used_usd": "1743.87343",
          "max_leverage_value": 3,
          "position_value_usd": "5231.62029",
          "return_on_equity": "2.2836393396",
          "size": "-50367.0",
          "token_symbol": "STBL",
          "unrealized_pnl_usd": "16677.54047"
        },
        "position_type": "oneWay"
      },
      {
        "position": {
          "cumulative_funding_all_time_usd": "200.361581",
          "cumulative_funding_since_change_usd": "201.157877",
          "cumulative_funding_since_open_usd": "200.361581",
          "entry_price_usd": "0.311285",
          "leverage_type": "cross",
          "leverage_value": 5,
          "liquidation_price_usd": "39.6872752647",
          "margin_used_usd": "2020.946984",
          "max_leverage_value": 5,
          "position_value_usd": "10104.73492",
          "return_on_equity": "3.1976362269",
          "size": "-90052.0",
          "token_symbol": "MOODENG",
          "unrealized_pnl_usd": "17927.1615"
        },
        "position_type": "oneWay"
      }
    ],
    "cross_maintenance_margin_used_usd": "722948.2832910001",
    "cross_margin_summary_account_value_usd": "4643143.4382309997",
    "cross_margin_summary_total_margin_used_usd": "1456365.231985",
    "cross_margin_summary_total_net_liquidation_position_on_usd": "13339928.690684",
    "cross_margin_summary_total_raw_usd": "13987445.0243870001",
    "margin_summary_account_value_usd": "4643143.4382309997",
    "margin_summary_total_margin_used_usd": "1456365.231985",
    "margin_summary_total_net_liquidation_position_usd": "13339928.690684",
    "margin_summary_total_raw_usd": "13987445.0243870001",
    "timestamp": 1761283435707,
    "withdrawable_usd": "2933647.2403759998"
  }
}
PreviousHyperliquid APIsNextAddress Perp Trades

Last updated

Was this helpful?