Orderbook API - CoW Protocol Services

The Orderbook API is the primary interface for order placement, querying, and price estimation in CoW Protocol.

Base URLs

The Orderbook API is deployed across multiple chains with both production and staging environments:

Production

Mainnet: https://api.cow.fi/mainnet
Gnosis Chain: https://api.cow.fi/xdai
Arbitrum One: https://api.cow.fi/arbitrum_one
Base: https://api.cow.fi/base
Avalanche: https://api.cow.fi/avalanche
Polygon: https://api.cow.fi/polygon
Lens: https://api.cow.fi/lens
Linea: https://api.cow.fi/linea
BNB: https://api.cow.fi/bnb
Plasma: https://api.cow.fi/plasma
Ink: https://api.cow.fi/ink
Sepolia (Testnet): https://api.cow.fi/sepolia

Staging

Mainnet: https://barn.api.cow.fi/mainnet
Gnosis Chain: https://barn.api.cow.fi/xdai
Arbitrum One: https://barn.api.cow.fi/arbitrum_one
Base: https://barn.api.cow.fi/base
And more…

Local Development

http://localhost:8080

Authentication

Most endpoints are public and don’t require authentication. Order placement and cancellation require EIP-712 signatures to prove ownership.

Rate Limits

Order creation: Protected against excessive order placements (HTTP 429)
Quote requests: Protected against excessive quote requests (HTTP 429)
Order cancellation: Best-effort cancellation to prevent in-flight settlement conflicts

Key Endpoints

Create Order

curl -X POST "https://api.cow.fi/mainnet/api/v1/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
    "buyToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "sellAmount": "1000000000000000000",
    "buyAmount": "900000000000000000",
    "validTo": 1678886400,
    "appData": "{}",
    "feeAmount": "0",
    "kind": "sell",
    "partiallyFillable": false,
    "signingScheme": "eip712",
    "signature": "0x..."
  }'

Creates a new order. To replace an existing order, include a valid replacement order UID in the appData. Endpoint: POST /api/v1/orders

Request Body

sellToken

address

required

ERC-20 token to be sold (20 byte hex address with 0x prefix)

buyToken

address

required

ERC-20 token to be bought (20 byte hex address with 0x prefix)

sellAmount

string

required

Amount of sellToken in atoms (decimal string)

buyAmount

string

required

Amount of buyToken in atoms (decimal string)

validTo

integer

required

Unix timestamp (uint32) until which the order is valid

appData

string

required

Full appData JSON string or appDataHash (32 bytes hex with 0x prefix). Use "{}" for no custom appData.

feeAmount

string

required

Fee amount in sellToken atoms. Set to “0” for new orders (fees computed dynamically by solvers).

kind

string

required

Order type: "sell" or "buy"

partiallyFillable

boolean

required

Whether the order can be partially filled

signingScheme

string

required

Signature type: "eip712", "ethsign", "presign", or "eip1271"

signature

string

required

65 bytes encoded as hex with 0x prefix (r || s || v)

receiver

address

Optional address to receive the bought tokens (defaults to owner)

sellTokenBalance

string

default:"erc20"

Where to draw sellToken from: "erc20", "internal", or "external"

buyTokenBalance

string

default:"erc20"

Where to transfer buyToken: "erc20" or "internal"

from

address

Address that must match the signature signer (helps catch encoding errors)

quoteId

integer

Optional quote ID to link order to a quote for slippage analysis

appDataHash

string

For debugging: hash of appData for verification

Response

orderUid

string

Unique order identifier (56 bytes hex with 0x prefix)

Status Codes:

201: Order accepted
400: Validation error (see OrderPostError)
403: Account is deny-listed
404: No route found for quoting the order
422: Invalid JSON
429: Too many order placements
500: Internal error

Error Types

Show OrderPostError Types

