# 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