5.3 KiB
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.