Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 37 additions & 1 deletion docs/cow-protocol/integrate/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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/`
Expand All @@ -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
Expand Down Expand Up @@ -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.

Copy link
Copy Markdown
Contributor

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?

Copy link
Copy Markdown
Contributor Author

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.


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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The 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 /quote

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How were those numbers computed?
They seem pretty reasonable but would be nice if you could provide some script, claude conversation or metrics that you used to pick those numbers.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


## Network Endpoints

CoW Protocol APIs are available on multiple networks:
Expand Down Expand Up @@ -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

Loading