Build on top of CoW Protocol
This document provides some quick start information for integrating to CoW Protocol. You will find an introduction to the protocol, its tools, resources, and documentation, along with some convenient
🏁 Get started
What is CoW Swap & CoW Protocol
CoW Swap is a Decentralized Application (DApp) and Protocol allowing users to exchange digital assets directly (peer-to-peer) and via existing trading decentralized exchanges.
Its novel design maximizes trade efficiency and provides a competitive way to ensure best prices.
One of the core ideas is executing trades in batches, where users will trade directly using what is known as “Coincidence of Wants” (hence the name CoW). In the context of blockchains, batch auctions are a superior mechanism compared to continuous time trading, as they already execute transactions in discrete “blocks” every few seconds.
In consequence CoW Swap protects users from front-running and other value extraction (known as MEV). The mechanism also leverages the concept of “ring trades” to boost liquidity in highly fragmented and long-tail token markets.
Additionally, CoW Swap allows for an improved user experience by facilitating gasless trades, not paying for failed transactions and adaptive routing in case of volatility.
Get familiar with CoW Swap
CoW Swap uses CoW protocol. One easy way to get familiar with the protocol is by doing one trade in CowSwap:
You can use it in the Görli test net if you want. Otherwise, it is available in Mainnet and Gnosis Chain.
💡 If you need Görli Ether, you can use this PoW-based Faucet. You can also ask us!
Some basics: Place an order
Trading in CoW Swap is done by signing off-chain transactions using your web3 wallet and posting them to an API.
You will need to:
Enable token for trading: (only one time) Similarly to other protocols like Uniswap, you need to set an allowance. After this, you can trade. Learn more here
Get a price/fee quote from the API: Fees are only paid if the trade is executed (you don’t pay for failed transactions). So this fee covers the settlement of the transaction on-chain. Learn more here
Sign the order using your wallet: Orders are just your signed intent to trade at a desired price or better before some expiration time. You sign orders with your web3 wallet. Learn more here
Post the signed order to the API: Signed orders are posted to the API, so the order can be executed. Read more here
💡 TIP: One easy way to understand the steps above is to see the DEMO: SDK Examples or check the SDK documents
Check order status
Orders are identified by an unique identifier (UID).
This UID is a deterministic hash derived from the order information. It is returned by the API when you post a new order (it can also be calculated locally deriving it from the order data).
This UID would allow you to get information about the status of the order. You can do this in two different ways:
API: Get the order details and its status from the UID (GET /orders/{UID}, see the Swagger docs)
Smart Contract: You can watch the Trade event.
It’s worth mentioning that, if you build a tool or UI that creates trades, it’s very convenient to provide the user a way to see the details of the trade that was just created. One simple way to do this, is by creating a link to the explorer:
https://explorer.cow.fi/orders/{UID}
CoW Explorer
The explorer is a website that allows you to explore the protocol data.
It’s the “Etherscan” for CoW protocol, so you will be able to find, among other things:
Order details, with trading status: You can get detailed information about executed, expired, or pending orders. This page is very convenient for directing users once they post an order (example order)
Order for a given account: You can get detailed information about executed, expired, or pending orders for a given trader (example orders for trader)
Orders for a batch: Given the transaction hash of a settlement, you can see all the trades in it (example orders in batch)
Signing orders
The protocol requires valid signed orders. There’s different ways in which someone could sign an order:
Off-chain signing (EIP-712): Allow gass-less trading for EOA like Metamask. Learn how to sign orders
Presign: Sign an order using an ethereum transaction. Convenient for Smart Contract integrations. See the setPresign solidity function for more details
Smart Contract Signing (EIP-1271): Gass-less signing for smart contracts. Here is a tutorial on how to use this type of signatures.
For more information on Signed orders, read here.
💡Resources
Dev Documentation
Start here your journey to learn about CoW Protocol
API
The API allows you to get direct access to the CoW protocol.
The documentation is exposed using Swagger docs:
The API is available in 3 different Networks: Mainnet, Gnosis Chain and Görli testnet.
For more information about the API, learn more here
SDK
The software development kit (SDK) is a Javascript library that provides tooling for accessing the API as well as some utilities like functions for order signing.
It is written in Typescript, making it simpler to use in both a Typescript or a plain Javascript project.
More info in SDK documents or see an example on how to use it here
The graph
CoW Protocol graph provides an alternative way to consume protocol information.
More info in https://github.com/cowprotocol/subgraph
Examples of simple integrations
CoW Protocol integration examples: Web app that shows how to integrate with CoW Protocol using the SDK https://github.com/anxolin/cow-examples
NodeJS Trading Bot: Basic bot that creates a random trade: https://github.com/cowprotocol/trading-bot
Python Trading script: https://pastebin.com/cKXUz0SW
Go Trading script: https://pastebin.com/r787C2wT
👩🌾 Bonus: Join the team!
There’s currently open positions for CoW Protocol.
If you are looking for new challenges and opportunities, consider our Open Positions.
\
Last updated