Overview
Orders form the foundational elements of trading on CoW Protocol. They represent an intent to exchange one token for another, establishing specific terms and conditions.
Order Structure
The Order dataclass contains essential information describing a trade:
from cowdao_cowpy.contracts.order import Order
order = Order(
sell_token="0x...",
buy_token="0x...",
receiver="0x...",
sell_amount="1000000000",
buy_amount="2000000000",
valid_to=1234567890,
app_data="0x...",
fee_amount="0",
kind="sell",
partially_fillable=False,
sell_token_balance="erc20",
buy_token_balance="erc20",
)
Core Fields
| Field | Description |
|---|
| sell_token | The ERC20 token address representing tokens for sale (checksummed address required) |
| buy_token | The ERC20 token address for received tokens (checksummed address required) |
| sell_amount | For sell orders, the exact quantity to sell; for buy orders, the maximum quantity willing to sell |
| buy_amount | For buy orders, the exact quantity to acquire; for sell orders, the minimum quantity willing to receive |
| receiver | The address receiving purchased tokens; if different from order signer, tokens transfer to this address |
| valid_to | Unix timestamp marking order expiration; execution becomes impossible after this time |
Token amounts use string representation to prevent precision loss with large integers.
Order Types
CoW Protocol supports two primary order types via the OrderKind enum:
Sell Orders
Sell orders establish a fixed amount of tokens for sale:
from cowdao_cowpy.contracts.order import Order, OrderKind
sell_order = Order(
sell_token=USDC_ADDRESS,
buy_token=WETH_ADDRESS,
sell_amount="1000000000",
buy_amount="500000000",
kind=OrderKind.SELL.value,
)
- sell_amount: Represents the precise quantity being sold
- buy_amount: Establishes the minimum acceptable receiving quantity
- Execution occurs when market conditions can provide at least the minimum buy amount for the specified sell quantity
Buy Orders
Buy orders specify a fixed amount of tokens for acquisition:
from cowdao_cowpy.contracts.order import Order, OrderKind
buy_order = Order(
sell_token=USDC_ADDRESS,
buy_token=WETH_ADDRESS,
sell_amount="2000000000",
buy_amount="1000000000",
kind=OrderKind.BUY.value,
)
- buy_amount: Represents the precise quantity being acquired
- sell_amount: Establishes the maximum acceptable payment quantity
- Execution occurs when market conditions can provide the specified buy amount within the maximum sell quantity
Order Balance Types
The OrderBalance enum determines token transfer mechanisms:
from cowdao_cowpy.contracts.order import OrderBalance
# Standard ERC20 token balances
order.sell_token_balance = OrderBalance.ERC20.value
order.buy_token_balance = OrderBalance.ERC20.value
# Balancer Vault internal balances
order.sell_token_balance = OrderBalance.INTERNAL.value
# Balancer Vault external balances
order.sell_token_balance = OrderBalance.EXTERNAL.value
Always use OrderBalance.ERC20 for both balances. On most networks (Ethereum mainnet, Gnosis Chain, Arbitrum, Base), the Balancer Vault contract has a compromised admin key, meaning INTERNAL and EXTERNAL balance types may expose users to risk. The CoW Protocol API rejects orders using these balance types on affected networks. Only use Vault balance types after verifying the Balancer deployment is safe on your target network.
Partially Fillable Orders
Orders permit configuration for partial execution:
order = Order(
partially_fillable=True,
)
- Orders can execute across multiple transactions
- Beneficial for sizable orders potentially unable to fill completely in a single batch
- Each execution reduces remaining amount
When disabled (default):
- Complete execution within a single transaction required
- Fill-or-kill execution model
- Simpler logic for most scenarios
Order Lifecycle
Order Creation
Users establish orders expressing their trading intent, then sign via EIP-712:from cowdao_cowpy.cow.swap import sign_order
from cowdao_cowpy.contracts.domain import domain
from cowdao_cowpy.common.constants import CowContractAddress
order_domain = domain(
chain=Chain.MAINNET,
verifying_contract=CowContractAddress.SETTLEMENT_CONTRACT.value
)
signature = sign_order(chain, account, order)
Order Submission
The signed order transmits to the CoW Protocol orderbook API:from cowdao_cowpy.order_book.api import OrderBookApi
from cowdao_cowpy.order_book.generated.model import OrderCreation
order_creation = OrderCreation(
from_=account.address,
sellToken=order.sellToken,
buyToken=order.buyToken,
sellAmount=str(order.sellAmount),
buyAmount=str(order.buyAmount),
validTo=order.validTo,
)
order_uid = await order_book_api.post_order(order_creation)
Order Matching
Competing solvers discover optimal execution through batch auction mechanisms, including:
- Direct order matching (Coincidence of Wants)
- DEX liquidity routing when necessary
- Price optimization and slippage minimization
Order Settlement
The selected solver’s solution executes on-chain, atomically settling all matched orders within a single transaction.
Order Completion or Expiry
- Filled: Order executes successfully; tokens transfer
- Expired: The
valid_to timestamp passes without execution
- Cancelled: The user explicitly revokes the order before execution
Order UID
Each order receives a unique identifier combining the order hash, owner, and validity:
from cowdao_cowpy.contracts.order import compute_order_uid
from cowdao_cowpy.contracts.domain import domain
order_domain = domain(chain=Chain.MAINNET, verifying_contract=SETTLEMENT_CONTRACT)
order_uid = compute_order_uid(order_domain, order, owner_address)
print(f"Order UID: {order_uid}")
The order UID measures 56 bytes (112 hexadecimal characters) and facilitates order status queries, execution tracking, and cancellation operations.
App Data
The app_data parameter permits applications to embed metadata within orders:
from cowdao_cowpy.app_data.utils import DEFAULT_APP_DATA_HASH
order = Order(
app_data=DEFAULT_APP_DATA_HASH,
)
- Application identification
- Referral monitoring
- Order uniqueness verification (duplicate prevention)
- Specialized integration metadata
The app data undergoes hashing to a 32-byte representation and may reference IPFS content for expanded metadata.
Fee Structure
CoW Protocol enables gasless trading with fees denominated in the sell token:
order = Order(
fee_amount="0",
)
Execution expenses integrate into the quoted price. The protocol identifies user surplus and subsidizes gas expenses, delivering superior efficiency compared to conventional DEXs.
Example: Complete Order Flow
import asyncio
from web3 import Account, Web3
from web3.types import Wei
from cowdao_cowpy.cow.swap import swap_tokens
from cowdao_cowpy.common.chains import Chain
async def create_and_execute_order():
account = Account.from_key(PRIVATE_KEY)
sell_token = Web3.to_checksum_address("0xbe72E441BF55620febc26715db68d3494213D8Cb")
buy_token = Web3.to_checksum_address("0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14")
result = await swap_tokens(
amount=Wei(1000000000),
account=account,
chain=Chain.SEPOLIA,
sell_token=sell_token,
buy_token=buy_token,
slippage_tolerance=0.005,
partially_fillable=False,
)
print(f"Order submitted successfully!")
print(f"Order UID: {result.uid}")
print(f"Track at: {result.url}")
asyncio.run(create_and_execute_order())
The swap_tokens function manages the complete order lifecycle, including quote retrieval, order creation, signing, and orderbook submission.
