> ## 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 maker and taker breakdown by address

> GET /v1/analytics/user-maker-taker splits a Hyperliquid address's fills, notional and fees into maker and taker per market over a time window, rebates included.

## When to use

`user-maker-taker` is the **single most diagnostic endpoint** for
analysing how an address transacts on Hyperliquid:

* A **high maker share with negative `maker_fee`** is the textbook
  signature of a market maker — they're providing liquidity and
  collecting rebates.
* A **high taker share with positive `taker_fee`** is the signature
  of a taker bot or whale paying the spread for execution.
* A **mixed profile** can indicate an arbitrageur, a basis trader,
  or a hybrid strategy.

The underlying signal is the `crossed` field on every Hyperliquid
fill (`crossed: true` = taker, `false` = maker). No other commercial
data provider exposes this aggregated per-address — Tardis ships
raw fills only; Coinglass and Nansen ship clearinghouseState only;
the HL `/info` API requires the consumer to reduce `userFills`
themselves over potentially millions of rows.

## Conventions

* `maker_fills` / `taker_fills` are counts of HL fills.
* `maker_notional` / `taker_notional` are USDC notional (price × size).
* `maker_fee` is **often negative** — that's the rebate HL pays to
  resting orders that get hit. `taker_fee` is positive (the fee
  takers pay).
* `pct_maker = maker_fills / total_fills`, a number in `[0, 1]`.
* The response envelope's `total` row sums all per-market rows.

## Historical caveat (read carefully)

The underlying `fills.crossed` column was added to ClickHouse on
**2026-05-21**. Fills ingested before that timestamp default to
`crossed = false` (maker) because we didn't carry the field through
the parser. **Until the S3 backfill completes**, queries spanning
windows before 2026-05-21 will over-count maker fills.

Backfill plan: `hl-recovery --rebuild` replays the S3 archive (HL
public node data, back to 2025-07-27) through the updated parser to
repopulate `crossed` on every historical fill.

## Example

```bash theme={null}
# Last 7 days, all markets
curl -H "Authorization: Bearer $IRONFLOW_API_KEY" \
  "https://api.ironflow.sh/v1/analytics/user-maker-taker?address=0x0c684f...&from=$(date -u -v-7d +%s)000&to=$(date -u +%s)000"

# One market only
curl -H "Authorization: Bearer $IRONFLOW_API_KEY" \
  "https://api.ironflow.sh/v1/analytics/user-maker-taker?address=0x0c684f...&market=BTC-PERP&from=...&to=..."
```


## OpenAPI

````yaml GET /v1/analytics/user-maker-taker
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/analytics/user-maker-taker:
    get:
      tags:
        - Analytics
      summary: Maker vs taker fill breakdown per market
      description: |
        Per-market breakdown of an address's maker vs taker fills, notional,
        and fees over a time window. The single most diagnostic field for
        market-maker analysis: a high maker share with negative
        `maker_fee` (rebate) is a textbook MM strategy; high taker share
        with positive fees is liquidity-taking flow.

        **Historical caveat:** the underlying `fills.crossed` column was
        added 2026-05-21. Fills ingested before that timestamp default to
        `crossed=0` (maker) until the S3 backfill repopulates them. Until
        backfill completes, queries spanning windows before 2026-05-21 will
        over-count maker fills. The `data` array's window is reflected in
        the response envelope's `from`/`to`.
      operationId: getUserMakerTaker
      parameters:
        - $ref: '#/components/parameters/address'
        - $ref: '#/components/parameters/market'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
      responses:
        '200':
          description: Per-market maker/taker breakdown + totals row.
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  from:
                    type: integer
                    format: int64
                  to:
                    type: integer
                    format: int64
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserMakerTakerBreakdown'
                  total:
                    $ref: '#/components/schemas/UserMakerTakerBreakdown'
        '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:
    address:
      name: address
      in: query
      description: Wallet address filter (hex string, e.g. `0xabc123`).
      schema:
        type: string
        example: '0xabc123def456'
    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
    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
  schemas:
    UserMakerTakerBreakdown:
      type: object
      required:
        - market
        - market_class
        - maker_fills
        - taker_fills
        - maker_notional
        - taker_notional
        - maker_fee
        - taker_fee
        - total_fills
        - pct_maker
      properties:
        market:
          type: string
          example: HYPE-PERP
        market_class:
          type: string
          enum:
            - perp
            - spot
            - prediction
            - option
          example: perp
        maker_fills:
          type: integer
          format: int64
          example: 1234
          description: Fills where the address provided liquidity (crossed=false)
        taker_fills:
          type: integer
          format: int64
          example: 567
          description: Fills where the address crossed the spread (crossed=true)
        maker_notional:
          type: number
          format: double
          example: 1000000
        taker_notional:
          type: number
          format: double
          example: 500000
        maker_fee:
          type: number
          format: double
          description: Sum of fee on maker fills (often negative = rebate)
          example: -50
        taker_fee:
          type: number
          format: double
          example: 200
        total_fills:
          type: integer
          format: int64
          example: 1801
        pct_maker:
          type: number
          format: double
          description: '[0, 1]'
          example: 0.685
    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.