DuplicatedOrder: Order already exists
QuoteNotFound: No valid quote found
QuoteNotVerified: Quote couldn’t be verified
InvalidQuote: Quote data is invalid
MissingFrom: Required from field missing
WrongOwner: Signature doesn’t match owner
InvalidEip1271Signature: EIP-1271 signature verification failed
InsufficientBalance: Not enough token balance
InsufficientAllowance: Not enough token allowance
InvalidSignature: Signature is invalid
SellAmountOverflow: Sell amount exceeds limits
TransferSimulationFailed: Token transfer simulation failed
ZeroAmount: Sell or buy amount is zero
IncompatibleSigningScheme: Signing scheme not supported
TooManyLimitOrders: Limit order quota exceeded
TooMuchGas: Gas estimate too high
UnsupportedBuyTokenDestination: Invalid buyTokenBalance
UnsupportedSellTokenSource: Invalid sellTokenBalance
UnsupportedOrderType: Order type not supported
InsufficientValidTo: validTo too soon
ExcessiveValidTo: validTo too far in future
InvalidNativeSellToken: Cannot sell native token
SameBuyAndSellToken: Buy and sell tokens are the same
UnsupportedToken: Token not supported
InvalidAppData: AppData format invalid
AppDataHashMismatch: AppData hash doesn’t match
AppDataMismatch: AppData content mismatch
AppdataFromMismatch: AppData from field mismatch
MetadataSerializationFailed: Failed to serialize metadata
OldOrderActivelyBidOn: Cannot replace order with active bids

Get Order

curl "https://api.cow.fi/mainnet/api/v1/orders/0xff2e2e54d178997f173266817c1e9ed6fee1a1aae4b43971c53b543cffcc2969845c6f5599fbb25dbdd1b9b013daf85c03f3c63763e4bc4a"

Retrieves an existing order by its UID. Endpoint: GET /api/v1/orders/{UID}

Path Parameters

UID

string

required

56 bytes order UID encoded as hex with 0x prefix

Response

order

object

Complete order data including creation parameters and metadata

Show Order Fields

uid

string

Order unique identifier

sellToken

address

Token being sold

buyToken

address

Token being bought

sellAmount

string

Amount to sell in atoms

buyAmount

string

Amount to buy in atoms

validTo

integer

Unix timestamp expiration

kind

string

Order type: "sell" or "buy"

owner

address

Order owner address (signer)

status

string

Current status: "presignaturePending", "open", "fulfilled", "cancelled", or "expired"

class

string

Order class: "market", "limit", or "liquidity"

creationDate

string

ISO 8601 UTC timestamp of creation

executedSellAmount

string

Total amount of sellToken executed (including fees)

executedBuyAmount

string

Total amount of buyToken received

executedFee

string

Total fees paid (network + protocol)

executedFeeToken

address

Token in which fee was captured

settlementContract

address

CoW Protocol settlement contract address

quote

object

Original quote data if order was created with a quote

Status Codes:

200: Order found
400: Invalid order UID
404: Order not found

Get Orders by Account

curl "https://api.cow.fi/mainnet/api/v1/account/0x6810e776880c02933d47db1b9fc05908e5386b96/orders?offset=0&limit=10"

Retrieves paginated orders for a specific address, sorted by creation date descending (newest first). Endpoint: GET /api/v1/account/{owner}/orders

Path Parameters

owner

address

required

Account address (20 byte hex with 0x prefix)

Query Parameters

offset

integer

default:"0"

Pagination offset

limit

integer

default:"10"

Results per page (min: 1, max: 1000)

Response

orders

array

Array of order objects (see Get Order response)

Status Codes:

200: Success
400: Invalid parameters (e.g., limit too large)

Get Quote

curl -X POST "https://api.cow.fi/mainnet/api/v1/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
    "buyToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "kind": "sell",
    "sellAmountBeforeFee": "1000000000000000000",
    "from": "0x6810e776880c02933d47db1b9fc05908e5386b96",
    "priceQuality": "verified",
    "validFor": 600
  }'

Computes a price quote and fee estimate for order parameters. Returns a complete order ready to sign. Endpoint: POST /api/v1/quote

Request Body

sellToken

address

required

Token to sell

buyToken

address

required

Token to buy

from

address

required

Address that will sign the order

kind

string

required

Quote type: "sell" or "buy"

Amount Parameters (one of):

sellAmountBeforeFee

string

For sell orders: total amount available (fee deducted from this)

sellAmountAfterFee

string

For sell orders: exact sellAmount (fee added on top)

buyAmountAfterFee

string

