> 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/asset-data/perppricehistorybytime.md).

# perpPriceHistoryByTime

Returns the accepted oracle and mark prices of a perp within a time range

Rows are in ascending order (oldest first), one per oracle round (roughly every 3 seconds per dex). These are the prices the exchange actually uses for margining and liquidation, on every dex including HIP-3. For HIP-3 they are the values the network **accepted** for the round, not what the dex deployer submitted in its `setOracle` action — use [oraclePriceHistoryByTime](/readme/rest-api/asset-data/oraclepricehistorybytime.md) for the raw submission. For the native Hyperliquid dex both endpoints return the same validator round.

<table><thead><tr><th width="115.50848388671875">Field</th><th width="177.66351318359375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"perpPriceHistoryByTime"</code></td></tr><tr><td><code>coin</code></td><td>string</td><td>symbol e.g. "BTC" or with dex prefix "xyz:XYZ100"</td></tr><tr><td><code>coins</code></td><td>string[]</td><td>batch form: 1–20 symbols. Returns an object keyed by coin instead of a flat array. Use <em>either</em> <code>coin</code> or <code>coins</code>.</td></tr><tr><td><code>startTime</code></td><td>int</td><td>ms unix timestamp</td></tr><tr><td><code>endTime</code></td><td>int</td><td>ms unix timestamp (optional)</td></tr><tr><td><code>limit</code></td><td>int</td><td>max 2000 (default 2000)</td></tr><tr><td><code>dex</code></td><td>string</td><td>DEX identifier e.g. "hyna", "xyz"; "main_dex" for the native dex (optional, returns all if omitted)</td></tr></tbody></table>

Request

{% 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": "perpPriceHistoryByTime",
      "coin": "xyz:AAOI",
      "startTime": 1787528956000,
      "endTime": 1787528966000
    }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os
import json

response = requests.post(
 'https://api.hydromancer.xyz/info',
 json={
        'type': 'perpPriceHistoryByTime',
        'coin': 'xyz:AAOI',
        'startTime': 1787528956000,
        'endTime': 1787528966000
 },
 headers={
          'Authorization': f'Bearer {os.environ["HYDROMANCER_API_KEY"]}',
          'Content-Type': 'application/json'
      }
)
print(json.dumps(response.json(), indent=2))
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

const response = await axios.post(
  'https://api.hydromancer.xyz/info',
  {
    type: 'perpPriceHistoryByTime',
    coin: 'xyz:AAOI',
    limit: 100,
    startTime: 1787528956000,
    endTime: 1787528966000
  },
  {
    headers: {
      'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
      'Content-Type': 'application/json'
    }
  }
);

console.log(JSON.stringify(response.data, null, 2));
```

{% endtab %}
{% endtabs %}

***

## Batch (multiple coins)

Pass `coins` (an array of 1–20 symbols) instead of `coin` to fetch several markets over the same time range in one request. `startTime`, `endTime` and `dex` apply to every coin. `limit` is **per coin, max 100** in the batch form (default 100) — so a 20-coin batch returns at most \~2000 rows; use the single-coin form for a wider window on one market. The response is an **object keyed by coin**, each value the same row array as the single-coin form; a requested coin with no data maps to an empty array.

This is served by a single ClickHouse query (`coin` is the table's leading sort key), so it is cheaper than looping the single-coin request. Billing is **1 token per coin** (a single-coin request is 1 token), and the rate-limit cost scales with the number of coins.

```bash
curl -X POST https://api.hydromancer.xyz/info \
-H "Authorization: Bearer $HYDROMANCER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
      "type": "perpPriceHistoryByTime",
      "coins": ["BTC", "xyz:GOLD"],
      "startTime": 1787528956000,
      "endTime": 1787528966000
    }'
```

```json
{
  "BTC": [ { "time": 1787528958000, "blockNumber": 1130393728, "dex": "hyperliquid", "coin": "BTC", "oraclePx": "...", "markPx": "..." } ],
  "xyz:GOLD": [ { "time": 1787528958000, "blockNumber": 1130393728, "dex": "xyz", "coin": "xyz:GOLD", "oraclePx": "...", "markPx": "...", "updateClass": "Normal" } ]
}
```

## Response Fields

| Field         | Type    | Description                                                                                                                                                                                                                                                                |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `time`        | int     | Block timestamp of the oracle round (ms)                                                                                                                                                                                                                                   |
| `blockNumber` | int     | Height of the block that committed the round — joins to `userFillsByTime` / block-level data                                                                                                                                                                               |
| `dex`         | string  | DEX identifier (`"hyperliquid"` for the native dex)                                                                                                                                                                                                                        |
| `coin`        | string  | Trading pair                                                                                                                                                                                                                                                               |
| `oraclePx`    | string? | Accepted oracle price. Omitted when the round carried no oracle slot for the asset: delisted native assets kept a frozen `markPx` with no oracle until 2026-06-13 (they drop out entirely after that), and the natively-priced HYPE/PURR miss the slot in \~2 rounds a day |
| `markPx`      | string  | Accepted mark price — the value used for margining, liquidations and funding. Always present                                                                                                                                                                               |
| `extPerpPx`   | string? | External perp reference price; omitted for assets without one                                                                                                                                                                                                              |
| `updateClass` | string? | HIP-3 only: how the network sourced the round as reported by the node (`"Deployer"`, `"Fallback"`, `"Normal"`). Omitted for the native dex                                                                                                                                 |

When a block commits more than one oracle round for the same dex, the last round is returned.

Accepted HIP-3 rounds are available from 2026-02-24; native rounds from 2025-08-01.

<details>

<summary>Response (HIP-3 dex)</summary>

```json
[
  {
    "time": 1787528956211,
    "blockNumber": 1130393728,
    "dex": "xyz",
    "coin": "xyz:AAOI",
    "oraclePx": "106.88",
    "markPx": "106.97",
    "extPerpPx": "106.88",
    "updateClass": "Deployer"
  },
  {
    "time": 1787528959402,
    "blockNumber": 1130393772,
    "dex": "xyz",
    "coin": "xyz:AAOI",
    "oraclePx": "106.88",
    "markPx": "106.96",
    "extPerpPx": "106.88",
    "updateClass": "Deployer"
  }
]
```

</details>

<details>

<summary>Response (native dex)</summary>

```json
[
  {
    "time": 1787528956211,
    "blockNumber": 1130393728,
    "dex": "hyperliquid",
    "coin": "BTC",
    "oraclePx": "108712.00",
    "markPx": "108708.40",
    "extPerpPx": "108709.50"
  },
  {
    "time": 1787528959402,
    "blockNumber": 1130393772,
    "dex": "hyperliquid",
    "coin": "BTC",
    "oraclePx": "108715.00",
    "markPx": "108711.10",
    "extPerpPx": "108712.00"
  }
]
```

</details>