48 lines
3.0 KiB
Markdown
48 lines
3.0 KiB
Markdown
# 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
|