> ## Documentation Index > Fetch the complete documentation index at: https://docs.ironflow.sh/llms.txt > Use this file to discover all available pages before exploring further. # Hyperliquid wallet labels > GET /v1/analytics/wallet-labels returns precomputed Hyperliquid wallet labels: whales, smart money, vaults and vault leaders. ## OpenAPI ````yaml GET /v1/analytics/wallet-labels openapi: 3.1.0 info: title: Ironflow API version: 1.0.0 description: > Hyperliquid market data from Ironflow's own nodes: tick-level fills and trades, candles, funding rates, liquidations, mark prices, open interest, markets and wallet analytics over REST, live Server-Sent Events streams and read-only SQL. One schema across native HL perps, HIP-3 builder markets, HIP-4 outcome contracts and HL spot. The same data is a hosted MCP server for AI agents at `https://mcp.ironflow.sh/mcp`, and agents with a USDC wallet on Base can pay per call with x402, no key: the data GET endpoints are also served at `/x402/v1/...` (discovery: `https://api.ironflow.sh/openapi.json` and `https://api.ironflow.sh/.well-known/x402`). **Base URL:** `https://api.ironflow.sh` **Authentication:** Read endpoints work without a key (keyless access) or with a Bearer token in the `Authorization` header. Writes always need a key. ``` Authorization: Bearer if_your_api_key ``` Get a free key at https://ironflow.sh/key. **Access levels:** | Access | Requests per minute | History | Max range per request | |---|---|---|---| | No key | 30 per IP (2,000 a day) | 24 hours | 1 hour | | Free key | 60 | 30 days | 6 hours | | Explorer | 100 | 90 days | 24 hours | | Builder | 1,000 | 1 year | 7 days | | Enterprise | 10,000 | full | unlimited | Without a market filter, high-volume endpoints allow at most 4 hours per request. `/v1/trades` filtered to one perp or spot market allows 24 hours per request without a key and on a free key. A header that is present but malformed returns 401; keyless access applies only when no `Authorization` header is sent. **Data availability:** fills and trades start on 25 May 2025; other datasets start later (funding 2025-09-27, open interest and mark prices 2026-04-29). Bulk history is free to download from https://huggingface.co/ironflow. **Timestamps:** All timestamps are Unix milliseconds (int64). **Pagination:** Paginated endpoints return a `cursor` in `pagination.next_cursor`. Pass it as the `cursor` query parameter to fetch the next page. When `pagination.has_more` is `false`, you have reached the last page. **Notices:** a successful JSON object may start with `notice`, the `X-Ironflow-Notice` header in the body: what was served when it differs from what was asked (a keyless sample, a shortened history, a guessed path) and how to get the rest. **Guessed paths:** a few paths callers guess are answered by the endpoint they mean, with a `notice` and the `X-Ironflow-Canonical` header naming it: `/v1/liquidations/aggregate`, `/v1/summary/liquidations` and similar by `/v1/liquidations/summary`, `/v1/liquidations/buckets` and `heatmap` by `/v1/analytics/liquidation-levels`, and `/v1/liquidations/map/BTC-PERP` by `/v1/liquidations/map?market=BTC-PERP`. A path with trailing `.`, `,`, `;` or `)` (`/v1/query.`, copied from a sentence) is answered by the endpoint without them, with the same method, query and body. OpenAI-style paths (`/v1/models`, `/v1/chat/completions`) answer 404: this is not an LLM API, and agents use the MCP server above. contact: name: Ironflow Support url: https://ironflow.sh servers: - url: https://api.ironflow.sh description: Production security: - bearerAuth: [] - {} tags: - name: Market Data description: Historical tick-level market data stored in ClickHouse. - name: Analytics description: >- Aggregated analytics. Net flows, funding stats and the liquidation map markets work without a key; liquidation levels, the liquidation map and the vault leaderboard return a sample without one; order flow needs a key (a free key works). - name: Cohorts description: Predefined and custom address groups for filtering market data. - name: Alerts description: >- Liquidation alerts that Ironflow posts to your webhook, Discord channel, Slack channel or Telegram chat. - name: Ironbox description: >- Secure, sandboxed environments in Tokyo, next to Hyperliquid, where a trading agent runs with Ironflow's data, analytics, alerts and execution. Any API key, free included. - name: Query description: >- Read-only ClickHouse SQL over curated Hyperliquid tables (hl.*), limited by tier. - name: Billing description: >- Paid plans, paid in USDC on Hyperliquid or with x402 on Base. No card, no account page. - name: System description: Health checks and metadata endpoints. - name: TradingApp description: >- The trading terminal's own endpoints (terminal.ironflow.sh), wallet-session auth. Not part of the public data API; left out of the docs copy. paths: /v1/analytics/wallet-labels: get: tags: - Analytics summary: Precomputed wallet labels (whales, smart money, vaults) description: | Single-blob catalog of address → label list. Covers four categories: - **whale** — top 100 wallets by 24h notional volume - **smart_money** — top 100 wallets by 30d realized PnL - **vault** — every distinct vault address with ops in 365d - **vault_leader** — modal commission recipient per vault (the operator earning carry) Edge-cached for 5 minutes. The full response is ~few KB and is designed to be fetched once per session and used to label every address in the terminal without per-row API calls. operationId: getWalletLabels parameters: - $ref: '#/components/parameters/source' - name: whale_top_n in: query schema: type: integer minimum: 1 maximum: 500 default: 100 - name: smart_top_n in: query schema: type: integer minimum: 1 maximum: 500 default: 100 responses: '200': description: Wallet labels blob. content: application/json: schema: $ref: '#/components/schemas/WalletLabelsResponse' '500': $ref: '#/components/responses/InternalError' '504': $ref: '#/components/responses/QueryTimeout' components: parameters: source: name: source in: query description: Venue identifier. Defaults to `hyperliquid`. schema: type: string enum: - hyperliquid default: hyperliquid example: hyperliquid schemas: WalletLabelsResponse: type: object required: - generated_at - ttl_seconds - source - labels - counts properties: generated_at: type: integer format: int64 description: Unix ms ttl_seconds: type: integer example: 300 source: type: string example: hyperliquid labels: type: object description: Map of address → label list (lowercase hex keys). additionalProperties: type: array items: $ref: '#/components/schemas/WalletLabel' counts: type: object required: - whales - smart_money - vaults - vault_leaders properties: whales: type: integer smart_money: type: integer vaults: type: integer vault_leaders: type: integer WalletLabel: type: object description: One label attached to an address by the precomputed catalog. required: - kind - name - priority properties: kind: type: string enum: - whale - smart_money - vault - vault_leader rank: type: integer description: 1-based rank within the category (0 for unranked kinds) example: 5 name: type: string description: Human-readable, stable display string. example: 'WHALE · #5' priority: type: integer description: Higher wins when an address has multiple labels. example: 30 value: type: number format: double nullable: true description: Metric value that earned the label (e.g. 24h USD volume). Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code. example: RATE_LIMIT_EXCEEDED message: type: string description: Human-readable error description. example: Rate limit exceeded. Retry after 60 seconds. upgrade: type: object description: >- On a limit a higher plan lifts, the next plan, its price, what it lifts and the call that gets it. ironbox: type: object description: >- On a rate limit, the keyless daily cap, the stream limit and the SQL time budget, how to run the agent in an Ironbox instead. properties: why: type: string example: >- No rate limits inside an Ironbox: your agent runs next to Hyperliquid with the data on the box. create: type: string example: POST https://api.ironflow.sh/v1/ironbox url: type: string format: uri example: https://ironflow.sh/ironbox?utm_source=api stream: type: string description: >- On the keyless daily limit of `/v1/liquidations` and `/v1/trades`, the live stream that replaces polling. example: >- GET https://api.ironflow.sh/v1/liquidations/stream (no daily limit for keyless streams) responses: InternalError: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An unexpected error occurred QueryTimeout: description: >- Query exceeded the 15-second execution limit. Narrow your time range, add a market filter, or reduce the limit. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: QUERY_TIMEOUT message: >- query took too long — narrow your time range, add a market filter, or reduce the limit securitySchemes: bearerAuth: type: http scheme: bearer description: >- Ironflow API key, format `if_xxxx`. Free keys at https://ironflow.sh/key. Optional on read endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.