-
Notifications
You must be signed in to change notification settings - Fork 30
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.
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
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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" | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
|
||
| 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. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Rephrased a bit. |
||
|
|
||
| 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 | | ||
|
Comment on lines
+117
to
+121
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. How were those numbers computed?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The relevant Slack thread is here: https://nomevlabs.slack.com/archives/C0BCANH39SM/p1782725824849949?thread_ts=1782138814.761399&cid=C0BCANH39SM IIRC, there is no single query. |
||
|
|
||
| ## 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 | ||
| - **[Order Signing Guide](../reference/core/signing_schemes.mdx)** - Cryptographic signing details | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated since your PR was merged and will be a part of the next weekly release.