Documentation
Start typing to search…

Order ID vs Trade ID: Trading Scenarios

Order ID vs Trade ID: Trading Scenarios

This document explains the difference between order_id and trade_id through various trading scenarios to help developers understand how these identifiers work in the Premia V4 trading system.

Key Concepts

  • order_id: Unique identifier for individual limit orders (32-character hex string). Generated when a limit order is posted to the orderbook.
  • trade_id: Unique identifier for executed trades (32-character hex string). Generated when a market order is filled against limit orders.

Relationship: Multiple trades can reference the same order_id when a single limit order is filled across multiple market orders (partial fills). Each trade execution generates a unique trade_id.

Trading Scenarios

Scenario 1: Simple Market Order (Fully Filled)

You place: Market BUY order for 10 contracts

Order book has:

  • SELL limit order A: 10 contracts @ $100

Results:

  • Your trade record:
    • order_id: abc123 (your order)
    • trade_id: abc123 (same as your order_id)
    • direction: buy
    • taker_fee: 0.008
  • Counterparty record:
    • order_id: def456 (their limit order)
    • trade_id: abc123 (your order id)
    • direction: sell
    • taker_fee: 0 (they're maker)

Scenario 2: Market Order with Multiple Fills

You place: Market BUY order for 20 contracts

Order book has:

  • SELL limit order A: 10 contracts @ $100
  • SELL limit order B: 10 contracts @ $101

Results:

  • Your trade record:
    • order_id: abc123
    • trade_id: abc123
    • size: 20
    • average_price: 100.5
    • taker_fee: 0.016
  • Counterparty A record:
    • order_id: def456
    • trade_id: abc123
    • size: 10
    • price: 100
  • Counterparty B record:
    • order_id: ghi789
    • trade_id: abc123
    • size: 10
    • price: 101

Scenario 3: Limit Order That Crosses (Takes Liquidity)

You place: Limit BUY order for 15 @ $105 (crosses the spread)

Order book has:

  • SELL limit order A: 10 @ $100

Results:

  • Immediate fill (you as taker):
    • order_id: abc123
    • trade_id: abc123
    • size: 10
    • taker_fee: 0.008
  • Counterparty record:
    • order_id: def456
    • trade_id: abc123
    • size: 10
    • taker_fee: 0
  • Your remaining order: 5 contracts @ $105 posted to order book

Scenario 4: Your Limit Order Gets Filled Later

Continuing from Scenario 3: Your 5 contracts @ $105 are on the book

Someone else places: Market SELL order for 5 contracts

Results:

  • Their trade record (new taker):
    • order_id: xyz999
    • trade_id: xyz999
    • direction: sell
    • taker_fee: 0.004
  • Your fill record (now maker):
    • order_id: abc123 (your original order)
    • trade_id: xyz999 (their order)
    • direction: buy
    • taker_fee: 0 (you're maker now)
    • maker_fee: -0.002 (rebate)

Scenario 5: Partial Fill of Large Limit Order

Order book has: SELL limit order A: 100 contracts @ $100

Multiple market orders hit it:

Market Buy #1: 30 contracts

  • Limit order record:
    • order_id: aaa111 (unchanged)
    • trade_id: buyer1
    • size: 30

Market Buy #2: 50 contracts

  • Limit order record:
    • order_id: aaa111 (still same)
    • trade_id: buyer2
    • size: 50

Market Buy #3: 20 contracts

  • Limit order record:
    • order_id: aaa111 (still same)
    • trade_id: buyer3
    • size: 20

Scenario 6: Post-Only Order Rejection

You place: Post-only SELL order @ $99

Order book has: BUY order @ $100

Results:

  • Order rejected (would cross)
  • No trades generated
  • No trade_id created

Scenario 7: Fill-or-Kill (FOK) Success

You place: FOK BUY order for 50 contracts

Order book has:

  • SELL order A: 30 @ $100
  • SELL order B: 20 @ $101

Results:

  • All fills share same trade_id:
    • Fill A: trade_id: abc123, size: 30
    • Fill B: trade_id: abc123, size: 20
  • Atomic execution (all or nothing)

Scenario 8: RFQ (Request for Quote)

Special case where limit orders have specific takers:

You request: RFQ for 100 contracts Market maker responds: Limit order with taker = your address

Results:

  • order_id: RFQ-specific ID
  • trade_id: Generated when you accept
  • Only you can fill this order

Key Patterns to Remember

  1. Taker always: Has order_id == trade_id
  2. Maker always: Has order_id != trade_id
  3. One market order: Creates one trade_id for all fills
  4. Limit orders: Keep same order_id across multiple fills
  5. Fee indicator: Positive taker_fee = you're taker; Zero/negative = you're maker

Common Use Cases

Tracking Your Orders

  • Use order_id to track the lifecycle of your limit orders
  • Use trade_id to track executions of your market orders

Reconciliation

  • Match trades by trade_id to see all fills from a single market order
  • Match trades by order_id to see all fills of a single limit order

Fee Calculation

  • Taker fees are charged when you place market orders (order_id == trade_id)
  • Maker rebates are earned when your limit orders are filled (order_id != trade_id)

WebSocket Events

When subscribing to trade events via WebSocket, you'll receive:

  • order_id: The original order that was filled
  • trade_id: The execution that filled it
  • Same patterns apply as described in the scenarios above

For more details on WebSocket subscriptions, see the WebSocket API documentation.

Updated 6 days ago