> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/market-data/marketliquidity.md).

# marketLiquidity

## Overview

The `marketLiquidity` endpoint returns aggregated orderbook depth data for a specific market.

**Key details:**

* Refreshed every second
* Data retained for 24 hours
* Depth available at multiple bps levels (2, 5, 10, 25, 25-500)
* Supports time-based filtering (up to 24h back)

#### Request

**Endpoint:** `POST /info`

<table><thead><tr><th width="164">Field</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"marketLiquidity"</code></td></tr><tr><td><code>market</code></td><td>string</td><td>Market symbol (e.g., "BTC", "flx:TSLA") - required</td></tr><tr><td><code>startTime</code></td><td>integer</td><td>Start timestamp in milliseconds, must be within 24h (optional)</td></tr><tr><td><code>endTime</code></td><td>integer</td><td>End timestamp in milliseconds, used with startTime (optional)</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Max rows to return, default/max 500 (optional)</td></tr></tbody></table>

**Note:** When `startTime` is provided, results are returned in ascending order (oldest first). Without `startTime`, results are returned in descending order (newest first).

{% tabs %}
{% tab title="Python" %}

<pre class="language-python"><code class="lang-python"><strong>import requests 
</strong>import os
response = requests.post(
    'https://api.hydromancer.xyz/info', 
    json={ 'type': 'marketLiquidity', 'market': 'BTC', 'limit': 100 }, 
    headers={ 
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}', 
        'Content-Type': 'application/json' 
        } 
    )
print(response.json())
</code></pre>

{% endtab %}
{% endtabs %}

<details>

<summary>Response Fields</summary>

```json
[
  {
    "timestamp": 1769093272236,
    "market": "BTC",
    "bestBidPrice": "89216.00",
    "bestAskPrice": "89217.00",
    "bidDepth2bps": "2.74368",
    "bidDepth5bps": "54.3951",
    "bidDepth10bps": "181.87754",
    "bidDepth25bps": "569.9405",
    "bidDepth25To500bps": "1956.54844",
    "askDepth2bps": "134.67537",
    "askDepth5bps": "207.53212",
    "askDepth10bps": "376.64531",
    "askDepth25bps": "672.82051",
    "askDepth25To500bps": "1890.64212"
  }
]
```

| Field                | Description                                                          |
| -------------------- | -------------------------------------------------------------------- |
| `timestamp`          | Snapshot timestamp in milliseconds                                   |
| `market`             | Market symbol                                                        |
| `bestBidPrice`       | Best bid price across all addresses                                  |
| `bestAskPrice`       | Best ask price across all addresses                                  |
| `bidDepth2bps`       | Total bid depth within 2 basis points of mid (in market asset)       |
| `bidDepth5bps`       | Total bid depth within 5 basis points of mid (in market asset)       |
| `bidDepth10bps`      | Total bid depth within 10 basis points of mid (in market asset)      |
| `bidDepth25bps`      | Total bid depth within 25 basis points of mid (in market asset)      |
| `bidDepth25To500bps` | Total bid depth between 25-500 basis points of mid (in market asset) |
| `askDepth2bps`       | Total ask depth within 2 basis points of mid (in market asset)       |
| `askDepth5bps`       | Total ask depth within 5 basis points of mid (in market asset)       |
| `askDepth10bps`      | Total ask depth within 10 basis points of mid (in market asset)      |
| `askDepth25bps`      | Total ask depth within 25 basis points of mid (in market asset)      |
| `askDepth25To500bps` | Total ask depth between 25-500 basis points of mid (in market asset) |

</details>

#### Rate limits

* 10 points per request

#### Common errors

* **400**: `market parameter is required` - must provide market symbol
* **400**: `startTime cannot be more than 24 hours in the past` - time filter limit
* **403**: Permission denied - check API key
* **429**: Rate limit exceeded