slippageHistory

Get historical slippage estimates for a specific market and notional size.

Overview

The slippageHistory endpoint returns historical slippage data sampled every 15 minutes. For a given coin and USD notional amount, it provides the estimated buy and sell slippage in basis points, along with the half-spread.

Key details:

• 15-minute sample interval

• Slippage measured in basis points (bps) for a specific USD notional size

• Available notional amounts: $1K, $5K, $10K, $30K, $50K, $100K, $250K, $500K, $1M

• Supports all perp markets including HIP-3 dexes

• Values rounded to 2 decimal places

• startTime and amount are required; results returned in ascending order

Request

Endpoint: POST /info

Field	Type	Description
type	string	Must be "slippageHistory"
coin	string	Coin symbol (e.g., "BTC", "ETH", "xyz:GOLD") - required
amount	number	USD notional amount (e.g., 100000) - 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)

Coin format: For Hyperliquid native markets, use the coin symbol directly (e.g., "BTC", "ETH"). For HIP-3 dex markets, prefix with the dex name and a colon (e.g., "xyz:GOLD", "cash:TSLA").

cURL

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slippageHistory",
    "coin": "BTC",
    "amount": 100000,
    "startTime": 1706000000000,
    "limit": 500
  }'

Python

import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'slippageHistory',
        'coin': 'BTC',
        'amount': 100000,
        'startTime': 1706000000000,
        '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: 'slippageHistory',
        coin: 'BTC',
        amount: 100000,
        startTime: 1706000000000,
        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": 1764777547234,
    "dex": "hyperliquid",
    "coin": "BTC",
    "halfSpreadBps": 0.05,
    "amountUsd": 100000.0,
    "buySlippageBps": 1.36,
    "sellSlippageBps": 0.05
  },
  {
    "timestamp": 1764778383619,
    "dex": "hyperliquid",
    "coin": "BTC",
    "halfSpreadBps": 0.05,
    "amountUsd": 100000.0,
    "buySlippageBps": 0.05,
    "sellSlippageBps": 0.05
  }
]

Response Fields

Field	Description
timestamp	Sample timestamp in milliseconds
dex	DEX identifier (e.g., "hyperliquid", "xyz")
coin	Coin symbol
halfSpreadBps	Half-spread at time of sample, in basis points
amountUsd	USD notional amount this slippage was estimated for
buySlippageBps	Estimated buy slippage in basis points (null if insufficient liquidity)
sellSlippageBps	Estimated sell slippage in basis points (null if insufficient liquidity)

Comparison with marketLiquidityHistory

Feature	marketLiquidityHistory	slippageHistory
Units	Depth in market asset (coins)	Slippage in basis points
Denominated in	Asset quantity	USD notional
Granularity	Hourly averages	15-minute samples
Use case	How deep is the book?	How much would a $X trade slip?

Rate limits

• 10 points per request

Common errors

• 400: coin parameter is required - must provide coin symbol

• 400: amount parameter is required (positive USD notional) - must provide a positive USD amount

• 400: startTime parameter is required - startTime is mandatory

• 403: Permission denied - check API key

• 429: Rate limit exceeded