cow-protocol-sdk

# cow-protocol-sdk USE FOR: - "CoW Protocol / CoW Swap integration" - "MEV-protected DeFi trading" - "intent-based DEX order" - "TWAP on-chain order" - "limit order on DEX (crypto)" - "cross-chain swap / bridge" - "batch auction solver trading" - "TypeScript DeFi trading SDK" tags: [CoW-Protocol, DeFi, DEX, MEV-protection, TWAP, limit-order, intent-based, Ethereum, TypeScript, solver, batch-auction] kind: sdk category: crypto-defi-trading --- ## What Is CoW Protocol? Intent-based trading protocol with MEV protection via batch auctions and solver network. - Repo: https://github.com/cowprotocol/cow-sdk - Docs: docs.cow.fi - Interface: swap.cow.fi (CoW Swap) - Model: **Coincidence of Wants** — direct peer-to-peer matching when possible ### How CoW Works ``` User submits signed intent (not on-chain tx) ↓ Solver network competes to find best execution: Option A: CoW match → peer-to-peer, no AMM needed (best price) Option B: AMM route → Uniswap/Curve/etc. (fallback) Option C: Aggregator → 1inch/Paraswap route ↓ Best solver wins batch auction → executes on-chain User gets guaranteed price or better (surplus → user) ``` **MEV Protection**: Orders are signed intents, not on-chain txs → front-running impossible. **Surplus**: Any price improvement beyond quoted amount goes back to the user. --- ## Supported Networks Ethereum · BNB Chain · Gnosis Chain · Polygon · Base · Arbitrum One · Avalanche · Linea · Ink · Sepolia (testnet) --- ## Package Architecture (14 packages) | Package | Purpose | |---------|---------| | `@cowprotocol/cow-sdk` | Main entry point (re-exports all) | | `@cowprotocol/sdk-trading` | High-level: quote → sign → post | | `@cowprotocol/sdk-order-book` | OrderBook API client (get/post orders) | | `@cowprotocol/sdk-order-signing` | Cryptographic signing utilities | | `@cowprotocol/sdk-composable` | Programmatic orders: TWAP, conditional | | `@cowprotocol/sdk-bridging` | Cross-chain token transfers | | `@cowprotocol/sdk-cow-shed` | Account abstraction support | | `@cowprotocol/sdk-viem-adapter` | Viem provider adapter | | `@cowprotocol/sdk-ethers-v6-adapter` | Ethers v6 adapter | | `@cowprotocol/sdk-ethers-v5-adapter` | Ethers v5 adapter | | `@cowprotocol/sdk-app-data` | Order metadata / app data | | `@cowprotocol/sdk-config` | Chain/environment config | | `@cowprotocol/sdk-contracts-ts` | Type-safe contract ABIs | | `@cowprotocol/sdk-subgraph` | GraphQL subgraph queries | --- ## Installation ```bash npm install @cowprotocol/cow-sdk # or pnpm add @cowprotocol/cow-sdk ``` --- ## Core Usage: Quote → Sign → Post ```typescript import { TradingSdk, SupportedChainId, OrderKind } from "@cowprotocol/cow-sdk" import { createWalletClient, http } from "viem" import { privateKeyToAccount } from "viem/accounts" import { mainnet } from "viem/chains" // Setup const account = privateKeyToAccount("0x...") const walletClient = createWalletClient({ account, chain: mainnet, transport: http() }) const sdk = new TradingSdk({ chainId: SupportedChainId.MAINNET, signer: walletClient, }) // 1. Get quote const quote = await sdk.getQuote({ kind: OrderKind.SELL, sellToken: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH buyToken: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI amount: "1000000000000000000", // 1 WETH (18 decimals) }) console.log(`Quote: sell 1 WETH → get ${quote.buyAmount} DAI`) // 2. Post order (sign + submit in one step) const orderId = await sdk.postSwapOrder({ ...quote, slippageBps: 50, // 0.5% slippage tolerance }) console.log(`Order posted: ${orderId}`) // Track at: https://explorer.cow.fi/orders/${orderId} ``` --- ## Order Types ### Market Order (Swap) ```typescript // Execute immediately at best available price const orderId = await sdk.postSwapOrder({ kind: OrderKind.SELL, sellToken: WETH, buyToken: DAI, amount: parseEther("1"), slippageBps: 50, }) ``` ### Limit Order ```typescript // Execute only when price reaches target const orderId = await sdk.postLimitOrder({ kind: OrderKind.SELL, sellToken: WETH, buyToken: DAI, sellAmount: parseEther("1"), buyAmount: parseUnits("3200", 18), // Only fill if 1 WETH ≥ 3200 DAI validTo: Math.floor(Date.now() / 1000) + 86400, // expires in 24h }) ``` ### TWAP (Time-Weighted Average Price) ```typescript import { buildTWAPOrder } from "@cowprotocol/sdk-composable" // Split 10 WETH into 10 parts over 24 hours const twapOrder = buildTWAPOrder({ sellToken: WETH, buyToken: DAI, totalSellAmount: parseEther("10"), numberOfParts: 10, timeBetweenParts: 2 * 60 * 60, // every 2 hours span: 0, // execute anytime within each window }) const orderId = await sdk.postComposableOrder(twapOrder) ``` --- ## OrderBook API (Direct) ```typescript import { OrderBookApi, SupportedChainId } from "@cowprotocol/cow-sdk" const orderBook = new OrderBookApi({ chainId: SupportedChainId.MAINNET }) // Get all open orders for a wallet const orders = await orderBook.getOrders({ owner: "0x..." }) // Get order status const order = await orderBook.getOrder(orderId) console.log(order.status) // "open" | "fulfilled" | "cancelled" | "expired" // Cancel an order await orderBook.cancelOrder(orderId, signature) ``` --- ## Cross-Chain Bridging ```typescript import { BridgingSdk } from "@cowprotocol/sdk-bridging" const bridge = new BridgingSdk({ chainId: SupportedChainId.MAINNET }) // Bridge USDC from Ethereum → Arbitrum const bridgeOrder = await bridge.postBridgeOrder({ sellToken: USDC_MAINNET, buyToken: USDC_ARBITRUM, amount: parseUnits("1000", 6), targetChainId: SupportedChainId.ARBITRUM_ONE, }) ``` --- ## Key Advantages Over Standard DEX Aggregators | Feature | CoW Protocol | 1inch / Paraswap | |---------|-------------|-----------------| | MEV Protection | ✓ (signed intents) | ✗ (on-chain txs) | | Surplus to user | ✓ (price improvement) | ✗ (keeper keeps it) | | Peer-to-peer matching | ✓ (CoW mechanism) | ✗ | | TWAP orders | ✓ (composable) | Limited | | Limit orders | ✓ | ✓ | | Gas costs | Lower (batched) | Standard | ---