For buy orders: exact buyAmount desired

Validity Parameters (one of):

validTo

integer

Absolute unix timestamp expiration

validFor

integer

Relative validity duration in seconds

Optional Parameters:

receiver

address

Custom recipient for bought tokens

appData

string

Full appData JSON or hash

appDataHash

string

Hash to verify appData

sellTokenBalance

string

default:"erc20"

Token source: "erc20", "internal", or "external"

buyTokenBalance

string

default:"erc20"

Token destination: "erc20" or "internal"

priceQuality

string

default:"verified"

Quality level: "fast", "optimal", or "verified" (recommended)

signingScheme

string

default:"eip712"

Signature type: "eip712", "ethsign", "presign", or "eip1271"

onchainOrder

boolean

default:false

Whether order is for on-chain placement

timeout

integer

Custom timeout in milliseconds (capped to default)

Response

quote

object

Order parameters ready to sign and submit

Show Quote Response Fields

quote.sellToken

address

Token to sell

quote.buyToken

address

Token to buy

quote.sellAmount

string

Amount to sell in atoms

quote.buyAmount

string

Amount to buy in atoms

quote.validTo

integer

Expiration timestamp

quote.feeAmount

string

Estimated network fee in sellToken atoms

quote.gasAmount

string

Estimated gas units required

quote.gasPrice

string

Estimated gas price in Wei

quote.sellTokenPrice

string

Price of sellToken in native token atoms

from

address

Address for whom quote was computed

expiration

string

ISO 8601 UTC timestamp when quote expires

integer

Quote ID for linking to orders

verified

boolean

Whether quote was verified via simulation

protocolFeeBps

string

Protocol fee in basis points (e.g., “2” = 0.02%)

Status Codes:

200: Quote generated
400: Error quoting order (see PriceEstimationError)
404: No route found
422: Invalid JSON
429: Too many quote requests
500: Internal error

Price Estimation Error Types

Show PriceEstimationError Types

QuoteNotVerified: Quote couldn’t be verified
UnsupportedToken: Token not supported
NoLiquidity: No liquidity available for trade
UnsupportedOrderType: Order type not supported

Cancel Order(s)

curl -X DELETE "https://api.cow.fi/mainnet/api/v1/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "orderUids": [
      "0xff2e2e54d178997f173266817c1e9ed6fee1a1aae4b43971c53b543cffcc2969845c6f5599fbb25dbdd1b9b013daf85c03f3c63763e4bc4a"
    ],
    "signature": "0x...",
    "signingScheme": "eip712"
  }'

Cancels orders by marking them invalid. This is a best-effort cancellation and might not prevent solvers from settling if the order is in an in-flight settlement. Endpoints:

DELETE /api/v1/orders (multiple orders)
DELETE /api/v1/orders/{UID} (single order, deprecated)

Request Body

orderUids

array

Array of order UIDs to cancel (up to 128, only for multiple cancellation endpoint)

signature

string

required

EIP-712 signature of OrderCancellation(s) message

signingScheme

string

required

Signature scheme: "eip712" or "ethsign"

Status Codes:

200: Order(s) cancelled
400: Malformed signature
401: Invalid signature
404: Order(s) not found
422: Invalid JSON

Get Order Status

curl "https://api.cow.fi/mainnet/api/v1/orders/0xff2e2e54d178997f173266817c1e9ed6fee1a1aae4b43971c53b543cffcc2969845c6f5599fbb25dbdd1b9b013daf85c03f3c63763e4bc4a/status"

Returns the current status of an order with information about solver competition. Endpoint: GET /api/v1/orders/{UID}/status

Response

type

string

Status: "open", "scheduled", "active", "solved", "executing", "traded", or "cancelled"

value

array

List of solvers who proposed solutions, sorted by score ascending (last = winner)

Status Codes:

200: Status retrieved
400: Invalid order UID

Get Native Token Price

curl "https://api.cow.fi/mainnet/api/v1/token/0x6B175474E89094C44Da98b954EedeAC495271d0F/native_price"

Returns the native token price for a given token (e.g., how much ETH is needed to buy 1 atom of the token). Endpoint: GET /api/v1/token/{token}/native_price

Path Parameters

