Document streaming quote API with per-network timeout guidance by squadgazzz · Pull Request #638 · cowprotocol/docs

squadgazzz · 2026-06-29T15:14:28Z

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 the timeout, 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

Added POST /api/v1/quote/stream to the Key Endpoints list
Added a "Streaming Quotes" section covering SSE behavior, event shape, a curl example, and timeout guidance with per-network suggestions

Summary by CodeRabbit

Documentation
- Added guidance for streaming quotes through the API, including the new POST /api/v1/quote/stream endpoint.
- Documented the SSE response model and how quote events (or absence of events) are delivered.
- Included timeout recommendations to help control how long the stream stays open and how many solver quotes may arrive.
- Updated the resources section with an Order Signing Guide link and made minor formatting improvements.

vercel · 2026-06-29T15:14:34Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Jun 30, 2026 8:46am

coderabbitai · 2026-06-29T15:14:44Z

Warning

Review limit reached

@squadgazzz, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 53 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ebd68567-7f0d-4211-8fb1-0a1b7104a707

📥 Commits

Reviewing files that changed from the base of the PR and between 12ff40f and 85bd38b.

📒 Files selected for processing (1)

docs/cow-protocol/integrate/api.mdx

📝 Walkthrough

Walkthrough

Documentation for the CoW Protocol API integration page adds the POST /api/v1/quote/stream SSE endpoint, a new “Streaming Quotes” section with event semantics and timeout guidance, and an Order Signing Guide link in Resources.

Changes

API Integration Docs

Layer / File(s)	Summary
Streaming quotes docs update `docs/cow-protocol/integrate/api.mdx`	Adds `POST /api/v1/quote/stream` to Key Endpoints, documents SSE event semantics and timeout guidance, updates Resources with Order Signing Guide, and includes a minor formatting change.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐇 Hop hop, the docs now stream,
Quotes arrive in an SSE beam.
Timeouts, links, and notes set bright,
Rabbit-approved and tidy tonight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the streaming quote API docs update and the per-network timeout guidance.
Description check	✅ Passed	The description includes the required purpose and changes sections and sufficiently explains the new streaming quote docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch streaming-quote-api

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

fleupold

Generally, for markdown PRs it's suggested to use a single line per sentence, so that updates later create cleaner diffs.

fleupold · 2026-06-30T08:09:39Z

+
+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.


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

Rephrased a bit.

fleupold · 2026-06-30T08:10:14Z

+
+`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.


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?

alfetopito · 2026-06-30T08:52:37Z

+    "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    "sellAmountBeforeFee": "1000000000000000000",
+    "kind": "sell",
+    "from": "0xYourWalletAddress"


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

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

pretf00d

looks good

Document streaming quote API with per-network timeout guidance

cebe7d7

squadgazzz requested a review from a team as a code owner June 29, 2026 15:14

vercel Bot deployed to Preview June 29, 2026 15:14 View deployment

fleupold reviewed Jun 30, 2026

View reviewed changes

Address comments

12ff40f

vercel Bot deployed to Preview June 30, 2026 08:40 View deployment

Phrasing

85bd38b

vercel Bot deployed to Preview June 30, 2026 08:46 View deployment

alfetopito reviewed Jun 30, 2026

View reviewed changes

pretf00d approved these changes Jun 30, 2026

View reviewed changes

fleupold mentioned this pull request Jun 30, 2026

Persist streamed quotes cowprotocol/services#4579

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

Document streaming quote API with per-network timeout guidance#638
squadgazzz wants to merge 3 commits into
mainfrom
streaming-quote-api

squadgazzz commented Jun 29, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

fleupold left a comment

Uh oh!

fleupold Jun 30, 2026

Uh oh!

squadgazzz Jun 30, 2026

Uh oh!

fleupold Jun 30, 2026

Uh oh!

alfetopito Jun 30, 2026

Uh oh!

squadgazzz Jun 30, 2026

Uh oh!

pretf00d left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		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.


		`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.

Uh oh!

Conversation

squadgazzz commented Jun 29, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Summary by CodeRabbit

Summary by CodeRabbit

Uh oh!

vercel Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

fleupold left a comment

Choose a reason for hiding this comment

Uh oh!

fleupold Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

squadgazzz Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

fleupold Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

alfetopito Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

squadgazzz Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

pretf00d left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

squadgazzz commented Jun 29, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Jun 29, 2026 •

edited

Loading

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading