Perps Positions - Clicker

Perps positions use the same position API structure as spots, with a few additional fields. This guide covers what’s different, and how to handle perps in your integration.

Spot vs Perps: What Changes

A spot position tracks tokens bought and sold onchain. A perps position tracks a leveraged long or short on Hyperliquid. The API returns both through the same position-fetching endpoints. Perps positions are distinguished by three fields on metadata (plus three new properties on metadata.positionStats, discussed later):

Field	Type	Description
`perpPositionType`	`"long" \| "short" \| null`	Position direction. Present only on perps.
`perpLeverage`	`number \| null`	Leverage multiplier (e.g. 2, 5, 10).
`positionAmountWithLeverage`	`number`	Token amount with leverage applied.

If perpPositionType is null or absent, the position is spot.

Perps Fields in Detail

Position Direction and Leverage

{
  "metadata": {
    "perpPositionType": "long",
    "perpLeverage": 5,
    "positionAmount": 0.5,
    "positionAmountWithLeverage": 2.5
  }
}

perpPositionType tells you whether the trader is long or short. perpLeverage is the multiplier. positionAmount is the base amount (the margin denominated in the token), and positionAmountWithLeverage is the notional exposure (positionAmount * perpLeverage). For shorts on Hyperliquid, positionAmount can be negative.

Position Stats

Perps positions add several fields to positionStats:

Field	Type	Description
`holdingsCostBasisUSD`	`number`	The margin (collateral) in USD
`holdingsCostBasisUSDWithLeverage`	`number`	The leveraged cost basis in USD
`boughtUSDWithLeverage`	`number`	Total USD entered with leverage applied
`soldUSDWithLeverage`	`number`	Total USD exited with leverage applied

For spot positions, holdingsCostBasisUSD is the total cost of the tokens currently held. For perps, it represents the margin posted. The WithLeverage variants reflect the full notional values.

{
  "metadata": {
    "positionStats": {
      "holdingsCostBasisUSD": 1000,
      "holdingsCostBasisUSDWithLeverage": 5000,
      "boughtUSD": 1000,
      "boughtUSDWithLeverage": 5000,
      "soldUSD": 0,
      "soldUSDWithLeverage": 0,
      "realizedGainsUSD": 0
    }
  }
}

In this example, the trader posted $1,000 margin with 5x leverage, giving $5,000 notional exposure.

Metadata vs Trade-Level Props

perpPositionType and perpLeverage exist in two places: on metadata (position-level) and on each object in the trades array. They serve different purposes. Metadata-level (metadata.perpPositionType, metadata.perpLeverage) reflects the current state of the position. Use these for:

Position cards, profile pages, and token screens
PnL calculations
Detecting whether a position is perps or spot
Displaying the current direction and leverage

For most integrations, the metadata-level fields are all you need. Trade-level (trade.perpPositionType, trade.perpLeverage) reflects what happened at the time of that specific trade. Use these when rendering individual trade activity. The trade-level leverage matters because it tells you the leverage that trade used, which is what you want when describing the action:

"alice 5x longed $2,000 of ETH"        ← trade.perpLeverage
"alice closed their 5x long ETH"       ← trade.perpLeverage
"alice closed $500 of their 5x long ETH" ← trade.perpLeverage

Computing Position Values

For the full formulas covering unrealized PnL, current value, and percent change for both spot and perp positions, see the Position Calculations guide.

Perps Trade Actions

If you’re building activity feeds or notifications, you can use the trades array to produce more descriptive copy than “entered” or “exited.” The Clicker app has copy for four different types of actions:

Action	How to derive	Example copy
`open`	`intent` is `"enter"` and it’s the first trade	”opened a 5x long on ETH”
`add`	`intent` is `"enter"` and prior trades exist	”5x longed $2,000 more of ETH”
`partial-close`	`intent` is `"exit"` and the position still has balance	”closed $500 of their 5x long ETH”
`full-close`	`intent` is `"exit"` and the position is fully closed	”closed their 5x long ETH”

​Spot vs Perps: What Changes

​Perps Fields in Detail

​Position Direction and Leverage

​Position Stats

​Metadata vs Trade-Level Props

​Computing Position Values

​Perps Trade Actions