3.9 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 | Unavailable; API net-value semantics have not passed verification |
| 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.
Why API Value is not displayed
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. Blindly displaying this API Value would
subtract the settled opening fee again. Adding it back alone does not establish
the full contract: collateral-currency valuation and the lockedAmount profit
cap must also be verified. The response does not expose that cap. The overview
therefore shows an em dash with an explanation, and higher Value totals containing
such a position also remain unavailable. It does not merge unmatched on-chain
observations into the API snapshot or build unsigned closing transactions.
This is a known first-version limitation, not verified closing-value parity with
Jupiter. Counts, amounts and prices above are observations, not fixed expectations.
See the change's verification.md for observation times and current checks.