token

address

required

Token address

Response

price

number

Native token price (e.g., 0.0005 means 1 token = 0.0005 ETH)

Status Codes:

200: Price retrieved
400: Error finding price
404: No liquidity found
500: Unexpected error

Get Trades

curl "https://api.cow.fi/mainnet/api/v2/trades?owner=0x6810e776880c02933d47db1b9fc05908e5386b96&offset=0&limit=10"

Returns paginated trade data. Exactly one of owner or orderUid must be specified. Endpoint: GET /api/v2/trades

Query Parameters

owner

address

Filter by trader address

orderUid

string

Filter by order UID

offset

integer

default:"0"

Pagination offset

limit

integer

default:"10"

Results per page (min: 1, max: 1000)

Response

trades

array

Array of trade objects

Show Trade Fields

blockNumber

integer

Block in which trade occurred

logIndex

integer

Log index in the block

orderUid

string

Order UID matched by this trade

owner

address

Trader address

sellToken

address

Token sold

buyToken

address

Token bought

sellAmount

string

Amount sold including fees

sellAmountBeforeFees

string

Amount sold excluding fees

buyAmount

string

Amount bought

txHash

string

Settlement transaction hash

executedProtocolFees

array

List of protocol fees applied to this trade

Get Solver Competition

curl "https://api.cow.fi/mainnet/api/v2/solver_competition/12345"

Retrieves information about solver competition for a specific auction. Endpoints:

GET /api/v2/solver_competition/{auction_id}
GET /api/v2/solver_competition/by_tx_hash/{tx_hash}
GET /api/v2/solver_competition/latest

Response

auctionId

integer

Auction ID

auctionStartBlock

integer

Block where auction started

auctionDeadlineBlock

integer

Block deadline for settlement

transactionHashes

array

Winning settlement transaction hashes

referenceScores

object

Reference scores per solver (CIP-67)

auction

object

Auction data (orders, prices)

solutions

array

All submitted solutions with rankings

AppData Management

Get AppData

curl "https://api.cow.fi/mainnet/api/v1/app_data/0x0000000000000000000000000000000000000000000000000000000000000000"

Endpoint: GET /api/v1/app_data/{app_data_hash} Retrieves the full appData document for a given hash. Status Codes:

200: AppData found
400: Invalid hash
404: AppData not found

Register AppData

curl -X PUT "https://api.cow.fi/mainnet/api/v1/app_data/0x..." \
  -H "Content-Type: application/json" \
  -d '{"fullAppData": "{\"version\":\"0.9.0\",\"metadata\":{}}" }'

Endpoints:

PUT /api/v1/app_data/{app_data_hash} (specify hash)
PUT /api/v1/app_data (returns computed hash)

Registers full appData so orders can reference it by hash. Status Codes:

200: AppData already exists
201: AppData registered
400: Validation error
422: Invalid JSON
500: Storage error

Get Orders by Transaction Hash

curl "https://api.cow.fi/mainnet/api/v1/orders/tx/0xd51f28edffcaaa76be4a22f6375ad289272c037f3cc072345676e88d92ced8b5"

Retrieves all orders that were settled in a specific transaction. Endpoint: GET /api/v1/orders/tx/{txHash}

Path Parameters

txHash

string

required

Settlement transaction hash (32 bytes hex with 0x prefix)

Response

orders

array

Array of order objects that were included in the settlement transaction

Status Codes:

200: Orders retrieved
400: Invalid transaction hash

Get Current Batch Auction

curl "https://api.cow.fi/mainnet/api/v1/auction"

Returns the current batch auction that solvers should be solving. Includes solvable orders, block number, and token prices for objective value computation. Endpoint: GET /api/v1/auction

This endpoint is currently permissioned. Reach out in Discord if you need access for solver integration.

Response

integer

Auction ID

block

integer

Block number when the auction was created

orders

array

Array of solvable orders in the auction

prices

object

Token prices used for objective value computation

Status Codes:

200: Auction data retrieved
403: Unauthorized (permissioned endpoint)

Get User Total Surplus

curl "https://api.cow.fi/mainnet/api/v1/users/0x6810e776880c02933d47db1b9fc05908e5386b96/total_surplus"

