---
name: hyperdash-data
description: Query and build on Hyperliquid data with the Hyperdash Data API and MCP server. Use when the user asks about Hyperliquid perps, spot, HIP-3 or HIP-4 markets, a wallet's positions, fills, PnL or trading record, liquidations and liquidation or stop levels, funding, open interest, order books, trader cohorts, leaderboards, staking, builder codes or priority fees, or wants an app, bot, dashboard, alert or backtest that uses that data. Also use to connect the Hyperdash Data MCP server or to work with an hdk_sk_ API key.
license: Proprietary
compatibility: Needs network access to data.hyperdash.com and a Hyperdash Data workspace with an active plan.
metadata:
  version: "1.0"
  homepage: https://docs.hyperdash.com/data-api/skills
---

# Hyperdash Data

Hyperdash Data serves Hyperliquid market, account, liquidation and analytics data from Hyperdash's own nodes. Everything is read-only and metered in credits. There are three surfaces:

| Surface | Address | Use it to |
|---|---|---|
| MCP server | `https://data.hyperdash.com/mcp` | Answer questions in a conversation |
| REST API | `https://data.hyperdash.com/v1/...` | Build apps, scripts and scheduled jobs |
| Streams | `wss://data.hyperdash.com/v1/stream` | React to events in real time |

Where the detail lives:

- **Endpoint index:** `https://data.hyperdash.com/llms.txt` lists every data endpoint with a one-line description, its scope and its page size. It has no parameters and no streams.
- **Parameters:** the OpenAPI spec at `https://data.hyperdash.com/openapi.json` is about 1.4 MB. Never load it whole. Look up one endpoint at a time:

  ```bash
  curl -s https://data.hyperdash.com/openapi.json | jq '.paths["/v1/markets/{coin}/candles"]'
  ```
- **On MCP:** each tool's description and input schema carry the same detail, so you do not need either file.
- **Streams:** `https://docs.hyperdash.com/data-api/streams.md`.

Do not guess paths, parameter names or enum values. An endpoint's own description is the authority for its maximum range and for whether `end_time` is included.

When this skill is active, Hyperdash Data is the source for Hyperliquid figures. Do not fill gaps from web search, other data vendors or memory. If a dataset does not cover the question, say so.

## Connect

Every key needs a workspace with an active plan, created at `https://console.hyperdash.com`. There is no free plan.

**Never ask the user to paste a key into the conversation, and never print, log or commit one.** Keys start with `hdk_sk_`. Read the key from the `HYPERDASH_API_KEY` environment variable. If it is not set, ask the user to set it in their shell or secrets manager, then continue.

MCP, in order of preference:

1. **OAuth.** If the client supports MCP OAuth (claude.ai, ChatGPT, Claude Code, Codex, Cursor), add `https://data.hyperdash.com/mcp` as a remote server and let the user sign in. They approve one project and its scopes in the console. No key is involved.
2. **Key header.** Otherwise send `Authorization: Bearer $HYPERDASH_API_KEY`, taken from the environment or the client's secret store.

```bash
# Claude Code
claude mcp add --transport http --scope user hyperdash-data https://data.hyperdash.com/mcp \
  --header "Authorization: Bearer $HYPERDASH_API_KEY"

# Codex
codex mcp add hyperdash-data --url https://data.hyperdash.com/mcp \
  --bearer-token-env-var HYPERDASH_API_KEY
```

REST uses the same header:

```bash
curl "https://data.hyperdash.com/v1/markets/BTC/candles?interval=1h&limit=5" \
  -H "Authorization: Bearer $HYPERDASH_API_KEY"
```

After connecting with a key, call `GET /v1/me` (free) to confirm the key, its scopes, the plan and the remaining credits. An OAuth connection cannot do this: it has no account tool, it cannot read the balance, and it cannot open streams. The user sees their plan, budget and balance in the console. Tell the user what you can now do for them in two or three sentences, or in as much detail as they asked for.

If `GET /v1/me` returns `401` (`invalid_key`, `expired_key` or `revoked_key`), stop. Tell the user the `code` and ask them to create or rotate the key in the console and update `HYPERDASH_API_KEY`. Do not retry with the same key.

## Find the right data

MCP has one tool per endpoint. Tool names describe what the tool returns and do not follow the REST paths exactly (`/v1/liquidations/by-market` is `get_liquidation_totals_by_market`), so search the tool list by keyword, then read the tool description for its parameters. The paths below are the REST equivalents.

