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

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