Returns the total surplus (price improvement) earned by a user across all their trades. Endpoint: GET /api/v1/users/{address}/total_surplus

This endpoint is UNSTABLE and under active development. The response format may change.

Path Parameters

address

required

User’s Ethereum address

Response

totalSurplus

string

Total surplus earned in the native token (e.g., ETH)

numberOfTrades

integer

Total number of trades executed by this address

Status Codes:

200: Surplus data retrieved
400: Invalid address

Data Types

Address

20 byte Ethereum address encoded as hex with 0x prefix. Example: "0x6810e776880c02933d47db1b9fc05908e5386b96"

TokenAmount

Amount of an ERC20 token as 256-bit unsigned integer in decimal notation. Example: "1234567890"

UID

56 bytes order unique identifier encoded as hex with 0x prefix.

Bytes 0-32: Order digest
Bytes 32-52: Owner address
Bytes 52-56: Valid to timestamp (uint32)

Example: "0xff2e2e54d178997f173266817c1e9ed6fee1a1aae4b43971c53b543cffcc2969845c6f5599fbb25dbdd1b9b013daf85c03f3c63763e4bc4a"

TransactionHash

32 byte digest encoded as hex with 0x prefix. Example: "0xd51f28edffcaaa76be4a22f6375ad289272c037f3cc072345676e88d92ced8b5"

AppDataHash

32 bytes encoded as hex with 0x prefix (keccak256 hash of appData JSON string). Example: "0x0000000000000000000000000000000000000000000000000000000000000000"

Order Lifecycle

Quote: Request quote via POST /api/v1/quote
Sign: Sign the quoted order parameters using EIP-712
Submit: Create order via POST /api/v1/orders
Track: Monitor status via GET /api/v1/orders/{UID}/status
Query: Retrieve order details via GET /api/v1/orders/{UID}
Cancel (optional): Cancel via DELETE /api/v1/orders
Verify: Check trades via GET /api/v2/trades

Best Practices

Always use verified quotes: Set priceQuality: "verified" for production orders
Link quotes to orders: Include quoteId when creating orders for better analytics
Set reasonable validTo: Don’t make orders valid for too long (gas prices fluctuate)
Handle rate limits: Implement exponential backoff for 429 responses
Validate signatures: Use the from field to catch signature encoding errors early
Monitor order status: Poll status endpoint to track order through settlement
Use appData wisely: Follow the appData schema for interoperability

APIs

​Base URLs

​Production

​Staging

​Local Development

​Authentication

​Rate Limits

​Key Endpoints

​Create Order

​Request Body

​Response

​Error Types

​Get Order

​Path Parameters

​Response

​Get Orders by Account

​Path Parameters

​Query Parameters

​Response

​Get Quote

​Request Body

​Response

​Price Estimation Error Types

​Cancel Order(s)

​Request Body

​Get Order Status

​Response

​Get Native Token Price

​Path Parameters

​Response

​Get Trades

​Query Parameters

​Response

​Get Solver Competition

​Response

​AppData Management

​Get AppData

​Register AppData

​Get Orders by Transaction Hash

​Path Parameters

​Response

​Get Current Batch Auction

​Response

​Get User Total Surplus

​Path Parameters

​Response

​Data Types

​Address

​TokenAmount

​UID

​TransactionHash

​AppDataHash

​Order Lifecycle

​Best Practices

Build docs developers (and LLMs) love

Base URLs

Production

Staging

Local Development

Authentication

Rate Limits

Key Endpoints

Create Order

Request Body

Response

Error Types

Get Order

Path Parameters

Response

Get Orders by Account

Path Parameters

Query Parameters

Response

Get Quote

Request Body

Response

Price Estimation Error Types

Cancel Order(s)

Request Body

Get Order Status

Response

Get Native Token Price

Path Parameters

Response

Get Trades

Query Parameters

Response

Get Solver Competition

Response

AppData Management

Get AppData

Register AppData

Get Orders by Transaction Hash

Path Parameters

Response

Get Current Batch Auction

Response

Get User Total Surplus

Path Parameters

Response

Data Types

Address

TokenAmount

UID

TransactionHash

AppDataHash

Order Lifecycle

Best Practices