Skip to main content
Understanding how Vita CLOB matches orders is crucial for effective trading strategies.

​
Matching Principles

Vita CLOB uses a price-time priority matching algorithm, the industry standard for fair and transparent order execution.
1st → Last

Price-Time Priority

Fair order matching algorithm
Best prices execute first, then earliest orders at the same price. This ensures fair and transparent order execution.

Price Priority

Best prices always execute first

Time Priority

Earlier orders at same price have priority

​
How Matching Works

​
Price-Time Priority Algorithm

1

Price Sorting

Orders are sorted by price:
  • Buy orders: Highest price first (descending)
  • Sell orders: Lowest price first (ascending)
2

Time Ordering

Within the same price level:
  • Orders maintain FIFO (First In, First Out)
  • Earlier orders execute before later ones
3

Matching Process

When prices overlap:
  • Best buy meets best sell
  • Orders match until no overlap remains
Order Book View

Order matching visualization showing price-time priority

The order book above shows real-time bid and ask orders. When the best bid price meets or exceeds the best ask price, orders are matched and executed immediately based on price-time priority.
CLOB Trading Interface

CLOB trading interface showing order placement and execution

​
Order Execution Scenarios

​
Market Order Execution

A market buy order for 100 NEAR would:
  1. Match with 75 NEAR at 5.05 USDC
  2. Match with 25 NEAR at 5.10 USDC
  3. Average execution price: ~5.06 USDC
Large market orders may experience significant price impact

​
Limit Order Execution

Crossing the Spread

When a limit order “crosses the spread” (buy above best ask or sell below best bid):
  • Executes immediately like a market order
  • But only up to the limit price
  • Remaining quantity joins the order book

​
Technical Implementation

​
Order Book Structure

// Orders stored in price-sorted tree structure
pub struct OrderTreeMap(pub TreeMap<u64, Vec<Order>>);

// Each price level contains orders in chronological order
Vec<Order> = [
  Order { timestamp: 1, amount: 100 },
  Order { timestamp: 2, amount: 50 },  // Executes after first order
  Order { timestamp: 3, amount: 75 }
]

​
Matching Constraints

Match Limit

Maximum 50 matches per order execution
  • Prevents excessive gas usage
  • Ensures fair processing

Self-Trade Prevention

Users cannot trade with their own orders
  • Maintains market integrity
  • Prevents wash trading

​
Partial Fills

Orders may be partially filled when:
Not enough counter-orders at your price:
  • Filled portion is executed
  • Remainder stays in order book
  • Order remains active until fully filled or cancelled
Order matches with 50 counter-orders:
  • Execution pauses after 50 matches
  • Remaining quantity stays active
  • May fill in subsequent transactions
Market moves away from limit price:
  • Partial fill at original price
  • Rest waits for market to return
  • No slippage on filled portion

​
Order Priority Examples

​
Scenario 1: Same Price, Different Times

Buy Orders at 5.00 USDC:
1. 100 NEAR - Placed at 10:30:00 (executes first)
2. 150 NEAR - Placed at 10:30:30
3. 75 NEAR  - Placed at 10:31:00

New sell order for 120 NEAR at 5.00 USDC:
- First 100 NEAR matches with Order 1
- Remaining 20 NEAR matches with Order 2

​
Scenario 2: Price Improvement

Current order book:
- Best bid: 4.95 USDC
- Best ask: 5.05 USDC

New limit buy at 5.10 USDC:
- Immediately matches with 5.05 ask
- Buyer gets better price (5.05 instead of 5.10)
- This is called "price improvement"

​
Best Practices for Order Placement

For Quick Execution

  • Use market orders
  • Place limit orders that cross the spread
  • Accept some price impact

For Better Prices

  • Use limit orders
  • Place orders away from market
  • Be patient for execution

For Large Orders

  • Split into smaller chunks
  • Use iceberg orders (if available)
  • Monitor market depth

For Volatility

  • Widen your price range
  • Use shorter time horizons
  • Adjust orders frequently

​
Advanced Concepts

​
Order Book Imbalance

When one side of the order book is significantly larger:
  • Indicates market sentiment
  • May predict price movement
  • Opportunity for market makers

​
Hidden Liquidity

Some liquidity may not be visible:
  • Orders beyond display depth
  • Upcoming market orders
  • Smart order routing

​
Performance Metrics

Matching Engine Specifications

  • Latency: Near Protocol block time (~1 second)
  • Throughput: Up to 50 matches per transaction
  • Fairness: Strict price-time priority
  • Transparency: All matches recorded on-chain

​
Troubleshooting

Common reasons:
  • Price hasn’t reached your limit
  • Orders ahead of yours in queue
  • Insufficient liquidity
  • Market moved away
Possible causes:
  • Limited liquidity at your price
  • Match limit reached (50)
  • Counter-party orders filled by others
Price improvement occurs when:
  • Your limit crosses the spread
  • Market moves in your favor
  • Always receive limit price or better

​
Next Steps

Place Orders

Apply your knowledge to trading

Manage Orders

Track your order execution