Order

Overview

The Opinion CLOB implements two order execution types (Market, Limit) and two position directions (Buy, Sell). These primitives enable participation in binary prediction markets through standardized order mechanics.

Order Sides

BUY (Long Position)

Definition: Acquisition of outcome tokens representing a prediction that the specified event will occur.

Example - Binary Market: "Will BTC reach $100k in 2025?"

from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide

# Buy YES tokens (betting it will happen)
side = OrderSide.BUY

Payoff Structure:

Position

Purchase Cost

Resolution

Settlement

Net P&L

Long 100 YES @ $0.60

$60

YES

$100

+$40 (66.7% ROI)

Long 100 YES @ $0.60

$60

-$60 (100% loss)

Risk Parameters:

Maximum Loss: Premium paid (position cost)
Maximum Gain: $1.00 per share minus premium
Breakeven: Event resolution matches position direction

SELL (Short Position or Position Exit)

Definition: Transfer of outcome tokens, either closing an existing long position or establishing a synthetic short position.

Two Use Cases:

Use Case 1: Close Position (Take Profit/Loss)

# You previously bought 100 YES @ $0.50
# Now YES price is $0.75
# Sell to lock in profit

from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide

side = OrderSide.SELL  # Sell your YES tokens

P&L Calculation:

Entry: 100 YES @ $0.50 = $50 cost basis
Exit: 100 YES @ $0.75 = $75 proceeds
Realized P&L: +$25 (50% return)

Use Case 2: Synthetic Short (Advanced)

Strategy: Split collateral into outcome token pairs, sell overpriced outcome, retain opposite side.

# Thesis: YES tokens overpriced at $0.80 (implied 80% probability)
# Strategy: Create position exposed to NO outcome

# Step 1: Convert 100 USDT → 100 YES + 100 NO (via splitPosition)
client.split(market_id=123, amount=100_000000)  # 100 USDT

# Step 2: Sell YES tokens
from opinion_clob_sdk.chain.py_order_utils.model.order import PlaceOrderDataInput
from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide
from opinion_clob_sdk.chain.py_order_utils.model.order_type import LIMIT_ORDER

order = PlaceOrderDataInput(
    marketId=123,
    tokenId='token_yes',
    side=OrderSide.SELL,
    orderType=LIMIT_ORDER,
    price='0.80',
    makerAmountInBaseToken=100  # Sell 100 YES
)
client.place_order(order)

# Position Analysis:
# - Received: $80 USDT (from YES sale)
# - Holdings: 100 NO tokens
# - Net cost: $100 - $80 = $20
#
# Payoff scenarios:
# - If NO resolves: 100 NO → $100 USDT, P&L = $100 - $20 = +$80 (400% ROI)
# - If YES resolves: 100 NO → $0, P&L = $0 - $20 = -$20 (100% loss)

Order Types

Market Orders

Definition: Orders executing immediately at the best available counterparty price, prioritizing fill certainty over price control.

Execution Characteristics:

Fill guarantee (subject to liquidity availability)
Immediate execution (latency: 200-500ms)
Price discovery via orderbook matching
Slippage exposure in thin markets

Use Cases:

Urgent position entry/exit requirements
Markets with deep liquidity (tight spread)
Price movement urgency exceeds execution cost sensitivity
Closing positions under time constraints

Syntax:

from opinion_clob_sdk.chain.py_order_utils.model.order import PlaceOrderDataInput
from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide
from opinion_clob_sdk.chain.py_order_utils.model.order_type import MARKET_ORDER

# Market order: buy with specified USDT allocation
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.BUY,
    orderType=MARKET_ORDER,
    price='0',  # Ignored for market orders (accepts market price)
    makerAmountInQuoteToken=50  # Allocate 50 USDT for purchase
)

result = client.place_order(order)

Order Matching Mechanism:

Order transmitted to CLOB matching engine
Matching engine iterates best available limit orders
Fills sequentially until USDT allocation exhausted or orderbook cleared
Outcome tokens credited to multi_sig_addr
Execution report returned (average fill price, total quantity)

