API reference · Liquidations & positions

Positions

Open positions of one perp with leverage and liquidation price.

GET https://api.femtos.xyz/v1/positions

Parameters

Param	In	Example or values	Meaning
`coin`	query	`BTC`	Perp coin
`side`	query	`(empty)`, `long`, `short`	One side
`sort`	query	`notional`, `upnl`, `liqDistance`	Sort
`limit`	query	`50`	Rows

curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/positions?coin=BTC&sort=notional&limit=50"

Key: Authorization: Bearer $FEMTOS_KEY. Get a free key, or with no browser through agent onboarding.

Field	Type	Meaning
`positions[]`	object	Sorted as asked: {address, szi, side, entryPx, notional, upnl, leverage, marginMode, liqPx, liqDistancePct, label, entity}
`markPx`	decimal \| null	Mark used
`asOf`	ms	Time of `height` (Unix ms)
`height`	int	Block the positions are at: the node's latest state (one every 10,000 blocks, ~12 min) rolled forward with every fill, funding payment and ledger update since, a few seconds behind the chain; the state itself while the roll is not running
`baseHeight`	int	Block of that node state (= height when not rolled forward)
`sort`	string	Sort applied (liqDistance or upnl without what they need: notional)
`order`	string	Order applied

Liquidations GET /v1/liquidations HyperCore
Perp liquidations, newest first, one row per account, coin and block.
Liquidations stream WS hc.liquidations HyperCore
Each liquidation fill, the block it happens.
Liquidation stats GET /v1/liquidations/stats HyperCore
Totals, per coin, per time bucket and the largest, over a window.
Position changes WS hc.positions HyperCore
Each perp position change, one per block, account and coin.
Open interest GET /v1/positions/overview HyperCore
Open interest, accounts and unrealized PnL per perp.
Liquidation map GET /v1/positions/liqmap HyperCore
Notional that would be liquidated at each price around the mark.