This file explains collateral and margin quantities exposed by the API, pure rejection classification, and the verified distinction between mark-price reserve and order-price estimates.
TL;DR
- Portfolio equity, raw collateral, effective collateral, and available margin are different fields.
- Resting orders reserve margin using mark valuation, rather than their limit price alone.
- There is no account leverage setter in the evaluated implementation.
- A margin-rejected landed transaction can cost a fee while filling nothing.
- A simple first-tier formula is an observed special case, not a complete tiered margin calculator.
1. Account quantities
Portfolio value comes from the trader view. USDC collateral is already included; adding it again double-counts it. Raw on-chain header collateral is a signed quote-lot balance, not portfolio equity.
The pure helper computes:
freeMarginUsd = max(0, effectiveCollateral - initialMargin)
Missing or nonfinite fields return unavailable. Use fields from one trusted view. A stale read, missing field, or contradictory state/view pair cannot establish newly available margin. API trust is described in api-and-reads.md §3.
2. Position and resting-order reserve
Public metadata supplies leverage tiers and limit-order risk factors. On the evaluated first tier, resting-order margin matched size × markPrice / maxLeverage when the limit-order risk factor was one. The trader view's order margin agreed with mark-price valuation for every resting order checked on 2026-09-27.
An order-price-only estimate understates reserve for a bid below mark and can overstate it for an ask above mark. This is a valuation distinction, not a recommendation about where to place orders.
For a synthetic example with size 2 units, mark 100, limit 80, and a first-tier maximum leverage 10, mark-valued reserve is 20 rather than the order-price estimate 16. These numbers are invented and do not describe a market or account.
Tier transitions, risk factors, netting, existing positions, and collateral type can change the full calculation. The toolkit does not export a complete initial-margin calculator from a simplified estimate. Read the venue view and current official formula for a proposed account operation.
3. Rejection and risk states
An observed exposure-increasing rejection contained InsufficientFunds and Unhealthy trader cannot increase exposure on 2026-09-25. The pure classifier recognizes these margin-rejection messages and returns the evidence classification to the caller.
A transaction that reaches the chain and fails may charge a fee. RPC preflight refusal before forwarding is different. Do not keep submitting an unchanged exposure-increasing request based on the same stale margin estimate.
Public metadata on 2026-10-03 contained risk factors and bps counterparts, including a cancelOrder value of 70 for the checked public market. The meaning of that field for each cancellation mechanism has not been independently verified.
4. Fees and isolated collateral
Public market metadata on 2026-10-03 showed maker 0.00005 and taker 0.00035 on the examined list: 0.5 and 3.5 basis points. These are dated market parameters, distinct from Solana network fees and any future account overrides.
Isolated child-account collateral movement is documented upstream but not implemented by this toolkit's helpers. A decoded isolated position does not imply support for registering, funding, or closing its child account.
Pitfalls
| What breaks | Why | Correct approach |
|---|---|---|
| Equity doubled | Collateral added to portfolio value | Use the returned equity once |
| Reserve too small for a resting bid | Limit price used for mark valuation | Current view and mark-aware reasoning |
| Apparent free margin triggers another refusal | Read is stale or formula incomplete | Trusted evidence and classification |
| Risk factor called proven cancellation rule | Field value overinterpreted | Keep semantics explicitly unverified |
Open questions / not verified
- Full tiered/order-netting margin behavior beyond the observed first-tier case.
- Exchange-side cancellation thresholds and risk-capacity eviction behavior.
- Delegate collateral operations for isolated children and future account fee overrides.
Sources
Margin math; Leverage tiers; Margin; Public Phoenix market metadata. Mark-valued resting reserve observed 2026-09-27; metadata/rates checked 2026-10-03. Synthetic arithmetic above is illustrative only.
© 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.