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, post-fee USD collateral and price PnL before separate fees, with leverage/ROI against positive collateral. It SHALL preserve optional reported valueUsd as an unverified estimate, converting integer micro-USD exactly without fee corrections. Missing/null Value SHALL remain unavailable; present malformed amounts SHALL fail the observation. Other valid metrics SHALL survive missing Value.

Scenario: Unverified API closing value

WHEN API Value subtracts opening fees already settled in collateral or does not establish profit-cap valuation
THEN the reported Value is preserved unchanged as an unverified estimate while independent metrics remain available
AND it is not represented as guaranteed closing proceeds or corrected by adding opening fees back

Scenario: Reported API closing estimate

WHEN Jupiter reports valueUsd as "123234567", "0" or "-1234567"
THEN the overview preserves exactly 123.234567, 0 or -1.234567 USD respectively
AND it does not add opening fees back or impose a profit-cap correction

Scenario: Missing or malformed Value

WHEN valueUsd is missing or null
THEN Value is unavailable while independent metrics remain available
AND a present malformed amount instead fails the complete observation

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

3.0 KiB Raw Blame History