Slippage Example:

Orderbook:
  Sell: 10 YES @ $0.60
  Sell: 20 YES @ $0.61
  Sell: 50 YES @ $0.62

You place: Market BUY for $50 USDT

Execution:
  - Buy 10 YES @ $0.60 = $6.00
  - Buy 20 YES @ $0.61 = $12.20
  - Buy 51.6 YES @ $0.62 = $31.80

Total: 81.6 YES for $50.00
Average price: $0.613 per YES

Limit Orders

Definition: Orders that only execute at your specified price or better.

Characteristics:

✅ Price control (you set maximum/minimum)
✅ No slippage (always your price or better)
❌ May not fill (if price never reached)
❌ Delayed execution (passive waiting)

When to Use:

You want a specific price
No urgency to execute
Market making strategies
Large orders (avoid slippage)

Syntax:

from opinion_clob_sdk.chain.py_order_utils.model.order import PlaceOrderDataInput
from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide
from opinion_clob_sdk.chain.py_order_utils.model.order_type import LIMIT_ORDER

# Limit buy - only buy if price drops to $0.55 or lower
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.BUY,
    orderType=LIMIT_ORDER,
    price='0.55',
    makerAmountInQuoteToken=100  # Willing to spend $100 USDT
)

result = client.place_order(order)

How Limit Orders Execute:

SDK sends order to CLOB
CLOB adds order to orderbook
Order waits for counterparty
Fills when matching order arrives (or immediate if crosses spread)
You receive tokens (partial fills possible)

Order Matching Example:

Orderbook before your order:
  Buy:  20 YES @ $0.58
  Buy:  30 YES @ $0.57
  Sell: 40 YES @ $0.60
  Sell: 50 YES @ $0.61

You place: Limit BUY 100 YES @ $0.59

Orderbook after:
  Buy:  100 YES @ $0.59  ← Your order (waiting)
  Buy:  20 YES @ $0.58
  Buy:  30 YES @ $0.57
  Sell: 40 YES @ $0.60
  Sell: 50 YES @ $0.61

Later, someone places: Limit SELL 60 YES @ $0.59

Result: You buy 60 YES @ $0.59, your order now shows 40 YES remaining

Price Mechanics

Price Range

Valid Prices: 0.01 to 0.99

Interpretation:

0.01 = 1% probability = 1¢ per $1 share
0.50 = 50% probability = 50¢ per $1 share
0.99 = 99% probability = 99¢ per $1 share

Invalid Prices:

price='0.00'   # ❌ Too low
price='1.00'   # ❌ Too high
price='1.05'   # ❌ Greater than 1.00

Price Precision

Prices are strings with up to 4 decimal places:

price='0.5'      # Valid: 50%
price='0.511'   # Valid: 51.10%
price='0.55555'  # Invalid: too many decimals

Bid-Ask Spread

The difference between best buy and sell prices.

Orderbook:
  Best Buy:  $0.58  ← Highest bid
  Best Sell: $0.62  ← Lowest ask

Spread = $0.62 - $0.58 = $0.04 (4¢)

Spread Implications:

Spread

Market Condition

Strategy

$0.01

Tight (liquid)

Market orders OK

$0.05

Moderate

Limit orders recommended

$0.10+

Wide (illiquid)

Limit orders essential

Amount Specifications

Quote Token Amount (USDT)

Specify how much USDT to spend (BUY) or receive (SELL).

from opinion_clob_sdk.chain.py_order_utils.model.order import PlaceOrderDataInput

# Buy YES tokens by spending $50 USDT
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.BUY,
    orderType=LIMIT_ORDER,
    price='0.60',
    makerAmountInQuoteToken=50  # $50 USDT
)

# Calculation:
# Tokens received = $50 / $0.60 = 83.33 YES tokens

When to Use:

You have a fixed budget (e.g., "spend $100")
Dollar-cost averaging
Portfolio allocation (e.g., "allocate 10% of portfolio")

