> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paradex.trade/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paradex.trade/_mcp/server.

# VWAP Price Protection for Market Orders

## What is VWAP?

**VWAP (Volume Weighted Average Price)** is a price protection mechanism for market orders that ensures your average execution price stays within acceptable limits, even if individual fills occur at different price levels.

## How It Works

Market orders use **two types of price protection**:

### 1. Terminal Price (Hard Limit)

* **What it is**: Maximum price allowed for any single fill
* **How it's calculated**: Based on mark price and market price bands
* **Protection**: No individual fill can exceed this price

### 2. VWAP Price (Average Limit)

* **What it is**: Maximum average price across all fills
* **How it's calculated**: Based on best bid/offer (BBO) price and your max slippage setting
* **Protection**: Allows partial fills at higher prices as long as the overall average stays within limit

## Key Benefits

✅ **Better Execution**: Can fill orders even when some price levels exceed your slippage tolerance, as long as the average price is acceptable

✅ **Protection**: Prevents unexpected high-cost fills while maintaining order completion

✅ **Flexibility**: Works automatically with your existing max slippage settings

## How VWAP Price is Calculated

### For Buy Orders

* Uses the **best ask price** from the order book
* **Formula**: `Ask Price * (1 + Your Max Slippage)`
* **Example**: If ask is `$20000` and slippage is `0.1%` then `VWAP` is `$20020`

### For Sell Orders

* Uses the **best bid price** from the order book
* **Formula**: `Bid Price * (1 + Your Max Slippage)`
* **Example**: If bid is $20,000 and slippage is 0.1%, VWAP = $20,020.00

### Max Slippage Priority

1. Your account-level max slippage setting (if configured)
2. Market-level default max slippage
3. System default: as returned by the `/v1/markets` endpoint `max_slippage` field

**Note**: If BBO prices are unavailable, the system falls back to mark price for VWAP calculation.

## Example Scenarios

### Scenario 1: Standard Execution

**Order**: Buy 50 units, Terminal: `$20060`, VWAP: `$20000`

**Order Book**:

* 10 units @ \$19,900 ✅ Fully filled
* 20 units @ \$20,050 ✅ Fully filled
* 10 units @ \$20,100 ❌ Rejected (exceeds terminal)

**Result**: 30 units filled at average price of \$19,975 (within VWAP limit)

### Scenario 2: Partial Fill with VWAP Protection

**Order**: Buy 50 units, Terminal: `$20150`, VWAP: `$20000`

**Order Book**:

* 10 units @ \$19,900 ✅ Fully filled
* 10 units @ \$20,050 ✅ Fully filled
* 10 units @ \$20,100 ⚠️ Partially filled (5 units to maintain VWAP)

**Result**: 25 units filled at exactly \$20,000 average (VWAP limit maintained)

## API Changes

### Field Migration

**Deprecated**: `max_slippage_price` field\
**New**: `vwap_price` field

The VWAP feature replaces the previous `max_slippage_price` field with `vwap_price` for market orders. This change provides more sophisticated price protection by allowing partial fills while maintaining average price limits.

**Migration Notes**:

* `max_slippage_price` is no longer used for market orders
* Use `vwap_price` instead when placing market orders via API
* If `vwap_price` is omitted, it will be automatically calculated (same behavior as before)

## Automatic Behavior

* **UI Orders**: VWAP price is automatically calculated and sent with your order
* **API Orders**: Server calculates VWAP if not provided
* **Flag Setting**: The `TARGET_STRATEGY_VWAP` flag is automatically set for market orders

## Important Notes

⚠️ **Terminal Price Always Enforced**: Even with VWAP protection, no single fill can exceed the terminal price limit

⚠️ **BBO Dependency**: VWAP calculation relies on best bid/offer prices. If unavailable, mark price is used as fallback

⚠️ **Partial Fills**: To maintain VWAP limits, orders may be partially filled at certain price levels

## When VWAP Helps Most

* **Thin Order Books**: When liquidity is spread across multiple price levels
* **Volatile Markets**: When prices move quickly but you want average price protection
* **Large Orders**: When your order size spans multiple price levels in the book

## Summary

VWAP price protection gives you **two layers of safety**:

1. **Terminal Price**: Hard stop on individual fills
2. **VWAP Price**: Soft limit on average execution price

Together, they ensure your market orders execute efficiently while staying within your price tolerance limits.