> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Times, numbers, identifiers, pagination, response formats, and async jobs.

## Data conventions

| Topic | Rule |
| - | - |
| Time | Integers in Unix milliseconds, UTC. Ranges use `start_time` and `end_time` and are half-open: `start_time` is included, `end_time` is not. |
| Numbers | Prices, sizes, and money are decimal strings (`"108733.0"`). Parse them as decimals: the same value may appear with extra trailing zeros. Counts are integers. |
| Coins | Hyperliquid names: `BTC`, spot pairs such as `@107`, HIP-3 markets such as `xyz:TSLA` (URL-encode the colon as `%3A`). |
| Addresses | `0x` followed by 40 hex characters. |
| Field names | `snake_case`. Series rows use short keys (`t o h l c v q n`), documented per endpoint. |
| Caching | Authenticated responses carry `Cache-Control: private, no-store`. |
| Request IDs | Every response carries an `X-Request-Id` (a UUIDv7). Quote it when you contact support. |

## Response metadata

List endpoints return `data`, `has_more`, `next_cursor`, and a `meta` object. Depending on the endpoint, `meta` and the matching headers describe freshness and completeness:

| Field | Header | Meaning |
| - | - | - |
| `as_of` | `X-As-Of` | When the data was read, in Unix milliseconds. |
| `complete_to` | `X-Complete-To` | The end of the verified history. Anything later comes from the live feed. |
| `truncated`, `max_rows` | `X-Truncated`, `X-Max-Rows` | The result was cut at your plan's wallet-list cap. |
| `incomplete` | `X-Incomplete` | Parts of the result could not be served. |

Check `GET /v1/status` (free, no key needed) for each dataset's health (`ok`, `degraded`, `stale`, or `unknown`), its live lag and, where available, its `complete_to`. `GET /v1/datasets` lists every dataset with its coverage and endpoints, and `GET /v1/changelog` lists features, deprecations, data corrections, and incidents.

## Pagination

List endpoints use cursors. Pass `limit` (each endpoint documents its default and maximum) and follow `next_cursor` until `has_more` is `false`.

```js theme={null}
let cursor = null;
do {
  const url = new URL("https://data.hyperdash.com/v1/liquidations");
  url.search = new URLSearchParams({ coin: "ETH", start_time: from, end_time: to, limit: 1000, ...(cursor && { cursor }) });
  const page = await (await fetch(url, { headers: { Authorization: `Bearer ${key}` } })).json();
  handle(page.data);
  cursor = page.next_cursor;
} while (cursor);
```

* A cursor is signed, bound to your workspace and the exact query, and valid for 24 hours. An expired or mismatched cursor returns `400 invalid_parameter`.
* Responses are capped at 2 MiB (16 MiB on batch endpoints). A request that would exceed the cap returns `400 range_too_large`: lower `limit` and page through.
* Request bodies can be at most 64 KiB (1 MiB on batch endpoints, 128 KiB on the priority lookup).

## Response formats

List endpoints return JSON by default. Send `Accept: text/csv` for CSV, or `Accept: application/x-ndjson` (also `application/jsonl`) for newline-delimited JSON. Rows and price are the same in every format. Test keys always return JSON. In CSV and NDJSON, pagination moves to the `X-Has-More` and `X-Next-Cursor` headers, and the freshness headers above apply.

## Async jobs

Async jobs run computations that take too long for a normal request. They are available on Growth, Scale, and Enterprise.

1. `POST /v1/jobs` with an `Idempotency-Key` header and a body such as `{"kind": "account_fills_summary", "params": {...}}`.
2. Poll `GET /v1/jobs/{id}` until the job is done. Asking for the result too early returns `409 job_not_ready`.
3. Read the result from `GET /v1/jobs/{id}/result`, paginated like any list.

The only job kind today is `account_fills_summary`. For one wallet over up to 90 days, it returns per coin: fill count, buy and sell notional, fees, realized PnL, and first and last fill. At most 2 jobs can run at a time and 100 per day. Results are kept for 24 hours. Creating, listing, polling, and cancelling jobs is free. Reading the result costs 10 credits plus 1 per row, and the first page also carries the job's compute fee: 20 credits per upstream call plus 1 credit per 10 fills scanned.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.