Skip to content

docs: add quote-to-order tutorial with slippage guidance #587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
data-cowwboy wants to merge 11 commits into
base: main
Choose a base branch
from
Open

docs: add quote-to-order tutorial with slippage guidance #587

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
a1568eb
docs: add quote-to-order tutorial with slippage guidance
data-cowwboy Jan 22, 2026
3552895
fixes
harisang Jan 29, 2026
62eb315
Remove space
harisang Jan 29, 2026
28408c5
more fixes
harisang Jan 29, 2026
2a0a984
more fixes
harisang Jan 29, 2026
40e1ff4
small fixes
harisang Jan 29, 2026
a5f5551
more fixes
harisang Jan 29, 2026
437cf4c
rephrasings
harisang Jan 29, 2026
1d339d2
fix typo
harisang Jan 29, 2026
6fa8ff3
add zero fee
harisang Jan 29, 2026
58fd8c0
docs: address PR review feedback for quote-to-order tutorial
data-cowwboy Feb 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions docs/cow-protocol/integrate/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The primary API for creating and managing orders on CoW Protocol.
- `POST /api/v1/orders` - Submit signed orders
- `GET /api/v1/orders/{uid}` - Get order details
- `DELETE /api/v1/orders/{uid}` - Cancel orders
- `GET /api/v1/trades` - Get trade history
- `GET /api/v2/trades` - Get trade history

## Quick Start Example

Expand All @@ -31,22 +31,31 @@ The primary API for creating and managing orders on CoW Protocol.
curl -X POST "https://api.cow.fi/mainnet/api/v1/quote" \
-H "Content-Type: application/json" \
-d '{
"sellToken": "0xA0b86a33E6411Ec5d0b9dd2E7dC15A9CAA6C1F8e",
"sellToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"buyToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"sellAmountBeforeFee": "1000000",
"sellAmountBeforeFee": "1000000000",
"kind": "sell",
"from": "0xYourWalletAddress"
}'
```

### 2. Sign and Submit Order
### 2. Apply Slippage and Sign Order

:::caution Important
Before signing, you should apply slippage tolerance to protect against price movements. See the [Quote to Order Tutorial](../tutorials/quote-to-order.mdx) for detailed examples.
:::

```javascript
// After getting a quote, sign the order
// Apply slippage to the quote before signing
// For sell orders: reduce buyAmount by slippage (e.g., 0.5%)
const buyAmountWithSlippage = BigInt(quoteResponse.quote.buyAmount) * 995n / 1000n
const sellAmount = BigInt(quoteResponse.quote.sellAmount) + BigInt(quoteResponse.quote.feeAmount)

// Build order for signing
const order = {
...quoteResponse,
signature: await signOrder(quoteResponse, signer),
signingScheme: "eip712"
...quoteResponse.quote,
sellAmount: sellAmount.toString(),
buyAmount: buyAmountWithSlippage.toString(),
}
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

cat -n docs/cow-protocol/integrate/api.mdx | sed -n '40,70p'

Repository: cowprotocol/docs

Length of output: 1243

🏁 Script executed:

rg -i "feeAmount|fee.*amount" docs/ -A 2 -B 2 --max-count=20

Repository: cowprotocol/docs

Length of output: 27326

🏁 Script executed:

rg "sellAmount.*feeAmount|feeAmount.*sellAmount" docs/ -B 3 -A 3 --max-count=10

Repository: cowprotocol/docs

Length of output: 644

Fix syntax error on line 61 and correct feeAmount handling.

The code on line 61 has a syntax error (const signature = signature: await signOrder(...)) with a duplicate assignment operator. Additionally, line 52 incorrectly adds feeAmount to sellAmount; feeAmount should remain as a separate field in the order object, as defined in the CoW Protocol order schema. Remove the feeAmount addition and pass it as a distinct field:

Corrected code 
const buyAmountWithSlippage = BigInt(quoteResponse.quote.buyAmount) * 995n / 1000n
-const sellAmount = BigInt(quoteResponse.quote.sellAmount) + BigInt(quoteResponse.quote.feeAmount)

// Build order for signing
const order = {
  ...quoteResponse.quote,
-  sellAmount: sellAmount.toString(),
+  sellAmount: quoteResponse.quote.sellAmount,
   buyAmount: buyAmountWithSlippage.toString()
 }

-const signature = signature: await signOrder(quoteResponse, signer)
+const signature = await signOrder(order, signer)

const signedOrder = {
   ...order,
   signature: signature,
   signingScheme: "eip712"
 }
🤖 Prompt for AI Agents 
In `@docs/cow-protocol/integrate/api.mdx` around lines 49 - 59, The code has a
syntax error in the signature assignment and incorrectly mutates sellAmount by
adding feeAmount; fix by removing the addition of feeAmount to sellAmount (keep
feeAmount as its own field on the order built from quoteResponse.quote) and
ensure buyAmountWithSlippage and sellAmount are converted to strings when
creating the order object (refer to buyAmountWithSlippage, sellAmount,
quoteResponse.quote, order). Then correct the signature line to use a proper
assignment calling signOrder and awaiting the result (refer to signOrder and
signature) so it reads like a normal await assignment rather than a duplicate
operator.


// Submit the signed order
Expand Down Expand Up @@ -155,11 +164,13 @@ try {

For complete API documentation including all endpoints, parameters, and response schemas, see:

- **[Quote to Order Tutorial](../tutorials/quote-to-order.mdx)** - Step-by-step guide with slippage handling
- **[Order Book API Reference](/cow-protocol/reference/apis/orderbook)** - Complete endpoint documentation
- **[API Documentation](https://api.cow.fi/docs/)** - Interactive API explorer

## Resources

- **[Quote to Order Tutorial](../tutorials/quote-to-order.mdx)** - Complete guide with slippage handling
- **[Order Book API Reference](/cow-protocol/reference/apis/orderbook)** - Detailed API documentation
- **[API Explorer](https://api.cow.fi/docs/)** - Interactive documentation
- **[GitHub Examples](https://github.com/cowprotocol/cow-sdk/tree/main/examples)** - Code examples
Expand Down
Loading