Skip to content

Document streaming quote API with per-network timeout guidance #638

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
squadgazzz wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Document streaming quote API with per-network timeout guidance #638

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cebe7d7
Document streaming quote API with per-network timeout guidance
squadgazzz Jun 29, 2026
12ff40f
Address comments
squadgazzz Jun 30, 2026
85bd38b
Phrasing
squadgazzz Jun 30, 2026
2a881b6
docs: note streamed quote events carry a reusable quote id
squadgazzz Jul 3, 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
51 changes: 50 additions & 1 deletion docs/cow-protocol/integrate/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ The API integration allows you to interact with CoW Protocol at the lowest level
## Key APIs

### Order Book API

The primary API for creating and managing orders on CoW Protocol.

- **Base URL**: `https://api.cow.fi/`
Expand All @@ -18,6 +19,7 @@ The primary API for creating and managing orders on CoW Protocol.
### Key Endpoints

- `POST /api/v1/quote` - Get trading quotes
- `POST /api/v1/quote/stream` - Stream quotes from individual solvers as they arrive (SSE)
- `POST /api/v1/orders` - Submit signed orders
- `GET /api/v1/orders/{uid}` - Get order details
- `DELETE /api/v1/orders/{uid}` - Cancel orders
Expand Down Expand Up @@ -71,6 +73,52 @@ const orderDetails = await orderResponse.json()
console.log('Order status:', orderDetails.status)
```

## Streaming Quotes

`POST /api/v1/quote/stream` takes the same request body as `POST /api/v1/quote`, but returns a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream instead of a single response.
Each solver's quote arrives as its own event, so the client can show a price as soon as the fastest solver responds instead of waiting for the whole competition.

Each event's `data` is an `OrderQuoteResponse`, the same shape `POST /api/v1/quote` returns, with `id` set to `null`.
Solvers without a quote send nothing, so the stream may contain fewer events than there are solvers.
If no solver returns a usable quote, the server sends a final `error` event with a `NoLiquidity` body, then closes.

```bash
curl -N -X POST "https://api.cow.fi/mainnet/api/v1/quote/stream" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"sellToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"sellAmountBeforeFee": "1000000000000000000",
"kind": "sell",
"from": "0xYourWalletAddress"

@alfetopito alfetopito Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Would be useful to add the timeout in the example, as otherwise this behaves like a regular quote, no?

@squadgazzz squadgazzz Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

It doesn't behave as a regular quote in any case. The events are coming as solvers respond.

}'
```

### Choosing a timeout

Each quote is delivered as soon as its solver responds, so a usable price arrives faster than with `POST /api/v1/quote`, which waits for the whole competition.
Streaming does not make any solver compute faster, though.
The final quote is only as good as the responses that arrived before the stream was closed, and the `timeout` sets that boundary.

The stream stays open until the request `timeout` elapses or every solver has responded.
Slower solvers sometimes return a better price, especially on thin or unusual pairs that only one or two solvers can quote.
A short timeout returns sooner, but it can yield a worse quote or none at all.
A longer timeout gives the competition time to find a better price.

This tradeoff is controlled by the client through the `timeout`.
The value is set (in milliseconds) on the request, or the connection is closed once a good-enough quote has arrived.

Comment on lines +100 to +112

@coderabbitai coderabbitai Bot Jul 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n### Target file context\n'
nl -ba docs/cow-protocol/integrate/api.mdx | sed -n '92,120p'

printf '\n### Search for relevant phrases\n'
rg -n --hidden -S "good-enough|good enough|close.*quote|timeout.*responded|solver has responded|stream stays open|stream" docs . 2>/dev/null | sed -n '1,200p'

Repository: cowprotocol/docs

Length of output: 219

🌐 Web query:

"good-enough quote" CoW Protocol stream timeout quote

💡 Result:

In CoW Protocol, the term "good-enough quote" refers to a mechanism associated with the streaming quote API (SSE endpoint /api/v1/quote/stream) [1]. This API allows latency-sensitive integrators to receive partial quote responses as individual solvers reply, rather than waiting for the entire auction competition to conclude [1]. Integrators can monitor these streamed events and choose to stop (e.g., by disconnecting or proceeding to order placement) as soon as they have received a quote they consider "good-enough," even if the full timeout for the auction has not yet elapsed [1][2]. This approach aims to reduce user wait times by enabling faster decision-making once a competitive price estimate is identified [1][2]. Key technical aspects include: - Streamed Quotes: The /api/v1/quote/stream endpoint returns events shaped like OrderQuoteResponse [1]. - No Change to Quote Quality: The mechanism does not inherently change the quality of the quotes provided, only the timing of their delivery [1]. - Timeout Interaction: The stream naturally closes when all solvers have responded or when the existing quote timeout fires [1]. - Persistence: To support this flow, quote candidates are persisted before being sent in the stream, ensuring they can be retrieved if the client decides to place an order based on a previously received "good-enough" quote [2]. This functionality complements standard quoting methods, where "Fast" quotes (returning after a threshold of solvers, typically two) and "Optimal" quotes (waiting for all solvers or a full 5s timeout) are used for different user experience requirements [3][4][5][6].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n### Target file context\n'
awk 'NR>=96 && NR<=116 {printf "%5d  %s\n", NR, $0}' docs/cow-protocol/integrate/api.mdx

printf '\n### Search for exact phrase in repo\n'
grep -RIn --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build "good-enough quote" docs . 2>/dev/null | sed -n '1,80p'

Repository: cowprotocol/docs

Length of output: 1890

Clarify who closes the stream here. “Good-enough quote” reads like an extra server close condition, but it’s really the client’s decision to stop listening. Reword this to avoid implying the stream itself ends early for that reason.

🧰 Tools
🪛 LanguageTool

[style] ~107-~107: ‘none at all’ might be wordy. Consider a shorter alternative.
Context: ...oner, but it can yield a worse quote or none at all. A longer timeout gives the competition...

(EN_WORDINESS_PREMIUM_NONE_AT_ALL)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/cow-protocol/integrate/api.mdx` around lines 100 - 112, The streaming
quote description currently implies the stream can end early because a
“good-enough quote” is reached, which is misleading. Reword the explanation
around the timeout behavior in the integrate/api.mdx section so it clearly
states that the client may stop listening after receiving an acceptable quote,
while the server stream itself ends only when the request timeout elapses or all
solvers respond. Keep the phrasing aligned with the existing `POST
/api/v1/quote` comparison and the `timeout` explanation.

The table below is a starting point, not a guarantee.
The values should be measured against real traffic and raised for pairs that only slower solvers can price.
Response times also differ by network, and these values shift as solver performance changes (guidance as of 2026-06).

| Network | `timeout` (ms) |
|---|---|
| Base, Gnosis Chain, Linea | 1000 |
| Mainnet, BNB Chain | 1800 |
| Arbitrum, Polygon, Avalanche, Ink | 2500 |

## Network Endpoints

CoW Protocol APIs are available on multiple networks:
Expand Down Expand Up @@ -163,4 +211,5 @@ For complete API documentation including all endpoints, parameters, and response
- **[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
- **[Order Signing Guide](../reference/core/signing_schemes.mdx)** - Cryptographic signing details
- **[Order Signing Guide](../reference/core/signing_schemes.mdx)** - Cryptographic signing details

Loading