Base Token Amount (Outcome Tokens)

Specify exact number of outcome tokens to buy/sell.

# Sell exactly 100 YES tokens
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.SELL,
    orderType=LIMIT_ORDER,
    price='0.75',
    makerAmountInBaseToken=100  # 100 YES tokens
)

# Calculation:
# USDT received = 100 × $0.75 = $75 USDT

When to Use:

Closing a specific position (e.g., "sell all my 100 YES tokens")
Rebalancing to exact token counts
Arbitrage strategies

Conversion Between Amounts

# Given: price and one amount type, calculate the other

price = 0.60
quote_amount = 50  # USDT

# Calculate base tokens
base_tokens = quote_amount / price  # 83.33 YES

# Reverse calculation
quote_amount = base_tokens * price  # $50 USDT

Order Examples

Example 1: Simple Market Buy

from opinion_clob_sdk import Client
from opinion_clob_sdk.chain.py_order_utils.model.order import PlaceOrderDataInput
from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide
from opinion_clob_sdk.chain.py_order_utils.model.order_type import MARKET_ORDER

client = Client(...)

# "Buy YES tokens with $100 USDT immediately"
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.BUY,
    orderType=MARKET_ORDER,
    price='0',  # Ignored for market orders
    makerAmountInQuoteToken=100
)

result = client.place_order(order)

Example 2: Limit Buy at Specific Price

# "Buy 50 YES tokens, but only if price drops to $0.45 or lower"
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.BUY,
    orderType=LIMIT_ORDER,
    price='0.45',
    makerAmountInBaseToken=50
)

result = client.place_order(order)
print(f"Order placed, waiting for $0.45 or better")

Example 3: Take Profit Sell

# You own 200 YES, current price is $0.80, you want to sell
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.SELL,
    orderType=MARKET_ORDER,
    price='0',
    makerAmountInBaseToken=200  # Sell all 200 YES
)

result = client.place_order(order)
# You receive ~$160 USDT (200 × $0.80)

Example 4: Limit Sell (Ask)

# "Sell 100 YES tokens, but only at $0.85 or higher"
order = PlaceOrderDataInput(
    marketId=813,
    tokenId='84286908393008806294032747949016601113812276485362312899677525031544985576186',
    side=OrderSide.SELL,
    orderType=LIMIT_ORDER,
    price='0.85',
    makerAmountInBaseToken=100
)

result = client.place_order(order)
print(f"Order on book at $0.85")

Order Lifecycle

1. Order Creation

result = client.place_order(order)

2. Order States

State

Description

Next Actions

Pending

Waiting in orderbook

Cancel or wait

Filled

Fully executed

View trade history

Cancelled

Manually cancelled / Cancelled by system default rules

None

Expired

Time limit reached

Place new order

3. Checking Order Status

# Get all your orders for a market
orders = client.get_my_orders(market_id=813, limit=50)

for order in orders['result']['data']:
    print(f"Order {order['orderId']}: {order['status']}")

4. Cancelling Orders

# Cancel single order
client.cancel_order(orderId='________')

# Cancel all orders for a market
cancelled = client.cancel_all_orders(market_id=813)
print(f"Cancelled {len(cancelled['result'])} orders")

Best Practices

1. Check Orderbook Before Trading

# Always check current prices before placing orders
orderbook = client.get_orderbook(token_id='84286908393008806294032747949016601113812276485362312899677525031544985576186')

best_bid = orderbook['result']['bids'][0]['price'] if orderbook['result']['bids'] else None
best_ask = orderbook['result']['asks'][0]['price'] if orderbook['result']['asks'] else None

print(f"Best bid: {best_bid}, Best ask: {best_ask}")

# Place limit order between bid and ask for better fill chances
if best_bid and best_ask:
    mid_price = (float(best_bid) + float(best_ask)) / 2
    # Place buy slightly above bid, sell slightly below ask

2. Use Limit Orders for Large Sizes

