diff --git a/docs/cow-protocol/integrate/api.mdx b/docs/cow-protocol/integrate/api.mdx index 4ba6c817d..6695d204e 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,53 @@ 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. +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. + +```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 + +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. + +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: @@ -163,4 +212,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 +