This file covers Phoenix perpetuals REST data, exact account decoding, snapshot consistency, and indexer catch-up. It concerns the Solana perpetuals protocol, not the older spot order book or the Phoenix web framework.
TL;DR
- REST reads are indexer views. Writes are Solana transactions.
- State uses the owner authority; the equity view uses the trader PDA.
- Keep u64/i64 strings exact. Empty arrays may be omitted, but malformed arrays are errors.
- A state slot behind an accepted read or confirmed fill is untrusted.
- State → equity view → state agreement prevents some false-flat snapshots; it is a client safeguard.
1. Public REST surfaces
Base URL: https://perp-api.phoenix.trade.
| Endpoint | Contents |
|---|---|
/v1/view/exchange/markets | Symbols, grid, status, leverage tiers, fees, RWA metadata |
/v1/view/exchange | Markets and transaction account keys |
/v1/view/exchange/status | Active/running state, gating, withdrawal availability |
/v1/markets/stats/latest | Per-symbol mark/oracle prices and timestamps |
/v1/view/orderbook/{symbol} | Book view, slot, midpoint |
/v1/trader/state/{authority}?traderPdaIndex=N | All subaccounts, positions, and resting orders |
/v1/view/trader/{traderPda} | Portfolio value, collateral, margin, risk, positions |
The implemented client exposes these reads without onboarding or invitation requests. Newer documented routes do not expand the toolkit automatically.
Public checks on 2026-10-03 showed 92 markets, all active, and exchange status active with gating enabled and withdrawals available. These are timestamped observations, never startup constants.
2. State and view shapes
State includes authority, PDA index, slot, slot index, capabilities, and subaccounts. Each subaccount may contain collateral, positions, and grouped orders. Position sizes are signed i64 lot strings. Price ticks, order sequences, and remaining lots are exact decimal strings.
Validate authority case exactly, requested indices, a valid slot, and the required cross subaccount. A row carrying a delta-stream closed marker is not a valid snapshot row. Missing arrays represent empty collections in observed snapshots; a present malformed array must fail the whole read. A zero-remaining order is not live.
Orders contain side, sequence, price ticks, remaining lots, and reduce-only flag. Bid sequence numbers are at least 2^63; ask sequences are below it. Reject a mismatched sequence/side pair rather than guessing. Conditional-order flags are schema-level information and were not observed in the evaluated live snapshots.
The trader view uses TokenAmount objects with string ui values for portfolio and margin data. Parse ui rather than treating a numeric JSON value as an exact amount. Check the returned authority and trader PDA. Supplying the owner wallet where a trader PDA is expected can return Trader not found; that is a read error, not an empty account.
Position and order conversions require valid market metadata. Keep exact identities while converting lots to display sizes. More than one subaccount is not one merged position.
3. Slots, echoes, and stable reads
The REST indexer can lag a confirmed transaction. Reads observed 2026-09-24 caught up after a short, variable delay. Do not infer a universal deadline from those samples.
Reject snapshots below an already accepted slot or below a confirmed own-fill slot. An uncertain fill can temporarily gate reads until resolution or caller-selected expiry. Feed the state-change gate only when a transaction actually changed trader state; an empty IoC must not lock an idle account indefinitely.
A stable read takes state, then the equity view, then state again. It requires matching position keys and checks whether an intermediate-slot view contradicts the nonzero position set. A view outside the state slot window supplies weaker plausibility evidence. If the view cannot supply a comparable position size, do not invent one. The result's equityAvailable indicates that a view was decoded, not that it is independently fresh; callers must inspect slot and gate evidence.
Own-placement and cancellation echoes are keyed by exact order identity and disappear when indexer evidence catches up or explicit memory TTL expires. Unknown-outcome locks are separate. See orders.md §6.
The meaning of slot on an idle account is unresolved: it may refer to the account's last change rather than the chain head. A blanket “slot must be close to current chain slot” rule would reject an otherwise valid idle account.
4. Read transport and prices
The REST client requires explicit pacing, retry count, timeout, and retry/backoff settings. HTTP 429 honors Retry-After as a client-wide pause. Other 4xx responses are exchange answers; retry eligible 5xx or transport failures for reads only.
All-market midpoint helpers decode mark prices from stats. A symbol midpoint can prefer the orderbook view and fall back to mark data. Neither proves an executable price: spline liquidity can differ from the rendered top level. Reject empty, nonfinite, crossed, or malformed price inputs.
Pitfalls
| What breaks | Why | Correct approach |
|---|---|---|
| Bid ID changes | JSON number rounded u64 | Require exact decimal strings |
| Flat state appears plausible | Omitted arrays or lagging replica | Validate shape and compare stable reads |
| Equity endpoint says not found | Owner supplied instead of trader PDA | Use the correct identity |
| Idle account is held forever | Snapshot slot assumed to equal chain head | Gate on accepted/own-change evidence |
| Quote fails to fill | View is not executable liquidity | Treat fill as transaction evidence |
Open questions / not verified
- Snapshot-slot meaning on idle accounts and worst-case replica lag.
- Conditional/stop row variants and delta-stream markers beyond schema evidence.
- Public REST rate ceilings and some newer API routes.
Sources
API overview; List markets; Accounts; WS/API best practices; Rise public source. Public market/status check: 2026-10-03. Snapshot and order-row shapes: observed 2026-09-23 and 2026-09-24. Stable-read and gate rules are toolkit safeguards.
© markpaper authors. Licensed under CC BY 4.0: when publishing or adapting this material, credit “markpaper — Phoenix knowledge base” and link to the original and the license.