> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phoenix.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Spline Liquidity

> How spline traders quote and fill liquidity on Phoenix

Spline liquidity is a Phoenix-specific liquidity source for quoting a shaped curve without placing one FIFO order at every price level.

A spline trader publishes a mid price and bid/ask regions. The matching engine materializes those regions into visible price levels when it builds the combined book.

## Spline data model

Each spline has:

* a `mid_price`
* bid regions below mid
* ask regions above mid
* sequence ordering
* current fill state
* risk-limited bid and ask capacity

Each region is defined by:

* `start_offset`
* `end_offset`
* `density`
* optional top-level hidden take size
* lifespan / expiry

Region offsets are tick distances from the spline mid:

* bid offset `x` maps to `mid_price - x`
* ask offset `x` maps to `mid_price + x`
* `density` is the base-lot size available per tick in the region

For example, a spline with mid `100`, bid region `[1, 3)`, and density `5` exposes:

* `5` lots at `99`
* `5` lots at `98`

An ask region `[1, 3)` on the same spline exposes:

* `5` lots at `101`
* `5` lots at `102`

## How spline levels become visible

A spline level is eligible for the book when:

* the spline is active
* the spline has a nonzero mid price
* the region has not expired
* the region still has unfilled size
* the spline trader has remaining risk capacity on that side

The visible level is the first unfilled tick in the active region. If a tick is partially filled, only the remaining size at that tick is displayed. Once a tick is fully consumed, the next tick in the region becomes visible.

Spline liquidity is therefore not a static list of orders. It is derived from the spline's mid price, region definitions, region fill state, expiry, and current risk counters.

## Risk caps

Before matching, Phoenix caps each spline's available bid and ask size using the spline trader's current risk state.

The cap accounts for:

* current margin and position state
* `leverage_decrease_in_bps`
* optional max position size limits
* the current risk action

After each spline fill, the in-memory risk counter is decremented. This prevents one instruction from consuming more spline liquidity than the trader can support across multiple price levels.

## Uncrossing and slide prices

Spline liquidity from different traders can cross when their mids and regions overlap. Phoenix resolves this before rendering or matching spline-only liquidity.

The uncross path:

1. Matches crossed splines against FIFO liquidity first when the spline crosses the explicit book.
2. Computes slide prices for remaining crossed spline-only liquidity.
3. Displays and matches more aggressive spline bids at the slide bid.
4. Displays and matches more aggressive spline asks at the slide ask.

Slide prices make the remaining spline book non-crossing without writing synthetic orders into the FIFO book.

## Pro-rata fills

At a single spline price level, FIFO price-time priority does not apply across spline traders. Phoenix allocates the fill pro-rata by available size:

```text theme={null}
allocation = floor(available_lots * fill_size / total_available)
```

Spline sequence number is still used for deterministic iteration and dust handling. It is not the primary priority rule.

Important execution consequences:

* one spline price level consumes one `match_limit` unit, even if multiple splines participate
* one FIFO maker order consumes one `match_limit` unit
* spline liquidity at the same price fills before FIFO liquidity
* worse spline prices do not skip better FIFO prices

## Hidden take size

`top_level_hidden_take_size` is not displayed as normal resting spline liquidity for incoming takers.

It is used when a spline itself takes FIFO liquidity during uncrossing. In that path, Phoenix can consume visible size at the current top tick, then hidden take size at that same tick, then visible size through deeper ticks.