com_r35157_nenjim-hubd-impl_ref/docs/PhoenixPerps.md

Phoenix Perps read-only integration

PhoenixPerpsService and PhoenixPerpsPosition live in com.r35157.libs.phoenix.perps; the REST implementation is in impl.ref. They contain no Evelyn/UI types or signing/trading operations. NenjimHub creates one adapter without a portfolio cache as phoenix.perps.default and injects it into both Evelyn Perps processes. Each process owns its own wallet list, refresh worker and snapshot. See Evelyn for consumer behavior and the canonical system overview for configuration and deployment status.

REST reads and account model

The implementation uses these official endpoints at https://perp-api.phoenix.trade:

1. GET /v1/trader/state/{authority}?traderPdaIndex=0 returns the wallet authority's version-1 snapshot and subaccounts. The account model currently uses trader PDA index 0 for user accounts. Subaccount 0 is cross-margin; other returned subaccounts are isolated. Read every returned subaccount and include only nonzero basePositionLots. An omitted positions field is documented as optional and means empty; null or a wrong type is rejected.
2. GET /v1/view/exchange/markets supplies each symbol's baseLotsDecimals.
3. GET /v1/market/{symbol}/mark-price supplies markPrice.price in USD. The API permits an absent mark price; a held position without a valid positive price fails the lookup rather than appearing as zero.

An empty trader state needs only the first request. Otherwise metadata is fetched once and each active symbol's price once per wallet lookup, including when that symbol is held in several subaccounts. Request starts are spaced at least one second apart across both environments to avoid bursts of per-market reads. Each HTTP request has a 10-second timeout and uses the Hub's existing HTTP client (no redirects by default). On HTTP 429 the adapter respects Retry-After (seconds or HTTP date; 60 seconds if missing/invalid). Further calls fail fast during that shared cooldown, letting Jupiter and other wallet attempts continue; the normal refresh cycle retries later. There are no automatic retries, new API keys or authentication/signing flows. Public reads worked during verification, despite generated API security annotations referring to bearer auth. HTTP failures, including 401/403/404/429, are errors rather than empty portfolios. The shared pacing follows Phoenix's rate-limit guidance; it does not guarantee a fixed quota.

Units, precision and identity

The official SDK's baseLotsToBaseUnits uses lots / 10 ** baseLotsDecimals; the exponent may be negative. The adapter uses:

quantity = BigDecimal(basePositionLots).scaleByPowerOfTen(-baseLotsDecimals)
sizeUsd  = abs(quantity) * markPrice.price

All lot counts use BigInteger; conversion and multiplication use BigDecimal without a rounding context. Jackson parses JSON price numbers directly as decimal, without a double intermediate. For example, 2,144 SOL lots at baseLotsDecimals=2 are 21.44 SOL; at a mark price of 104.45 USD, notional is 2,239.408 USD. Entry price, collateral, virtual quote lots and margin are not substitutes for current notional. Rounding to cents occurs only in the existing EMC display formatter.

Within each wallet's Phoenix venue, identity is traderPdaIndex:subaccountIndex:symbol. Sequence numbers do not affect identity. Rows sort by PDA index, subaccount index and symbol; labels use SYMBOL-PERP, with no extra subaccount tree level. Positive quantity means Long and negative means Short. Thus two SOL subaccounts remain two rows even though their labels match.

Authority/PDA identity, snapshot version, arrays, symbols, duplicate subaccounts or positions, integer lots, metadata and prices are validated. A malformed lookup fails as a whole; it never publishes a partially decoded portfolio. The shared Jackson mapper is copied so strict parsing does not change other integrations.

Refresh behavior and limitations

Each Evelyn process performs an initial background refresh, then waits 60 seconds following each completed cycle. Jupiter and Phoenix are attempted independently for each configured wallet. Successful results replace only that wallet/venue; failures log wallet and venue and retain its last successful result. A valid empty result clears only that venue's positions, preserving its group. Snapshot reads never fetch external data; EMC's three-second polling remains unchanged.

Positions and prices are separate REST reads and can belong to different slots. This is a periodic current-notional estimate, not an atomic exchange valuation. A cycle's duration includes all sequential reads and request pacing before the 60-second pause (32 active markets need at least about 33 seconds for their reads). Failed reads can leave old data visible indefinitely; there is no stale/error indicator yet. Trader PDA indices other than 0, streaming and position management are out of scope.