Document streaming quote API with per-network timeout guidance#638
Document streaming quote API with per-network timeout guidance#638squadgazzz wants to merge 4 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughDocumentation for the CoW Protocol API integration page adds the ChangesAPI Integration Docs
Estimated code review effort: 1 (Trivial) | ~5 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
fleupold
left a comment
fleupold
left a comment
There was a problem hiding this comment.
Generally, for markdown PRs it's suggested to use a single line per sentence, so that updates later create cleaner diffs.
|
|
||
| The client side owns this decision. The stream stays open until the request `timeout` elapses, or every solver has responded, so the value you set determines both how long you wait and which quotes you see. Set `timeout` (milliseconds) on the request, or close the connection yourself once you have a good-enough quote. | ||
|
|
||
| Streaming delivers quotes as they arrive, but it doesn't make any solver respond faster, so it isn't simply a quicker `/quote`. How much a short timeout helps depends on the pair: fast solvers cover liquid pairs in a few hundred milliseconds, while a thinner pair might rely on a single slower solver that a tight timeout would miss. It's worth tuning the value to the pairs you serve. |
There was a problem hiding this comment.
The first sentence is weird. We are marketing it as a faster quote precisely because before the request takes as long as the slowest solver would take, whereas now you can show quotes as soon as the fastest solver responds. So it is a faster version of /quote
There was a problem hiding this comment.
Rephrased a bit.
|
|
||
| `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 one response. Each solver's quote arrives as its own event, so you can show prices as they come in instead of waiting for the slowest solver. | ||
|
|
||
| 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 you may receive 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. |
There was a problem hiding this comment.
It's weird that we don't return a quote id. How are integrators supposed to use these quotes when placing orders if they don't have an ID?
There was a problem hiding this comment.
Updated since your PR was merged and will be a part of the next weekly release.
| "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", | ||
| "sellAmountBeforeFee": "1000000000000000000", | ||
| "kind": "sell", | ||
| "from": "0xYourWalletAddress" |
There was a problem hiding this comment.
Would be useful to add the timeout in the example, as otherwise this behaves like a regular quote, no?
There was a problem hiding this comment.
It doesn't behave as a regular quote in any case. The events are coming as solvers respond.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/cow-protocol/integrate/api.mdx`:
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0e626237-8071-4c32-a9b8-4ad281e2fe43
📒 Files selected for processing (1)
docs/cow-protocol/integrate/api.mdx
|
|
||
| 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. | ||
|
|
There was a problem hiding this comment.
🎯 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:
- 1: Streaming quote API (SSE) - v1 services#4456
- 2: Persist streamed quotes services#4579
- 3: https://github.com/cowprotocol/services/blob/main/docs/COW_ORDER_DEBUG_SKILL.md
- 4: https://docs.cow.fi/cow-protocol/tutorials/arbitrate/orderbook
- 5: https://docs.cow.bleu.builders/cow-protocol/explanation/architecture/orderbook
- 6: https://cowswap.mintlify.app/cow-protocol/explanation/architecture/orderbook
🏁 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.
4 participants
Description
The new streaming quote endpoint (
POST /api/v1/quote/stream) needs to be covered with docs. Integrators need to know it streams per-solver quotes over SSE, that they control thetimeout, and that it is not simply a faster/quote: on a thin pair that only a slow solver can price, a short timeout drops that quote.Changes
POST /api/v1/quote/streamto the Key Endpoints listSummary by CodeRabbit
Summary by CodeRabbit
POST /api/v1/quote/streamendpoint.errorevent is emitted.