90 lines
5.3 KiB
Markdown
90 lines
5.3 KiB
Markdown
# 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 | `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](Evelyn.md#risiko-i-perps).
|
||
|
||
## 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:
|
||
|
||
```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. 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](https://git.r35157.com/r35157/com_r35157_nenjim-hubd-impl_ref/issues/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.
|