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$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.