marketLiquidityHistory

Get hourly-averaged orderbook depth history for a specific market with unlimited retention.

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

Field	Type	Description
type	string	Must be "marketLiquidityHistory"
market	string	Market symbol (e.g., "BTC", "ETH") - required
startTime	integer	Start timestamp in milliseconds - required
endTime	integer	End timestamp in milliseconds (optional)
limit	integer	Max rows to return, default 500, max 2000 (optional)

cURL

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
  }'

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())

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);
}

Response

[
  {
    "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"
  }
]

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