> ## 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 trade history > GET /v1/trades returns tick-level Hyperliquid trades for one market across all participants. Every trade is stored; the history window depends on your key tier. ## OpenAPI ````yaml GET /v1/trades 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. One schema across native HL perps, HIP-3 builder markets, HIP-4 outcome contracts and HL spot. **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 | 10 per IP | 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. A header that is present but malformed returns 401; keyless access applies only when no `Authorization` header is sent. **Data availability:** fills and trades cover a rolling 12 months; other datasets start later (funding 2025-09-27, open interest and mark prices 2026-04-29). **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. 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 endpoints (Builder tier and above). - name: Cohorts description: Predefined and custom address groups for filtering market data. - name: Info Proxy description: >- Cached passthrough to the Hyperliquid Info API. No record caps, higher rate limits. - name: Export description: Bulk data export as CSV or Parquet (Builder tier and above). - name: Query description: >- Read-only ClickHouse SQL over curated Hyperliquid tables (hl.*), limited by tier. - name: System description: Health checks and metadata endpoints. - name: TradingApp description: >- Trading app Phase A — wallet auth (SIWE), agent-key provisioning, and kill-switch. paths: /v1/trades: get: tags: - Market Data summary: List trades description: > Query historical tick-level trades. Returns all trades across all participants for the given market. Full tick resolution — every trade is stored. **History windows by tier:** - No key: 24 hours - Free key: 30 days - Explorer: 90 days - Builder: 1 year - Enterprise: everything stored (fills: rolling 12 months) **Per-request query window (max time range per request):** - With market filter: no key 1h, free key 6h, Explorer 24h, Builder 7d, Enterprise unlimited - Without market filter: 4h (all tiers) - Returns `QUERY_WINDOW_EXCEEDED` (400) if exceeded. Paginate by splitting into smaller from/to windows. operationId: listTrades parameters: - name: order in: query required: false description: >- Sort direction by timestamp. `asc` (default) returns the oldest rows of the window first; `desc` returns the newest first — use with `limit` to get the freshest trades. schema: type: string enum: - asc - desc default: asc - $ref: '#/components/parameters/source' - $ref: '#/components/parameters/market' - $ref: '#/components/parameters/base_market' - $ref: '#/components/parameters/issuer' - $ref: '#/components/parameters/from' - $ref: '#/components/parameters/to' - $ref: '#/components/parameters/address' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' - name: min_size in: query description: Minimum trade size filter (decimal string, e.g. `"1.0"`). schema: type: string example: '1.0' responses: '200': description: Paginated list of trades. content: application/json: schema: $ref: '#/components/schemas/TradeList' example: data: - source: hyperliquid market: BTC-PERP issuer: '' base_market: BTC-PERP market_type: perp timestamp: 1718400000000 block_number: 12345678 sequence: 42 price: '67432.10' size: '1.5' side: buy address: '0xabc123' fee: '0.38' realized_pnl: '0' hash: '0x9f1a2b' - source: hyperliquid market: flx:GAS-PERP issuer: flx base_market: GAS-PERP market_type: perp timestamp: 1718400001000 block_number: 12345679 sequence: 43 price: '1.5021' size: '12000' side: buy address: '0xdef456' fee: '0.05' realized_pnl: '0' hash: '0x9f1a2c' pagination: next_cursor: MTcxODQwMDAwMDAwMC00Mg== has_more: true '400': $ref: '#/components/responses/QueryWindowExceeded' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '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 market: name: market in: query description: Market symbol (e.g. `BTC-PERP`, `ETH-PERP`). Omit to query all markets. schema: type: string example: BTC-PERP base_market: name: base_market in: query description: > Base market symbol, stripped of any issuer namespace (e.g. `GAS-PERP`). Matches both native HL markets (`market` == `base_market`) and every HIP-3 builder-deployed market with that base (e.g. `flx:GAS-PERP`). Use together with `issuer` to scope to a single builder, or alone to query across all issuers of the same base symbol. schema: type: string example: GAS-PERP issuer: name: issuer in: query description: > HIP-3 builder/issuer namespace (e.g. `flx`). For native HL perps the issuer is the empty string; do not combine `issuer=""` with this filter — omit the parameter instead. Commonly paired with `base_market` to disambiguate a builder-deployed market from its native counterpart. schema: type: string example: flx from: name: from in: query description: >- Start time as Unix milliseconds. Defaults to 24 hours ago. Clamped to tier history window. On /v1/trades and /v1/fills, the time range (to - from) is limited per tier (no key 1h, free key 6h, Explorer 24h, Builder 7d, Enterprise unlimited; without market filter 4h for all tiers). Returns QUERY_WINDOW_EXCEEDED (400) if exceeded — paginate with narrower from/to windows. schema: type: integer format: int64 example: 1718313600000 to: name: to in: query description: End time as Unix milliseconds. Defaults to now. schema: type: integer format: int64 example: 1718400000000 address: name: address in: query description: Wallet address filter (hex string, e.g. `0xabc123`). schema: type: string example: '0xabc123def456' limit: name: limit in: query description: Maximum number of results per page. Default 100, max 1000. schema: type: integer default: 100 maximum: 1000 example: 100 cursor: name: cursor in: query description: >- Opaque pagination cursor from `pagination.next_cursor` in a previous response. schema: type: string example: MTcxODQwMDAwMDAwMC00Mg== schemas: TradeList: type: object required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/Trade' pagination: $ref: '#/components/schemas/Pagination' Trade: type: object required: - source - market - issuer - base_market - market_type - timestamp - block_number - sequence - price - size - side - address - fee - realized_pnl - hash properties: source: type: string example: hyperliquid market: type: string description: >- Full market identifier. Native HL perps use the base symbol (e.g. `BTC-PERP`); HIP-3 builder-deployed markets are namespaced as `:` (e.g. `flx:GAS-PERP`). example: BTC-PERP issuer: type: string description: HIP-3 builder/issuer namespace. Empty string for native HL markets. example: '' base_market: type: string description: >- Base market symbol with any issuer namespace stripped. Equal to `market` for native HL perps. example: BTC-PERP market_type: type: string enum: - perp - spot example: perp timestamp: type: integer format: int64 description: Unix milliseconds. example: 1718400000000 block_number: type: integer format: int64 example: 12345678 sequence: type: integer format: int64 description: Monotonically increasing sequence number within the block. example: 42 price: type: string description: Trade price as a decimal string. example: '67432.10' size: type: string description: Trade size as a decimal string. example: '1.5' side: type: string enum: - buy - sell example: buy address: type: string description: Taker address for trades, account address for fills. example: '0xabc123' fee: type: string description: Fee paid in USD as a decimal string. example: '0.38' realized_pnl: type: string description: Realized PnL for this trade in USD. "0" for market trades. example: '0' hash: type: string description: Transaction hash. example: '0x9f1a2b' venue: type: string description: Venue identifier (HIP-3 cutover, 2026-04-27). example: hyperliquid market_class: type: string enum: - perp - spot - prediction - option description: Market class discriminator. example: perp market_id: type: integer format: int64 description: Venue-native market id (HL asset id for perps). example: 0 quote_asset: type: string description: Quote asset symbol. example: USD display_symbol: type: string description: Display symbol (same as `market`). example: BTC-PERP notional: type: string description: Notional value (`price * size`) of the fill. example: '101148.15' oid: type: integer format: int64 description: HL order id. example: 9876543 tid: type: integer format: int64 description: HL trade id. example: 1234567 fee_token: type: string description: Fee currency token. example: USDC liquidation: type: boolean description: True if this fill is the result of a liquidation. example: false Pagination: type: object required: - next_cursor - has_more properties: next_cursor: type: string nullable: true description: >- Cursor to pass as `cursor` query parameter to fetch the next page. Null when no more pages. example: MTcxODQwMDAwMDAwMC00Mg== has_more: type: boolean description: Whether more pages are available. example: true 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. responses: QueryWindowExceeded: description: >- Time range exceeds the per-request maximum for the caller's tier. Narrow the from/to window and paginate. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: QUERY_WINDOW_EXCEEDED message: >- query time range exceeds maximum 24h0m0s per request for your tier — narrow your from/to window and paginate Unauthorized: description: Missing or invalid API key. headers: WWW-Authenticate: schema: type: string example: Bearer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid or missing API key Forbidden: description: Your tier does not include this feature. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TIER_FORBIDDEN message: Export requires Builder tier or above RateLimited: description: Rate limit exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Retry after 60 seconds. 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.