jupiter-perps-overview Specification

Purpose

Provide precise read-only Jupiter position metrics for capital and risk inspection without altering transaction or alarm behavior.

Requirements

Requirement: Coherent read-only position overview

The overview SHALL read the official positions response for one wallet, validate completeness and unique stable identities, and return immutable results. USD integer amounts SHALL be converted from micro-USD without binary floating point. Requests SHALL be interruptible and have bounded timeouts; failed or malformed reads SHALL NOT become empty portfolios.

Scenario: Incomplete response

WHEN count differs from the returned position count, or identities are duplicated
THEN the read fails and no partial portfolio is published

Scenario: Valid empty response

WHEN the response contains count zero and an empty position list
THEN the successful result clears that wallet's Jupiter scope

Requirement: Verified metrics and unavailable valuations

The overview SHALL preserve size basis, use post-fee USD collateral and price PnL before separate fees, and calculate leverage and ROI against positive collateral. Unverified closing valuations SHALL be unavailable with an explanation; placeholder zeros and double subtraction of settled fees SHALL NOT be used.

Scenario: Unverified API closing value

WHEN API value subtracts opening fees already settled in collateral or does not establish profit-cap valuation
THEN closing Value is unavailable, while independently verified metrics remain available

Scenario: Nonpositive collateral

WHEN a position's collateral is zero or negative
THEN its leverage and PnL percentage are unavailable

Requirement: Report venue risk prices with observation time

The overview SHALL expose the venue reference and liquidation prices in exact USD units with the original response observation time. Missing or nonpositive risk prices SHALL be unavailable, never zero safety or infinite distance. Stable position identity and the separate transaction/alarm read path SHALL remain unchanged.

Scenario: Missing or sentinel price

WHEN a valid position has no actionable liquidation price
THEN its other metrics remain present and its liquidation distance is unavailable

2.3 KiB Raw Blame History