70 lines
3.9 KiB
Markdown
70 lines
3.9 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 | 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.
|