AI Agent Orders

This tutorial shows how an autonomous AI agent (running in a loop, triggered by events, or driven by an LLM) can create and manage orders on CoW Protocol through the REST API. By the end you will have a working Python script that:

Fetches a quote
Applies slippage protection
Signs the order (EIP-712)
Submits it to the order book
Monitors execution with proper error recovery

This guide builds on the same API flow as the Raw API (cURL) and Python quickstarts. If you have not placed an order before, start there.

Prerequisites

Before starting, make sure your agent has access to:

A private key for an EOA wallet (stored securely — environment variable or secrets manager)
ETH on the target chain — only needed for token approval transactions, not for order submission
Tokens to trade — the sell token must already be in the wallet. Any ERC-20 token is tradeable, not just those on the CoW token list (the list is used by the UI for display purposes)
Token approval for the GPv2VaultRelayer (0xC92E8bdf79f0507f65a392b0ab4667716BFE0110) to spend the sell token
Python 3.8+ with requests, web3, and eth-account installed

API base URLs by network:

Network	Base URL
Ethereum Mainnet	`https://api.cow.fi/mainnet/api/v1`
Gnosis Chain	`https://api.cow.fi/xdai/api/v1`
Arbitrum One	`https://api.cow.fi/arbitrum_one/api/v1`
Base	`https://api.cow.fi/base/api/v1`
Sepolia (testnet)	`https://api.cow.fi/sepolia/api/v1`

Never hardcode private keys. Use os.environ.get("PRIVATE_KEY") in Python (not string interpolation or shell expansion) to avoid exposing secrets in process argument lists visible via ps. Avoid passing keys as command-line arguments (e.g., python script.py --key 0x...). For production agents, use a secrets manager.

Want to trade native ETH (not WETH)? You can use Eth-flow to place orders selling native ETH directly, without wrapping to WETH first.

Walkthrough

Agent-specific considerations

Rate limiting

The CoW Protocol API enforces per-IP rate limits. Key limits for agent workflows:

Endpoint	Limit
`POST /quote`	10 req/s
`POST /orders`	5 req/s
`GET /orders/{uid}`	100 req/min

Always implement exponential backoff with jitter for 429 responses. See the full Rate Limits & Quotas reference for details and backoff code examples.

Quote freshness

Quotes reflect current market conditions and expire. For agents:

Re-quote if the agent delays materially between quoting and submission, even if validTo has not been reached yet.
Re-quote whenever the agent changes any input that affects execution, such as the token pair, amount, or slippage settings.
Treat quote data as short-lived state: cache it only within the current decision loop and refresh it before signing if conditions have changed.

Error recovery

Your agent should handle these HTTP responses:

Status code	Meaning	Agent action
`200`	Success	Proceed normally
`400`	Bad request (invalid parameters, stale quote, insufficient balance)	Parse the error body, fix the issue, and retry. Common errors: `InsufficientBalance`, `InsufficientAllowance`, `QuoteNotFound`, `InvalidQuote`.
`429`	Rate limited	Read the `Retry-After` header, wait that duration plus random jitter, then retry. Max 3 retries.
`403`	Cloudflare WAF block	Your IP has been flagged. Do not retry in a loop — this will make it worse. See Rate Limits.
`500`	Server error	Wait 5 seconds and retry. Max 3 retries. If persistent, back off longer.

def api_request(method, url, json=None, max_retries=3):
    """Make an API request with exponential backoff for rate limits and errors."""
    for attempt in range(max_retries):
        resp = requests.request(method, url, json=json)

        if resp.status_code == 200 or resp.status_code == 201:
            return resp

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(retry_after + random.random())
            continue

        if resp.status_code >= 500:
            time.sleep(5 * (attempt + 1) + random.random())
            continue

        # 4xx errors (except 429) — do not retry, raise immediately
        resp.raise_for_status()

    raise Exception(f"Failed after {max_retries} retries: {url}")

Idempotency

Order UIDs are deterministic — derived from the order parameters and signer address. Submitting the same signed order twice returns the same UID without creating a duplicate. This means:

Your agent can safely retry a failed submission without risking double-execution.
If your agent crashes between signing and confirming submission, it can resubmit the same signed payload on restart.

Gas management

CoW Protocol orders are off-chain intents. Submitting and monitoring orders requires zero gas. Your agent only needs ETH for:

Token approvals — a one-time approve() transaction per sell token for the GPv2VaultRelayer
On-chain cancellations — if you cancel via the settlement contract instead of the API (optional)

For most agent workflows, a single approval per token is sufficient. The agent itself does not pay gas for trade execution — solvers handle that.

Complete example

A minimal Python script that runs the full flow:

"""
Minimal CoW Protocol agent order — full flow from quote to fill.

Usage:
  export PRIVATE_KEY="0x..."
  python agent_order.py
"""

import os
import time
import random
import requests
from eth_account import Account
from eth_account.messages import encode_typed_data

# --------------- Configuration ---------------
PRIVATE_KEY = os.environ["PRIVATE_KEY"]
API_BASE = "https://api.cow.fi/sepolia/api/v1"
CHAIN_ID = 11155111
SETTLEMENT_CONTRACT = "0x9008D19f58AAbD9eD0D60971565AA8510560ab41"

SELL_TOKEN = "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14"  # WETH
BUY_TOKEN = "0xbe72E441BF55620febc26715db68d3494213D8Cb"   # COW
SELL_AMOUNT = 10**17  # 0.1 WETH
SLIPPAGE_BPS = 50     # 0.5%

account = Account.from_key(PRIVATE_KEY)

