# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hydromancer.xyz/readme/rest-api/market-data/slippagehistory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.