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

# slippageHistory

### 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`

<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>"slippageHistory"</code></td></tr><tr><td><code>coin</code></td><td>string</td><td>Coin symbol (e.g., "BTC", "ETH", "xyz:GOLD") - required</td></tr><tr><td><code>amount</code></td><td>number</td><td>USD notional amount (e.g., 100000) - 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>

**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"`).

{% 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": "slippageHistory",
    "coin": "BTC",
    "amount": 100000,
    "startTime": 1706000000000,
    "limit": 500
  }'
```

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title="Javascript" %}

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

{% endtab %}
{% endtabs %}

<details>

<summary>Response</summary>

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

</details>

## 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