Phoenix: on-chain Solana perps CLOB — FIFO, splines, Rise SDK, Flight builders

Phoenix (phoenix.trade) is Ellipsis Labs’ on-chain perpetual futures exchange on Solana — a live terminal with order book, positions, rewards, and leaderboard, backed by a crank-free matching design that started as a spot CLOB and now centers on perps.

Docs: docs.phoenix.trade (llms.txt) · API · SDK · CLI sections. X: @PhoenixTrade. Related: Imperial (routes to Phoenix among other venues) · Flash Trade · Jupiter.

Note: the app geoblocks some regions per ToS — check availability before demoing live.

What traders get

Perps on Phoenix mean leveraged long/short exposure without expiry: collateral posts, PnL tracks mark vs entry, funding anchors the contract to the underlying over time, and liquidations enforce solvency. The UI surfaces markets (e.g. SOL-PERP), mark/index, 24h volume and open interest, funding countdown, order book, and portfolio history tabs — plus rewards / leaderboard campaigns (e.g. Flight Club style promotions).

Docs split the mental model into:

• Collateral & accounts — trader accounts, deposits, cross-chain deposit paths
• Matching engine — FIFO book + spline liquidity, order types, TP/SL, fees
• Margin & risk — mark, entry/PnL, funding, leverage tiers, health, liquidations/ADL
• RWA-style markets — index, impact pricing, mark bounds, commodity calendars where listed

Crankless roots (still the DNA)

Phoenix’s original Solana claim was a crankless on-chain order book: match and settle inside the taker’s transaction — no Serum/OpenBook-style keeper crank, no multi-step event-queue drain before balances move. That atomic fill model carries into the perps engine: when you cross the book, the program walks liquidity and updates state in one confirmed tx.

Taker tx T:
  validate order → build combined book (FIFO + splines)
  → match by price priority → update positions / collateral
  → rest remainder or cancel (IOC/market)
Fill final when T confirms — no separate crank.

Matching: FIFO + spline liquidity

Phoenix builds one matching view from two sources:

• FIFO order book — classic limit book; price then time priority within a level.
• Spline liquidity — authorized spline traders publish a mid and bid/ask regions; the engine materializes virtual levels into the combined book, with risk caps and per-slot fill state.

Why splines matter: refreshing a full multi-level quote ladder as discrete cancels/places can cost on the order of ~300k CU. A spline oracle/reference update is documented around ~600 CU — so makers can chase external prices with far less compute and less stale-quote toxicity. Spline updates can carry sequence numbers so out-of-order validator reordering can reject stale quotes.

Priority: best price wins across both surfaces. At the same price, spline fills before FIFO — but splines cannot jump past a better FIFO price; matching respects the FIFO boundary.

Risk stack (short tour)

• Mark price — not last-trade alone; blends adjusted oracle, Phoenix book, and external perp prices for fair risk.
• Funding — transfers between longs/shorts to keep the perp anchored without expiry.
• Margin / leverage tiers — position size vs collateral under published tier math.
• Liquidations — cancel risk-increasing orders, liquidate via book, escalate to backstop, ADL last against opposite profitable positions if needed.

Treat the risk-warning pages as mandatory reading before high leverage — perps remain loss-of-collateral products.

Fees

• Taker: 3.5 bps (0.035%) of matched notional
• Maker: 0.5 bps (0.005%)
• Crossing limits can be taker on the filled portion and maker on the rest
• Referral discounts may reduce user fees; Flight builder fees stack on top of exchange fees when flow is routed through a builder

Flight builder codes

Flight (flight.phoenix.trade) is Phoenix’s builder-code layer: register a builder authority, set a fee in bps, route orders via the SDK so instructions wrap with your code, and accrue fees as collateral on the builder’s trader account (withdraw from the portal).

Today Flight fees apply on liquidity-removing fills (markets + taking portion of limits). Maker-side builder fees are roadmap. Docs recommend a clean empty wallet for builder authority so revenue stays isolated from trading collateral.

API surface

REST groups: Auth (wallet / service / Privy / session refresh), Exchange (markets, orderbook, candles, funding, mark, snapshots, register trader), Invite / referral activation, Trader (state, history, /v1/ix/* transaction builders for isolated market/limit, conditionals, stop-loss, etc.).

# public reads (confirm paths in live docs)
curl -s https://perp-api.phoenix.trade/v1/view/exchange/markets | head
curl -s https://perp-api.phoenix.trade/v1/view/orderbook/SOL | head
curl -s https://perp-api.phoenix.trade/v1/market/SOL/mark-price

# WS subscribe shape
# {"type":"subscribe","subscription":{"channel":"orderbook","symbol":"SOL"}}

Many market reads are public; trading and some trader routes need bearer sessions from the auth flows. Errors return {"error":"..."}. Prefer schema-driven clients — numeric fields are often string-encoded for precision.

Rise SDK (TypeScript + Rust)

Rise is the official integrator SDK (Ellipsis-Labs/rise-public):

# TypeScript
npm add @ellipsis-labs/rise

# Rust
cargo add phoenix-rise

TS: HTTP clients, unified Phoenix client, metadata cache, instruction / order-packet builders, WS adapters, trader-state stores, margin helpers. Rust: phoenix-rise with typed HTTP/WS, PhoenixTxBuilder, metadata, margin math, low-level ixs. Configure builder authority here when integrating Flight.

Where Phoenix sits in the stack

• Venue: full exchange with its own risk engine and book — not “just an aggregator UI.”
• Route target: terminals like Imperial compare Phoenix against Flash / Jupiter / GMTrade on all-in cost for a given size and leverage.
• Builder platform: Flight + Rise let wallets, bots, and agent frontends own distribution without forking the matching engine.

Practical start for builders

1. Read perpetual futures + matching engine docs end to end.
2. Hit public REST for markets/orderbook/mark; open a WS orderbook subscription.
3. Install Rise; register a trader (ix builders + onboarder flows as documented).
4. Paper a small isolated market order path on a supported market; verify margin health endpoints before size.
5. If you ship a front-end, register Flight, set bps, and test taker-fee accrual on a clean builder wallet.

Resources

• Getting started · Perpetual futures · Matching engine · Fees
• API · Rise SDK · Flight / builder codes
• Phoenix on DevRels

Bottom line

Phoenix is the Solana perps CLOB to study when you care about how liquidity is matched on-chain: FIFO book + cheap-to-update spline quotes, a full margin/funding/liquidation stack, public REST/WS, Rise in TS and Rust, and Flight builder economics. Use the app as a trader; use the API/SDK as an integrator; expect routers like Imperial to treat you as one venue among several on all-in cost.