Overview
The OrderBookApi class provides a comprehensive interface for interacting with the CoW Protocol order book. This guide covers creating orders, querying order status, fetching trades, and canceling orders.
Initializing the API Client
from cowdao_cowpy.order_book.api import OrderBookApi
from cowdao_cowpy.order_book.config import OrderBookAPIConfigFactory
from cowdao_cowpy.common.config import SupportedChainId
# Use default configuration (mainnet, production)
order_book_api = OrderBookApi()
# Or specify chain and environment
config = OrderBookAPIConfigFactory.get_config(
env="prod", # or "staging"
chain_id=SupportedChainId.MAINNET
)
order_book_api = OrderBookApi(config)
Creating Orders
Request a Quote
Before creating an order, get a price quote from the API:from cowdao_cowpy.order_book.generated.model import (
OrderQuoteRequest,
OrderQuoteSide1,
OrderQuoteSideKindSell,
TokenAmount,
)
from web3 import Web3
# Prepare quote request
quote_request = OrderQuoteRequest(
sellToken=Web3.to_checksum_address(
"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" # USDC
),
buyToken=Web3.to_checksum_address(
"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" # WETH
),
from_=account.address,
appData="0x0000000000000000000000000000000000000000000000000000000000000000",
)
# Specify sell side with amount
order_side = OrderQuoteSide1(
kind=OrderQuoteSideKindSell.sell,
sellAmountBeforeFee=TokenAmount("1000000000") # 1000 USDC (6 decimals)
)
# Get quote
quote_response = await order_book_api.post_quote(
request=quote_request,
side=order_side
)
print(f"Buy amount: {quote_response.quote.buyAmount}")
print(f"Valid until: {quote_response.quote.validTo}")
Create and Sign Order
Build an order from the quote and sign it:from cowdao_cowpy.contracts.order import Order
from cowdao_cowpy.contracts.sign import sign_order, SigningScheme
from cowdao_cowpy.contracts.domain import domain
from cowdao_cowpy.common.constants import CowContractAddress
from cowdao_cowpy.common.chains import Chain
from eth_account.signers.local import LocalAccount
from web3 import Account
account: LocalAccount = Account.from_key("YOUR_PRIVATE_KEY")
order = Order(
sell_token=quote_request.sellToken,
buy_token=quote_request.buyToken,
receiver=account.address,
sell_amount=str(1000000000),
buy_amount=str(quote_response.quote.buyAmount.root),
valid_to=quote_response.quote.validTo,
app_data="0x0000000000000000000000000000000000000000000000000000000000000000",
fee_amount="0",
kind="sell",
partially_fillable=False,
sell_token_balance="erc20",
buy_token_balance="erc20",
)
order_domain = domain(
chain=Chain.MAINNET,
verifying_contract=CowContractAddress.SETTLEMENT_CONTRACT.value
)
signature = sign_order(order_domain, order, account, SigningScheme.EIP712)
Submit Order
Post the signed order to the order book:from cowdao_cowpy.order_book.generated.model import OrderCreation
order_creation = OrderCreation(
from_=account.address,
sellToken=order.sellToken,
buyToken=order.buyToken,
sellAmount=order.sellAmount,
buyAmount=order.buyAmount,
validTo=order.validTo,
appData=order.appData,
feeAmount=order.feeAmount,
kind=order.kind,
partiallyFillable=order.partiallyFillable,
receiver=order.receiver,
signature=signature.to_string(),
signingScheme=signature.scheme.name.lower(),
)
order_uid = await order_book_api.post_order(order_creation)
print(f"Order UID: {order_uid}")
Fetching Orders
Get Order by UID
from cowdao_cowpy.order_book.generated.model import UID
order_uid = UID("0x...")
order = await order_book_api.get_order_by_uid(order_uid)
print(f"Status: {order.status}")
print(f"Sell amount: {order.sellAmount}")
print(f"Buy amount: {order.buyAmount}")
Get All Orders for an Owner
from cowdao_cowpy.order_book.generated.model import Address
owner = Address("0x...")
orders = await order_book_api.get_orders_by_owner(
owner=owner,
limit=100,
offset=0,
)
for order in orders:
print(f"Order {order.uid}: {order.status}")
Search Across Environments
order = await order_book_api.get_order_multi_env(order_uid)
if order:
print(f"Order found: {order.status}")
else:
print("Order not found in any environment")
Fetching Trades
Trades by Order UID
trades = await order_book_api.get_trades_by_order_uid(order_uid)
for trade in trades:
print(f"Trade executed at block {trade.blockNumber}")
print(f"Sell amount: {trade.sellAmount}")
print(f"Buy amount: {trade.buyAmount}")
Trades by Owner
owner = Address("0x...")
trades = await order_book_api.get_trades_by_owner(owner)
print(f"Total trades: {len(trades)}")
Canceling Orders
Order cancellations must be signed by the order owner using EIP-712 typed data.
Cancel Single Order
from cowdao_cowpy.contracts.sign import sign_order_cancellation, SigningScheme
from cowdao_cowpy.order_book.generated.model import OrderCancellations
cancellation_signature = sign_order_cancellation(
domain=order_domain,
order_uid=order_uid.root,
owner=account,
scheme=SigningScheme.EIP712
)
order_cancellations = OrderCancellations(
orderUids=[order_uid.root],
signature=cancellation_signature.to_string(),
signingScheme=cancellation_signature.scheme.name.lower(),
)
result = await order_book_api.delete_order(order_cancellations)
print(f"Cancellation result: {result}")
Cancel Multiple Orders
from cowdao_cowpy.contracts.sign import sign_order_cancellations
order_uids_to_cancel = ["0x...", "0x...", "0x..."]
cancellation_signature = sign_order_cancellations(
domain=order_domain,
order_uids=order_uids_to_cancel,
owner=account,
scheme=SigningScheme.EIP712
)
order_cancellations = OrderCancellations(
orderUids=order_uids_to_cancel,
signature=cancellation_signature.to_string(),
signingScheme=cancellation_signature.scheme.name.lower(),
)
result = await order_book_api.delete_order(order_cancellations)
print(f"Cancelled {len(order_uids_to_cancel)} orders")
Transaction and Pricing Data
Orders by Transaction Hash
from cowdao_cowpy.order_book.generated.model import TransactionHash
tx_hash = TransactionHash("0x...")
orders = await order_book_api.get_tx_orders(tx_hash)
for order in orders:
print(f"Order {order.uid} in transaction")
Native Token Price
token_address = Address("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
price = await order_book_api.get_native_price(token_address)
print(f"Token price: ${price.price}")
User Surplus
user_address = Address("0x...")
surplus = await order_book_api.get_total_surplus(user_address)
print(f"Total surplus: {surplus.totalSurplus}")
Solver Competition Data
# Get latest solver competition
competition = await order_book_api.get_solver_competition("latest")
print(f"Auction ID: {competition.auctionId}")
print(f"Winner: {competition.winner}")
# Get competition by transaction
competition = await order_book_api.get_solver_competition_by_tx_hash(
TransactionHash("0x...")
)
Working with App Data
Upload App Data
from cowdao_cowpy.order_book.generated.model import AppDataObject, AppData, AppDataHash
import json
app_data_json = {
"appCode": "MyTradingApp",
"metadata": {
"referrer": {"address": "0x..."},
}
}
app_data_object = AppDataObject(
fullAppData=AppData(json.dumps(app_data_json))
)
app_data_hash = await order_book_api.put_app_data(app_data=app_data_object)
print(f"App data hash: {app_data_hash.root}")
Retrieve App Data
app_data_hash = AppDataHash(root="0x...")
app_data = await order_book_api.get_app_data(app_data_hash)
print(f"App data: {app_data}")
Complete Order Management Example
import asyncio
from web3 import Web3, Account
from cowdao_cowpy.order_book.api import OrderBookApi
from cowdao_cowpy.order_book.config import OrderBookAPIConfigFactory
from cowdao_cowpy.common.config import SupportedChainId
from cowdao_cowpy.order_book.generated.model import Address, UID
async def manage_orders():
config = OrderBookAPIConfigFactory.get_config(
env="prod",
chain_id=SupportedChainId.MAINNET
)
order_book_api = OrderBookApi(config)
account_address = Address("0x...")
orders = await order_book_api.get_orders_by_owner(account_address)
print(f"Found {len(orders)} orders")
for order in orders:
print(f"\nOrder {order.uid}")
print(f" Status: {order.status}")
print(f" Sell: {order.sellAmount} {order.sellToken}")
print(f" Buy: {order.buyAmount} {order.buyToken}")
trades = await order_book_api.get_trades_by_order_uid(UID(order.uid))
print(f" Trades: {len(trades)}")
order_link = order_book_api.get_order_link(UID(order.uid))
print(f" Explorer: {order_link}")
if __name__ == "__main__":
asyncio.run(manage_orders())
API Reference
| Method | Description |
|---|
post_order(order_creation) | Submit a new order |
get_order_by_uid(order_uid) | Fetch order by UID |
get_orders_by_owner(owner, limit, offset) | Get all orders for an address |
delete_order(order_cancellations) | Cancel one or more orders |
post_quote(request, side, validity) | Request a price quote |
get_trades_by_order_uid(order_uid) | Get trades for an order |
get_trades_by_owner(owner) | Get all trades for an address |
get_tx_orders(tx_hash) | Get orders in a transaction |
get_native_price(token_address) | Get token price in native currency |
get_total_surplus(user) | Get total surplus for a user |
get_solver_competition(action_id) | Get solver competition data |
put_app_data(app_data, hash) | Upload app data |
get_app_data(app_data_hash) | Retrieve app data |
Order Status Values
Orders can have the following statuses:
open — Order is available for solvers
fulfilled — Order has been completely filled
expired — Order validity period has passed
cancelled — Order was cancelled by the owner
presignaturePending — Waiting for Safe presignature
Use the get_order_link() method to get a direct URL to view the order on CoW Explorer.
Next Steps