# ❌ Bad: Large market order causes slippage
order = PlaceOrderDataInput(
    side=OrderSide.BUY,
    orderType=MARKET_ORDER,
    makerAmountInQuoteToken=10000  # $10,000 - will move market!
)

# ✅ Good: Break into smaller limit orders
for i in range(10):
    order = PlaceOrderDataInput(
        side=OrderSide.BUY,
        orderType=LIMIT_ORDER,
        price=f'{0.60 + i * 0.001}',  # Incrementing prices
        makerAmountInQuoteToken=1000  # $1,000 each
    )
    client.place_order(order)

3. Price Validation

def validate_price(price: str) -> bool:
    try:
        p = float(price)
        return 0.01 <= p <= 0.99
    except ValueError:
        return False

price = '0.75'
if validate_price(price):
    order = PlaceOrderDataInput(price=price, ...)
else:
    raise ValueError("Invalid price")

Common Mistakes

Mistake 1: Wrong Amount Type

# ❌ Using quote amount for SELL orders often confusing
order = PlaceOrderDataInput(
    side=OrderSide.SELL,
    makerAmountInQuoteToken=50  # "Sell $50 worth" - hard to calculate
)

# ✅ Better: Specify exact tokens to sell
order = PlaceOrderDataInput(
    side=OrderSide.SELL,
    makerAmountInBaseToken=100  # "Sell 100 tokens" - clear
)

Mistake 2: Forgetting Price for Limit Orders

# ❌ Missing price
order = PlaceOrderDataInput(
    orderType=LIMIT_ORDER,
    # price missing!
    makerAmountInQuoteToken=50
)

# ✅ Always specify price for limit orders
order = PlaceOrderDataInput(
    orderType=LIMIT_ORDER,
    price='0.65',
    makerAmountInQuoteToken=50
)

Next Steps

Gas Operations - Understanding when you need BNB
API Reference - Trading - Full method documentation

PreviousClient NextGas Operations

Last updated 10 days ago

hashtagOverview

hashtagOrder Sides

hashtagBUY (Long Position)

hashtagSELL (Short Position or Position Exit)

hashtagOrder Types

hashtagMarket Orders

hashtagLimit Orders

hashtagPrice Mechanics

hashtagPrice Range

hashtagPrice Precision

hashtagBid-Ask Spread

hashtagAmount Specifications

hashtagQuote Token Amount (USDT)

hashtagBase Token Amount (Outcome Tokens)

hashtagConversion Between Amounts

hashtagOrder Examples

hashtagExample 1: Simple Market Buy

hashtagExample 2: Limit Buy at Specific Price

hashtagExample 3: Take Profit Sell

hashtagExample 4: Limit Sell (Ask)

hashtagOrder Lifecycle

hashtag1. Order Creation

hashtag2. Order States

hashtag3. Checking Order Status

hashtag4. Cancelling Orders

hashtagBest Practices

hashtag1. Check Orderbook Before Trading

hashtag2. Use Limit Orders for Large Sizes

hashtag3. Price Validation

hashtagCommon Mistakes

hashtagMistake 1: Wrong Amount Type

hashtagMistake 2: Forgetting Price for Limit Orders

hashtagNext Steps

Overview

Order Sides

BUY (Long Position)

SELL (Short Position or Position Exit)

Order Types

Market Orders

Limit Orders

Price Mechanics

Price Range

Price Precision

Bid-Ask Spread

Amount Specifications

Quote Token Amount (USDT)

Base Token Amount (Outcome Tokens)

Conversion Between Amounts

Order Examples

Example 1: Simple Market Buy

Example 2: Limit Buy at Specific Price

Example 3: Take Profit Sell

Example 4: Limit Sell (Ask)

Order Lifecycle

1. Order Creation

2. Order States

3. Checking Order Status

4. Cancelling Orders

Best Practices

1. Check Orderbook Before Trading

2. Use Limit Orders for Large Sizes

3. Price Validation

Common Mistakes

Mistake 1: Wrong Amount Type

Mistake 2: Forgetting Price for Limit Orders

Next Steps