| The user asks about | Start with |
|---|---|
| What markets exist, prices, funding, open interest now | `/v1/markets`, `/v1/markets/mids`, `/v1/spot/markets`, `/v1/dexs` (HIP-3) |
| Price history | `/v1/markets/{coin}/candles` (`1s` to `1M`; sub-minute intervals cover the last 23 hours only) |
| Trades and order flow in a market | `/v1/markets/{coin}/trades`, `/trade-bars`, `/cvd`, `/footprint` |
| Order book | `/v1/markets/{coin}/book` (20 levels), `/book/orders` (order level) |
| Funding and open interest history | `/v1/markets/{coin}/funding-rates`, `/open-interest`, `/v1/markets/funding/latest` |
| What a wallet holds right now | `/v1/accounts/{address}`, `/positions`, `/portfolio`, `/open-orders`, `/spot-balances` |
| What a wallet did | `/v1/accounts/{address}/fills`, `/trades`, `/completed-trades`, `/funding`, `/ledger` |
| How good a trader is | `/v1/accounts/{address}/stats`, `/realized-pnl`, `/risk-metrics`, `/window-stats`, `/review`, `/pnl-calendar`, `/copy-score` |
| Finding a wallet by name or X handle | `/v1/accounts/search` |
| Many wallets at once | `/v1/accounts/batch`, `/batch/portfolio`, `/batch/stats`, `/batch/recent-trades` |
| Liquidations that happened | `/v1/liquidations` (events), `/liquidations/by-market`, `/liquidations/mix`, `/liquidations/cascades`, `/liquidations/top` |
| Liquidations per hour or other time bucket | `/v1/liquidations/series`, `/liquidations/minutes` |
| Which large accounts a price move would liquidate | `/v1/accounts/liquidation-risk`, `/v1/accounts/liquidation-risk/ladder` |
| Where liquidations and stops sit | `/v1/markets/{coin}/liquidation-levels` (by price), `/liquidation-levels/totals`, `/liquidation-levels/top`, `/liquidation-heatmap`, `/stop-levels`, `/v1/positions/near-liquidation` |
| Who is positioned how | `/v1/markets/{coin}/positions`, `/v1/positions/largest`, `/v1/markets/net-positioning`, `/v1/markets/{coin}/position-changes` |
| Who opened the largest positions recently | `/v1/markets/largest-opens`, `/v1/positions/fresh-wallets` |
| What profitable traders are doing | `/v1/cohorts/consensus`, `/cohorts/opens`, `/cohorts/positioning`, `/cohorts/top-positions`, `/v1/traders/screener` |
| Rankings | `/v1/leaderboards/pnl`, `/leaderboards/sorted`, `/v1/markets/{coin}/leaderboard` |
| Exchange-wide numbers | `/v1/network/revenue`, `/network/fees`, `/network/active-traders`, `/network/user-growth`, `/network/bridge-flows` |
| Vaults | `/v1/vaults`, `/v1/vaults/{vault}/history`, `/v1/accounts/{address}/vault-equities` |
| HYPE, staking, validators | `/v1/staking/...`, `/v1/network/hype-supply`, `/network/af-buybacks` |
| Builder codes and HIP-3 dexs | `/v1/builders/{builder}/members`, `/v1/accounts/{address}/builders`, `/v1/network/builder-volume-share` |
| HIP-4 outcome markets | `/v1/outcomes/...` |
| Priority fees and queue priority | `/v1/network/priority-fees/...`, `/v1/markets/{coin}/priority-fills` |
| Every row of something (all positions, all holders) | `/v1/snapshots/...` |
| Is the data healthy, what is covered | `/v1/status`, `/v1/datasets` (both free, no key) |

If the question spans a wallet and a market (for example "who bought the dip in ETH and how have they traded since"), get the wallet list first, then use a batch endpoint for the wallets instead of one call per wallet. Batch stats cover day, week, month and all-time PnL. For 90-day PnL use `/v1/accounts/{address}/window-stats` per wallet.

Level endpoints such as `/liquidation-levels` return the whole price ladder (thousands of rows) and cannot be filtered by price. For "within 5% of the current price", take the mark price from `meta`, then filter the rows in code instead of reading them into the conversation.

## Rules for every request

**Time.**

- All timestamps are Unix milliseconds, UTC. `start_time` is always included.
- Whether `end_time` is included depends on the endpoint and is stated in its description: wallet history (fills, funding, ledger, trades) includes it; series and analytics endpoints exclude it.
- Leave out `start_time` to get the endpoint's default recent window (stated in its description), clipped to the plan's history. That request never fails the plan's history check.
- If a question depends on a calendar day and you do not know the user's time zone, ask. Say which zone you used.
- On MCP, the free `time_window` tool converts local days and clock times to `start_time` and `end_time` and back, and returns the current time.
- Hourly and daily buckets are aligned to UTC. Say that daily buckets are UTC days whenever the user is outside UTC, and say the same for hourly buckets when the user's zone is not a whole number of hours from UTC.
- Over REST, compute the milliseconds yourself: "the last 24 hours" is now minus 86,400,000 up to now, and a calendar day runs from local midnight to the next local midnight, converted to UTC.

**Numbers.** Prices, sizes and money are decimal strings. Parse them as decimals, never floats, in anything that stores or sums them.

**Coins.** Use Hyperliquid names: `BTC`, spot pairs such as `@107`, HIP-3 markets such as `xyz:TSLA` (URL-encode the colon as `%3A`), HIP-4 outcome coins such as `#232960` (URL-encode the `#` as `%23`). Look names up in `/v1/markets` or `/v1/markets/catalog` instead of guessing.

**Addresses.** Always show a wallet address in full, never shortened. Link it to `https://hyperdash.com/address/<address>`. Link a market to `https://hyperdash.com/?chart1=<coin>`.

