100: Add Perps collateral, leverage, value, uPnL and gross-exposure totals in EMC

2026-10-24 17:56:20 +02:00
parent 7e36b7ef95
commit 28640f3203
35 changed files with 9110 additions and 180 deletions
@@ -0,0 +1,59 @@
+# 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](https://github.com/jup-ag/cli/blob/main/src/clients/PerpsClient.ts)
+and [API reference](https://perps-api.jup.ag/v1/docs) 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 |
+
+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.
+
+## 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:
+
+```text
+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](https://developers.jup.ag/docs/perps/position-account)
+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.