> 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/marketliquidityhistory.md).

# marketLiquidityHistory

### Overview

The `marketLiquidityHistory` endpoint returns hourly-averaged orderbook depth data for a specific market. It provides the same depth metrics as `marketLiquidity` but pre-aggregated into hourly buckets with **unlimited retention** (whereas `marketLiquidity` is limited to 24 hours).

**Key details:**

* Hourly granularity (average depth per snapshot within each hour)
* Unlimited data retention
* Depth available at multiple bps levels (2, 5, 10, 25, 25-500)
* `startTime` is required; results always returned in ascending order

## 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>"marketLiquidityHistory"</code></td></tr><tr><td><code>market</code></td><td>string</td><td>Market symbol (e.g., "BTC", "ETH") - required</td></tr><tr><td><code>startTime</code></td><td>integer</td><td>Start timestamp in milliseconds - required</td></tr><tr><td><code>endTime</code></td><td>integer</td><td>End timestamp in milliseconds (optional)</td></tr><tr><td><code>limit</code></td><td>integer</td><td>Max rows to return, default 500, max 2000 (optional)</td></tr></tbody></table>

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

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "marketLiquidityHistory",
    "market": "BTC",
    "startTime": 1706000000000,
    "endTime": 1706100000000,
    "limit": 500
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'marketLiquidityHistory',
        'market': 'BTC',
        'startTime': 1706000000000,
        'endTime': 1706100000000,
        'limit': 500
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'marketLiquidityHistory',
        market: 'BTC',
        startTime: 1706000000000,
        endTime: 1706100000000,
        limit: 500
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>Response</summary>

```json
[
  {
    "timestamp": 1706000000000,
    "market": "BTC",
    "snapshots": 3600,
    "avgBidDepth2bps": "2.74368",
    "avgBidDepth5bps": "54.3951",
    "avgBidDepth10bps": "181.87754",
    "avgBidDepth25bps": "569.9405",
    "avgBidDepth25To500bps": "1956.54844",
    "avgAskDepth2bps": "134.67537",
    "avgAskDepth5bps": "207.53212",
    "avgAskDepth10bps": "376.64531",
    "avgAskDepth25bps": "672.82051",
    "avgAskDepth25To500bps": "1890.64212"
  }
]
```

</details>

## Response Fields

| Field                   | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `timestamp`             | Hour start timestamp in milliseconds                                   |
| `market`                | Market symbol                                                          |
| `snapshots`             | Number of per-market snapshots aggregated in this hour                 |
| `avgBidDepth2bps`       | Average bid depth within 2 basis points of mid (in market asset)       |
| `avgBidDepth5bps`       | Average bid depth within 5 basis points of mid (in market asset)       |
| `avgBidDepth10bps`      | Average bid depth within 10 basis points of mid (in market asset)      |
| `avgBidDepth25bps`      | Average bid depth within 25 basis points of mid (in market asset)      |
| `avgBidDepth25To500bps` | Average bid depth between 25-500 basis points of mid (in market asset) |
| `avgAskDepth2bps`       | Average ask depth within 2 basis points of mid (in market asset)       |
| `avgAskDepth5bps`       | Average ask depth within 5 basis points of mid (in market asset)       |
| `avgAskDepth10bps`      | Average ask depth within 10 basis points of mid (in market asset)      |
| `avgAskDepth25bps`      | Average ask depth within 25 basis points of mid (in market asset)      |
| `avgAskDepth25To500bps` | Average ask depth between 25-500 basis points of mid (in market asset) |

### Comparison with marketLiquidity

| Feature     | `marketLiquidity`        | `marketLiquidityHistory` |
| ----------- | ------------------------ | ------------------------ |
| Granularity | Per-second snapshots     | Hourly averages          |
| Retention   | 24 hours                 | Unlimited                |
| Values      | Total depth per snapshot | Average depth per hour   |
| `startTime` | Optional (within 24h)    | Required                 |

### Rate limits

* 10 points per request

### Common errors

* **400**: `market parameter is required` - must provide market symbol
* **400**: `startTime parameter is required` - startTime is mandatory
* **403**: Permission denied - check API key
* **429**: Rate limit exceeded