# 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.