com_r35157_nenjim-hubd-impl_ref/docs/JupiterPerpsOverview.md

Jupiter read-only Perps overview

JupiterPerpsOverview is an overview-only interface under com.r35157.libs.jupiter.perps; impl.ref.RestJupiterPerpsOverview reads GET https://perps-api.jup.ag/v2/positions?walletAddress=<address> once per wallet. The Hub injects this reader into both Evelyn Perps processes with their existing separate wallet lists. It has a 10-second request timeout, no immediate retries and no portfolio cache. Signing, transactions, alarms, their existing Solana cache and entry-price behavior remain in the existing JupiterPerpsService.

Response contract and definitions

The official CLI response type and API reference describe the position list. The implementation requires an integer count matching the complete dataList, unique valid position accounts, valid asset mints, Long/Short side and positive size. HTTP/schema failures throw; only an explicit count-zero empty list clears the scope. Missing optional valuation fields become unavailable; malformed amounts fail the read.

Display	Source / definition
Exposure	sizeUsd / 10^6; preserves the existing recorded USD-size basis
Collateral	collateralUsd / 10^6, the venue's recorded post-fee USD collateral
Leverage	Exposure / positive Collateral; not equity-based leverage
uPnL	pnlBeforeFeesUsd / 10^6, price PnL before separately reported fees
uPnL percent	100 × uPnL / positive Collateral
Value	valueUsd / 10^6, Jupiter's reported estimate, unchanged and displayed with ≈
Risk reference price	Positive markPriceUsd / 10^6 from the same response
Reported liquidation price	Positive liquidationPriceUsd / 10^6; missing/nonpositive values are unavailable

All amounts are parsed as decimal integers and converted exactly. The API's pnlBeforeFeesPct is already percentage points (95.48 means 95.48%), but the overview derives the requested percentage against precise collateral itself. The API's rounded leverage is likewise not used for the derived ratio.

The overview preserves one original response observation time on all positions. It does not treat a position's updatedTime as proof of current price freshness. Risk uses the venue's reported prices, with no new liquidation-price formula or Ticker dependency. Missing/sentinel prices retain the position and its independent metrics. Present malformed amounts still fail the read. Isolated signed distance, the owner's neutral-distance policy and expiration are described in Perps risk presentation.

Reported Value and its uncertainty

The overview preserves optional valueUsd exactly as supplied, including zero and signed values. EMC displays it with ≈ and two USD decimals (for example, ≈$123.23). Its tooltip explains: “Estimated position value reported by Jupiter. Actual proceeds on closing may differ.” Missing/null values remain unavailable; present malformed amounts fail the complete observation. Successful observations replace earlier values, including replacing an estimate with unavailable Value. Failed reads retain the original observation, success time and failure indication.

Available Jupiter, wallet and Perpetual Contracts Value totals inherit the estimate qualification independently of expansion state. Mixed Phoenix/Jupiter totals identify both estimate sources; Phoenix's existing account-aware closing estimates and single counting of shared Cross capital are preserved. A missing required Value still makes the affected total —, without a numeric approximation marker. A successfully read empty scope can total zero.

This reports a venue estimate, not verified closing proceeds. It does not add opening fees back, correct the API number, introduce closing quotes or combine additional on-chain observations with the response.

On 24 October 2026 the funded configured wallet's six API sizes and collateral amounts matched read-only on-chain position data. For its SOL Short, the response contained these integer micro-USD values:

collateralUsd = 18559       pnlBeforeFeesUsd = 17721
openFeesUsd   = 361         closeFeesUsd     = 361
borrowFeesUsd = 7           valueUsd         = 35551

35551 = 18559 + 17721 - 361 - 361 - 7. The on-chain collateral was also 18559; the official position account documentation defines collateral as after fees. This observation raises uncertainty about subtracting a settled opening fee again; it does not prove that every API estimate is wrong. Adding that fee back alone would not establish the full contract: collateral-currency valuation and the lockedAmount profit cap remain unverified. The response does not expose that cap. The possible difference from actual closing proceeds is not known to be limited to small fees. Issue #100 therefore withheld Value; issue #104 replaces that presentation with the explicitly qualified venue estimate.

There is no verified closing-value parity with Jupiter. Counts, amounts and prices above are historical observations, not fixed expectations. See the change's verification.md for observation times and current checks.