From cebe7d7c98427091614ef4c0c169f88b2848a393 Mon Sep 17 00:00:00 2001 From: squadgazzz Date: Mon, 29 Jun 2026 15:13:09 +0000 Subject: [PATCH 1/4] Document streaming quote API with per-network timeout guidance --- docs/cow-protocol/integrate/api.mdx | 38 ++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/cow-protocol/integrate/api.mdx b/docs/cow-protocol/integrate/api.mdx index 4ba6c817d..2329c98f3 100644 --- a/docs/cow-protocol/integrate/api.mdx +++ b/docs/cow-protocol/integrate/api.mdx @@ -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/` @@ -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 @@ -71,6 +73,39 @@ 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 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. + +```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" + }' +``` + +### Choosing a timeout + +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. + +Treat the values below as a starting point, not a guarantee. Measure against your own traffic, and raise the timeout for pairs that only slower solvers can price. Quote response times also differ by network. These are guidance as of 2026-06 and shift as solver performance changes. + +| 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: @@ -163,4 +198,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 \ No newline at end of file +- **[Order Signing Guide](../reference/core/signing_schemes.mdx)** - Cryptographic signing details + From 12ff40f150d76981696d0576ea1e122da196dcd3 Mon Sep 17 00:00:00 2001 From: squadgazzz Date: Tue, 30 Jun 2026 08:39:32 +0000 Subject: [PATCH 2/4] Address comments --- docs/cow-protocol/integrate/api.mdx | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/cow-protocol/integrate/api.mdx b/docs/cow-protocol/integrate/api.mdx index 2329c98f3..8ce1e6039 100644 --- a/docs/cow-protocol/integrate/api.mdx +++ b/docs/cow-protocol/integrate/api.mdx @@ -75,9 +75,12 @@ 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 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. +`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 you 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 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. +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. ```bash curl -N -X POST "https://api.cow.fi/mainnet/api/v1/quote/stream" \ @@ -94,11 +97,21 @@ curl -N -X POST "https://api.cow.fi/mainnet/api/v1/quote/stream" \ ### Choosing a timeout -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. +You receive each quote 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 quote you act on is only as good as the responses that arrived before you stopped reading, and the `timeout` sets that boundary. -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 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 leave you with a worse quote or none at all. +A longer timeout gives the competition time to find a better price. -Treat the values below as a starting point, not a guarantee. Measure against your own traffic, and raise the timeout for pairs that only slower solvers can price. Quote response times also differ by network. These are guidance as of 2026-06 and shift as solver performance changes. +You own this tradeoff. +Set `timeout` (milliseconds) on the request, or read events and close the connection once you have a good-enough quote. + +The table below is a starting point, not a guarantee. +Measure against your own traffic, and raise the timeout 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) | |---|---| From 85bd38bff1fa42d494584cf21246c0b3ef78e4ba Mon Sep 17 00:00:00 2001 From: squadgazzz Date: Tue, 30 Jun 2026 08:46:00 +0000 Subject: [PATCH 3/4] Phrasing --- docs/cow-protocol/integrate/api.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cow-protocol/integrate/api.mdx b/docs/cow-protocol/integrate/api.mdx index 8ce1e6039..8a0ac6ea8 100644 --- a/docs/cow-protocol/integrate/api.mdx +++ b/docs/cow-protocol/integrate/api.mdx @@ -76,10 +76,10 @@ 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 you can show a price as soon as the fastest solver responds instead of waiting for the whole competition. +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 you may receive fewer events than there are solvers. +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 @@ -97,20 +97,20 @@ curl -N -X POST "https://api.cow.fi/mainnet/api/v1/quote/stream" \ ### Choosing a timeout -You receive each quote as soon as its solver responds, so a usable price arrives faster than with `POST /api/v1/quote`, which waits for the whole competition. +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 quote you act on is only as good as the responses that arrived before you stopped reading, and the `timeout` sets that boundary. +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 leave you with a worse quote or none at all. +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. -You own this tradeoff. -Set `timeout` (milliseconds) on the request, or read events and close the connection once you have a good-enough quote. +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. The table below is a starting point, not a guarantee. -Measure against your own traffic, and raise the timeout for pairs that only slower solvers can price. +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) | From 2a881b6ac7c73aec41431fbb334b011c9a185c99 Mon Sep 17 00:00:00 2001 From: squadgazzz Date: Fri, 3 Jul 2026 11:06:57 +0000 Subject: [PATCH 4/4] docs: note streamed quote events carry a reusable quote id --- docs/cow-protocol/integrate/api.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cow-protocol/integrate/api.mdx b/docs/cow-protocol/integrate/api.mdx index 8a0ac6ea8..6695d204e 100644 --- a/docs/cow-protocol/integrate/api.mdx +++ b/docs/cow-protocol/integrate/api.mdx @@ -78,7 +78,8 @@ console.log('Order status:', orderDetails.status) `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`. +Each event's `data` is an `OrderQuoteResponse`, the same shape `POST /api/v1/quote` returns. +The `id` on each event can be passed as `quoteId` when placing an order, the same as a quote from `POST /api/v1/quote`. 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.