25-08-2026: Perp Leaderboard Adds Five Fields And Four Sort Options
Affected endpoints: perp-leaderboard
This release is additive. No existing field changes name, type, or value, and no request that works today stops working.
Five new response fields
realized_pnl_usd
number
Realized PnL over the timeframe, in USD.
unrealized_pnl_usd
number
Unrealized PnL on positions still open, valued at the current mark.
volume_usd
number
Traded notional in USD. Both the opening and the closing fill count.
total_trades
integer
Number of fills over the timeframe.
top_positions
array
The five largest open positions, largest first.
total_pnl is unchanged and still equals realized_pnl_usd + unrealized_pnl_usd.
Each entry in top_positions carries coin, side (long or short), size_base, position_value_usd, entry_price, and unrealized_pnl_usd. size_base is absolute — side carries the direction, so a short has a positive size.
Four new sort options
order_by now accepts realized_pnl_usd, unrealized_pnl_usd, volume_usd, and total_trades, alongside the existing total_pnl, roi, and account_value.
What top_positions covers
top_positions lists only positions in coins the trader traded during the requested timeframe. A position opened before the window and held through it, in a coin the trader did not trade during the window, is not listed.
This matches the behaviour of the timestamp-certified tgm/historical-perp-leaderboard endpoint, so the two agree. It also matches the scope of unrealized_pnl_usd and of the open-exposure term in the roi denominator, which are gated the same way.
An empty top_positions therefore means "no open position in a coin traded during the window", not "holds nothing".
roi for a trader with no traded notional
A trader with zero traded notional in the window now returns roi: null instead of a number. Previously the denominator fell back to one dollar, which returned a PnL amount in dollars in a field documented as a ratio. null is the same answer tgm/historical-perp-leaderboard already gives.
No current values change: no trader in the leaderboard reaches this branch today, because a trader only appears by having a fill and a fill carries positive notional.
Why these fields were empty before
The underlying view computed realized PnL, unrealized PnL, and traded notional and then discarded them, so the endpoint could not return them. It never built the open-position list at all. All five are now selected, and the trade count is a new aggregate over the same source.
Last updated
Was this helpful?