# --------------- Helpers ---------------
def api_request(method, url, json=None, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.request(method, url, json=json)
        if resp.status_code in (200, 201):
            return resp
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(retry_after + random.random())
            continue
        if resp.status_code >= 500:
            time.sleep(5 * (attempt + 1) + random.random())
            continue
        resp.raise_for_status()
    raise Exception(f"Failed after {max_retries} retries: {url}")


# --------------- Step 1: Quote ---------------
quote_resp = api_request("POST", f"{API_BASE}/quote", json={
    "sellToken": SELL_TOKEN,
    "buyToken": BUY_TOKEN,
    "sellAmountBeforeFee": str(SELL_AMOUNT),
    "kind": "sell",
    "from": account.address,
    "receiver": account.address,
    "validFor": 600,
    "signingScheme": "eip712",
    "appData": "{}",
    "appDataHash": "0xb48d38f93eaa084033fc5970bf96e559c33c4cdc07d889ab00b4d63f9590739d",
})
quote_data = quote_resp.json()
quote = quote_data["quote"]
quote_id = quote_data["id"]
print(f"Quote: sell {quote['sellAmount']}, buy ~{quote['buyAmount']}, fee {quote['feeAmount']}")

# --------------- Step 2: Slippage ---------------
min_buy = int(int(quote["buyAmount"]) * (10000 - SLIPPAGE_BPS) / 10000)
sell_amount_to_sign = int(quote["sellAmount"]) + int(quote["feeAmount"])
app_data_hash = quote.get("appDataHash", quote["appData"])

# --------------- Step 3: Sign ---------------
domain = {
    "name": "Gnosis Protocol",
    "version": "v2",
    "chainId": CHAIN_ID,
    "verifyingContract": SETTLEMENT_CONTRACT,
}

order_types = {
    "Order": [
        {"name": "sellToken", "type": "address"},
        {"name": "buyToken", "type": "address"},
        {"name": "receiver", "type": "address"},
        {"name": "sellAmount", "type": "uint256"},
        {"name": "buyAmount", "type": "uint256"},
        {"name": "validTo", "type": "uint32"},
        {"name": "appData", "type": "bytes32"},
        {"name": "feeAmount", "type": "uint256"},
        {"name": "kind", "type": "string"},
        {"name": "partiallyFillable", "type": "bool"},
        {"name": "sellTokenBalance", "type": "string"},
        {"name": "buyTokenBalance", "type": "string"},
    ]
}

order_data = {
    "sellToken": quote["sellToken"],
    "buyToken": quote["buyToken"],
    "receiver": quote["receiver"],
    "sellAmount": sell_amount_to_sign,
    "buyAmount": min_buy,
    "validTo": quote["validTo"],
    "appData": bytes.fromhex(app_data_hash[2:]),
    "feeAmount": 0,
    "kind": "sell",
    "partiallyFillable": False,
    "sellTokenBalance": "erc20",
    "buyTokenBalance": "erc20",
}

signable = encode_typed_data(domain, order_types, order_data)
signed = account.sign_message(signable)
signature = signed.signature.hex()
print(f"Signed order: 0x{signature[:16]}...")

# --------------- Step 4: Submit ---------------
submit_resp = api_request("POST", f"{API_BASE}/orders", json={
    "sellToken": quote["sellToken"],
    "buyToken": quote["buyToken"],
    "receiver": quote["receiver"],
    "sellAmount": str(sell_amount_to_sign),
    "buyAmount": str(min_buy),
    "validTo": quote["validTo"],
    "appData": quote["appData"],
    "appDataHash": quote.get("appDataHash"),
    "feeAmount": "0",
    "kind": "sell",
    "partiallyFillable": False,
    "sellTokenBalance": "erc20",
    "buyTokenBalance": "erc20",
    "signingScheme": "eip712",
    "signature": "0x" + signature,
    "from": account.address,
    "quoteId": quote_id,
})
order_uid = submit_resp.json()
print(f"Order UID: {order_uid}")
print(f"Explorer:  https://explorer.cow.fi/sepolia/orders/{order_uid}")

# --------------- Step 5: Monitor ---------------
print("Monitoring order...")
deadline = time.time() + 300  # 5 minute timeout

while time.time() < deadline:
    resp = api_request("GET", f"{API_BASE}/orders/{order_uid}")
    status = resp.json()["status"]
    print(f"  Status: {status}")

    if status in ("fulfilled", "expired", "cancelled"):
        break
    time.sleep(10)

if status == "fulfilled":
    print("Order filled successfully.")
elif status == "expired":
    print("Order expired. Re-quote and retry with fresh market data.")
else:
    print(f"Final status: {status}")

Next steps

Rate Limits & Quotas — full rate limit details and backoff strategies
How Intents Are Formed — understand the fee pipeline and amount calculations
Signing Schemes — EIP-712, ethSign, ERC-1271, and PreSign options
TypeScript SDK — higher-level SDK with built-in rate limiting
cow-py SDK — Python SDK with swap_tokens() and automatic backoff
API Integration Guide — complete REST API reference

Overview

How It Works

Benefits

Order Types

Flash Loans

CoW AMM

CoW Explorer

Integration

Architecture

API Reference

Core Reference

Auctions

Prerequisites

Walkthrough

Agent-specific considerations

Rate limiting

Quote freshness

Error recovery

Idempotency

Gas management

Complete example

Next steps

​Prerequisites

​Walkthrough

​Agent-specific considerations

​Rate limiting

​Quote freshness

​Error recovery

​Idempotency

​Gas management

​Complete example

​Next steps

Prerequisites

Walkthrough

Agent-specific considerations

Rate limiting

Quote freshness

Error recovery

Idempotency

Gas management

Complete example

Next steps