Common

API reference for common types, configuration, and utilities in the CoW Protocol Python SDK

The common module provides core types, configuration, constants, and error handling used throughout the SDK.

Chain

Enum representing supported blockchain networks.

from cowdao_cowpy.common.chains import Chain

class Chain(Enum):
    MAINNET = (SupportedChainId.MAINNET, "ethereum", "https://etherscan.io")
    SEPOLIA = (SupportedChainId.SEPOLIA, "sepolia", "https://sepolia.etherscan.io")
    GNOSIS = (SupportedChainId.GNOSIS_CHAIN, "gnosis", "https://gnosisscan.io")
    ARBITRUM_ONE = (SupportedChainId.ARBITRUM_ONE, "arbitrum_one", "https://arbiscan.io")
    BASE = (SupportedChainId.BASE, "base", "https://basescan.org/")
    POLYGON = (SupportedChainId.POLYGON, "polygon", "https://polygonscan.com")
    AVALANCHE = (SupportedChainId.AVALANCHE, "avalanche", "https://snowtrace.io")
    BNB = (SupportedChainId.BNB, "bnb", "https://bscscan.com")

Properties

Property	Type	Description
chain_id	SupportedChainId	The numeric chain ID as an enum value
name	str	Human-readable network name
explorer	str	Block explorer URL

chain = Chain.MAINNET
chain.chain_id      # SupportedChainId.MAINNET (value: 1)
chain.name          # "ethereum"
chain.explorer      # "https://etherscan.io"

---

Configuration

SupportedChainId

from cowdao_cowpy.common.config import SupportedChainId

class SupportedChainId(Enum):
    MAINNET = 1
    GNOSIS_CHAIN = 100
    SEPOLIA = 11155111
    ARBITRUM_ONE = 42161
    BASE = 8453
    POLYGON = 137
    AVALANCHE = 43114
    BNB = 56

CowEnv

from cowdao_cowpy.common.config import CowEnv

class CowEnv(Enum):
    PROD = "prod"
    STAGING = "staging"

ApiContext

from cowdao_cowpy.common.config import ApiContext, SupportedChainId, CowEnv

context = ApiContext(
    chain_id=SupportedChainId.MAINNET,
    env=CowEnv.PROD,
    base_urls=None,
    max_tries=5
)

Parameter	Type	Default	Description
chain_id	SupportedChainId	Required	The blockchain network to use
env	CowEnv	Required	The API environment
base_urls	Optional[ApiBaseUrls]	None	Custom base URLs for API endpoints
max_tries	Optional[int]	5	Maximum retry attempts for API requests

DEFAULT_COW_API_CONTEXT

DEFAULT_COW_API_CONTEXT = ApiContext(
    env=CowEnv.PROD,
    chain_id=SupportedChainId.MAINNET
)

IPFSConfig

class IPFSConfig(Enum):
    READ_URI = "https://gnosis.mypinata.cloud/ipfs"
    WRITE_URI = "https://api.pinata.cloud"

---

Constants

CowContractAddress

from cowdao_cowpy.common.constants import CowContractAddress

class CowContractAddress(Enum):
    VAULT_RELAYER = "0xC92E8bdf79f0507f65a392b0ab4667716BFE0110"
    COMPOSABLE_COW = "0xfdaFc9d1902f4e0b84f65F49f244b32b31013b74"
    SETTLEMENT_CONTRACT = "0x9008D19f58AAbD9eD0D60971565AA8510560ab41"
    EXTENSIBLE_FALLBACK_HANDLER = "0x2f55e8b20D0B9FEFA187AA7d00B6Cbe563605bF5"

Contract Address Maps

from cowdao_cowpy.common.constants import (
    COW_PROTOCOL_SETTLEMENT_CONTRACT_CHAIN_ADDRESS_MAP,
    COW_PROTOCOL_VAULT_RELAYER_CHAIN_ADDRESS_MAP,
    COMPOSABLE_COW_CONTRACT_CHAIN_ADDRESS_MAP,
    EXTENSIBLE_FALLBACK_HANDLER_CONTRACT_CHAIN_ADDRESS_MAP,
)

# Get settlement contract for mainnet
settlement_address = COW_PROTOCOL_SETTLEMENT_CONTRACT_CHAIN_ADDRESS_MAP[
    SupportedChainId.MAINNET
].value

ZERO_APP_DATA

ZERO_APP_DATA = "0x0000000000000000000000000000000000000000000000000000000000000000"

---

Error Handling

CowError

Base exception class for CoW Protocol SDK errors.

from cowdao_cowpy.common.cow_error import CowError

class CowError(Exception):
    def __init__(self, message, error_code=None):
        super().__init__(message)
        self.error_code = error_code

Parameter	Type	Default	Description
message	str	Required	Error description
error_code	Optional[Any]	None	Optional error code for programmatic handling

try:
    # SDK operation
    pass
except CowError as e:
    print(f"CoW SDK Error: {e}")
    if e.error_code:
        print(f"Error code: {e.error_code}")

LOG_PREFIX

from cowdao_cowpy.common.cow_error import LOG_PREFIX
# "cow-sdk: "

---

Complete Example

from cowdao_cowpy.common.chains import Chain, SUPPORTED_CHAINS
from cowdao_cowpy.common.config import ApiContext, CowEnv, SupportedChainId
from cowdao_cowpy.common.constants import (
    COW_PROTOCOL_SETTLEMENT_CONTRACT_CHAIN_ADDRESS_MAP,
    COMPOSABLE_COW_CONTRACT_CHAIN_ADDRESS_MAP,
    ZERO_APP_DATA,
)
from cowdao_cowpy.common.cow_error import CowError, LOG_PREFIX

def setup_chain_config(chain: Chain):
    try:
        chain_id = chain.chain_id

        context = ApiContext(
            chain_id=chain_id,
            env=CowEnv.PROD,
            max_tries=3
        )

        settlement = COW_PROTOCOL_SETTLEMENT_CONTRACT_CHAIN_ADDRESS_MAP[chain_id].value
        composable_cow = COMPOSABLE_COW_CONTRACT_CHAIN_ADDRESS_MAP[chain_id].value

        print(f"{LOG_PREFIX} Chain: {chain.name}")
        print(f"{LOG_PREFIX} Settlement: {settlement}")
        print(f"{LOG_PREFIX} ComposableCow: {composable_cow}")

        return context
    except KeyError:
        raise CowError(
            f"Chain {chain.name} not supported",
            error_code="UNSUPPORTED_CHAIN"
        )

config = setup_chain_config(Chain.MAINNET)

# List all supported chains
for chain in SUPPORTED_CHAINS:
    print(f"  - {chain.name} (ID: {chain.chain_id.value})")

Best Practices

# Use enum values for chain selection
chain = Chain.MAINNET  # Good

# Create explicit contexts for different environments
prod_context = ApiContext(chain_id=SupportedChainId.MAINNET, env=CowEnv.PROD)
staging_context = ApiContext(chain_id=SupportedChainId.SEPOLIA, env=CowEnv.STAGING)