> For the complete documentation index, see [llms.txt](https://docs.metric.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metric.xyz/reference/api/retrieve-batch-bid-and-ask.md). # Retrieve pool batch bid and ask `POST /public/v1/evm/{chain_id}/bid_ask/batch` Returns the [bid and ask](/reference/api/retrieve-current-bid-and-ask.md) for up to 100 pools on one chain in a single request. Use it to scan or rank many pools, for example by depth, without sending one request per pool. Each pool gets exactly the quote that `GET /public/v1/evm/{chain_id}/{pool_address}/bid_ask` returns for it, and the two endpoints share a cache, so a pool quoted by one is served to the other from cache. This is a public endpoint. Its rate limit is lower than the single-pool endpoint's, since one request quotes up to 100 pools. A Trading API key is optional; sending one raises your rate limit: ```http Authorization: Bearer ``` A key you send must be valid: an unknown key returns `401`. Leave the header out if you don't have one. ### Path parameters | Name | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------- | | `chain_id` | integer | EVM chain ID, e.g. `1`. Must be one of the chains returned by `GET /public/v1/chains`. | ### Request body | Name | Type | Required | Default | Description | | ------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pools` | address\[] | Yes | | 1 to 100 pool addresses, as returned by `GET /public/v1/evm/{chain_id}/metadata`. Case-insensitive. An address listed more than once is quoted once. | | `depth` | boolean | No | `true` | `false` returns `"depth": null` for every pool, as the single-pool `depth` parameter does (see [Unavailable prices](/reference/api/retrieve-current-bid-and-ask.md#unavailable-prices)). | Any other field is rejected with `400`. ### Request ```bash curl -X POST "https://api.metric.xyz/public/v1/evm/1/bid_ask/batch" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "pools": [ "0xF85AfbADeCC7F23Dd173ed706f07d9C7e2473e24", "0x0000000000000000000000000000000000000001" ], "depth": false }' ``` ### Response `200 OK`. `results` holds one entry per distinct pool, in the order you listed them. Each entry carries either a `quote` or an `error`, never both. ```json { "results": [ { "poolAddress": "0xF85AfbADeCC7F23Dd173ed706f07d9C7e2473e24", "quote": { "pair": "WETH/USDC", "poolAddress": "0xF85AfbADeCC7F23Dd173ed706f07d9C7e2473e24", "priceProviderStatus": "healthy", "bidAdj": "49940417631045696435290", "askAdj": "49945012360825322506424", "totalToken0Available": "24503618827789131821", "totalToken1Available": "49785157539", "serverTs": 1790508850, "depth": null } }, { "poolAddress": "0x0000000000000000000000000000000000000001", "error": { "status": 404, "error": "Pair metadata not found for 0x0000000000000000000000000000000000000001" } } ] } ``` ### Response fields | Field | Type | Description | | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `results` | array | One entry per distinct requested pool, in request order. A repeated address appears once, at its first position. | | `results[].poolAddress` | address | The pool address as you spelled it in the request. | | `results[].quote` | object | Present when the pool was quoted. Same shape as the [single-pool response](/reference/api/retrieve-current-bid-and-ask.md#response-fields), including `depth`. | | `results[].error` | object | Present when the pool couldn't be quoted. `status` is the HTTP status the single-pool endpoint would have returned for this pool, `error` its message. | To estimate what an order fills for from a quote's `depth`, see [Estimating a fill](/reference/api/retrieve-current-bid-and-ask.md#estimating-a-fill). A pool whose feed has no price is a `quote`, not an `error`. It carries the unavailable sentinel (`bidAdj = "0"`, `askAdj = 2^128 − 1`) and its `priceProviderStatus`, exactly as on the single-pool endpoint. Check `priceProviderStatus` and each side's price in every quote before using it (see [Unavailable prices](/reference/api/retrieve-current-bid-and-ask.md#unavailable-prices)). Typical per-pool errors are `404` (`Pair metadata not found for `: the pool isn't served on this chain) and the temporary `500` (`Internal server error`), `502` (`Upstream service error`) and `503` (`Service temporarily unavailable`). Retry pools with a temporary error. ### Errors These fail the whole request. Per-pool problems never do: they are returned as entries in `results`. | Status | Error | When | | ------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `400` | `pools must name at least one pool address` | `pools` is empty. | | `400` | `pools names addresses; at most 100 are allowed per request` | More than 100 addresses, counting repeats. | | `400` | `pools[] is not a valid pool address` | An entry isn't a valid address. `` is its zero-based position. | | `400` | `Invalid request body: …` | The body isn't valid JSON, `pools` is missing, or it has unknown fields. | | `401` | `Invalid API key` | An `Authorization` header was sent with an unknown or revoked key. | | `404` | `Unknown chainId: ` | The chain is not served by the API. | | `429` | Rate limited | Too many requests. A valid key gets a higher limit. Wait for the time in `Retry-After`. | | `503` | `Service temporarily unavailable` | The batch took longer than 20 seconds. No partial results are returned. Retry, or split into smaller batches. | The rate limit counts batch requests, not pools, so one batch of 100 pools costs one request.