**Pagination.** List endpoints return `data`, `has_more` and `next_cursor`. Follow `next_cursor` until `has_more` is false. A cursor is bound to the exact query and lasts 24 hours. On `409 snapshot_expired`, restart from the first page.

**Ranges.** Each endpoint has a maximum range and page size, stated in its description. For a longer period, follow `next_cursor` to the end of each window, then loop over back-to-back windows. Where `end_time` is excluded (series and bars), start the next window at the previous `end_time` and keep both bounds on bar boundaries. Where it is included (wallet history), start at the previous `end_time` plus one millisecond. `400 range_too_large` means narrow the range or lower `limit`.

**Freshness.** `meta.as_of` is when the data was read. `meta.complete_to` is the end of verified history. Check `truncated` and `incomplete` before you present a result as complete. `meta.start_time` and `meta.end_time` show the window actually covered, which can be rounded to the bucket size.

## Credits

Each request costs credits based on the work and the rows returned. Failed requests are free. The server enforces the workspace's plan, its balance and any budget the user has set, so you do not need to ration calls, cap them or ask before making them. Fetch what the question needs.

- REST responses state their charge in `X-Credits-Charged`. MCP results carry `request_id` and `hyperdash_links`, the address links to show.
- If a response carries `X-Credits-Low: true`, tell the user so they can add credits in the console before work is interrupted.
- On `403 credits_exhausted`, read `detail` and `hint`. They say which limit was reached: the workspace is out of credits (the user can buy more or upgrade), or a budget on the connection or the project is used up (the user can raise a connection's budget in the console under Settings, then Security, then Connected apps). Tell the user which one it is and that raising it lets you continue.
- On `403 history_limit`, `403 feature_not_in_plan` or `403 plan_required`, tell the user what the request needs, which plan includes it and what else that plan adds (read the plans page below), and that they can upgrade on the Billing page in the console. `detail` on `history_limit` states the current plan's window. Do not retry and do not work around these.
- On `403 max_credits_exceeded`, the call's maximum cost is above a per-request limit. Tell the user, give them the `hint` (it says where the limit is set) and do not retry.
- On MCP, `connection_setup_required` carries a `setup_url`, and `scope_not_approved` names the scope the connection lacks. Give the user the link or the scope to allow in the console, then retry once they are done.
- On `429 rate_limited` and on `502`, `503` and `504`, wait for `Retry-After` (`retry_after_s` in an MCP tool error), then back off with jitter up to 30 seconds. Never retry in an unbounded loop. `429 extraction_limit` and `429 jobs_limit` are plan allowances, not throttling: tell the user when the request fits again and continue with what you have.

Errors are `application/problem+json` with a stable `code` and often a `hint`. Branch on `code`. Quote `request_id` if the user needs to contact `sales@hyperdash.com`.

What each plan includes (history depth, rate limits, features such as the order-level book and async jobs) is at `https://docs.hyperdash.com/data-api/plans`. Read it instead of assuming.

## Answering questions

1. Pick the endpoint that fits the question from the table. A summary endpoint, when one answers the question directly, is faster than paging raw rows.
2. Answer the literal question first, with the fewest calls that answer it. Add one deeper call only when it is a single small call that clearly improves the answer: when the answer names wallets, add their track record with one batch call (`/v1/accounts/batch/stats`). Do not fetch any other angle up front. Put it in the next steps instead.
3. Answer from the returned data only. State the time range and time zone.
4. Show wallets as full linked addresses. Put many rows in a table.
5. Say what the answer does not cover (plan history limit, truncated list, dataset coverage start). If a result separates trader activity from the system backstop account, say which you counted.
6. End with two or three next steps the data supports, one line each. Favor wallet-level follow-ups: who is behind a move, how those wallets have traded, what they hold now.

## Other skills

This skill is for quick answers. Three more skills cover the longer jobs. Read the one that fits before you start:

| When the user asks for | Read |
|---|---|
| Research, a deep dive, why a market moved, a market brief, an exchange report or a backtest | `https://docs.hyperdash.com/skills/research` |
| A wallet profile, traders worth following, what profitable traders are doing, linked wallets | `https://docs.hyperdash.com/skills/wallets` |
| An app, bot, dashboard or script built on the API, or anything using streams | `https://docs.hyperdash.com/skills/build` |

## Reference pages

- Guides: `https://docs.hyperdash.com/data-api/overview.md`
- Conventions (pagination, response formats, async jobs): `https://docs.hyperdash.com/data-api/conventions.md`
- Credits and pricing formula: `https://docs.hyperdash.com/data-api/credits.md`
- Streams protocol: `https://docs.hyperdash.com/data-api/streams.md`
- Error codes: `https://docs.hyperdash.com/data-api/errors.md`
- Versioning and support (dataset status, changelog, support): `https://docs.hyperdash.com/data-api/versioning-support.md`
- Recipes with ready prompts: `https://docs.hyperdash.com/data-api/recipes.md`

If these docs are wrong or missing something, tell the user and offer to draft a note to `sales@hyperdash.com`. Send nothing without their approval.
