> ## 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 funding payments by address

> GET /v1/analytics/user-funding returns daily or hourly funding payments per market for a Hyperliquid address, taken from Hyperliquid's own userFunding ledger.

## When to use

`user-funding` quantifies the **carry leg** of an address's perp
strategy. Every perp position pays or receives funding at each
funding interval (HL: 1 hour). Holding a long during a positive
funding regime means paying; holding a short means receiving (and
vice versa).

Use this endpoint to:

* Compute total funding income / expense for a given window
* Compare funding P\&L vs trading P\&L for a market maker
* Backtest a funding-arb strategy

For raw per-event funding rate data (market-wide, not per-address),
use [`/v1/funding`](/api-reference/market-data/list-funding-rates).

## Conventions

* `funding_payment` is **signed**: positive = received, negative = paid
  (matches HL's `userFunding.delta.usdc` and dYdX v4
  `fundingPayments.payment`).
* `bucket=1h` matches HL's native funding interval — one row per
  funding event.
* `bucket=1d` aggregates 24 hourly intervals into one daily row;
  `interval_count` carries the number of intervals rolled up.
* `bucket=raw` is currently equivalent to `1h`; reserved for future
  sub-hour intervals if HL ever ships them.

## Compute basis

`funding_payment` is derived from `fills` (the address's running
position) joined against `funding_rates` (the market's hourly rate)
at each funding interval. No information is read from a separate HL
endpoint — this is computed entirely from the data we already ingest,
which means accuracy depends on the address having complete fill
coverage in our window.

## Example

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


## OpenAPI

````yaml GET /v1/analytics/user-funding
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-funding:
    get:
      tags:
        - Analytics
      summary: Funding payments per market per bucket
      description: |
        Daily or hourly funding payments per market for an address, sourced
        from Hyperliquid's own `userFunding` ledger for that address (exact
        payments, native and HIP-3 perps).

        Sign convention: `funding_payment` is signed — positive = received,
        negative = paid. This matches HL `userFunding.delta.usdc` and dYdX
        v4 `fundingPayments.payment`.

        `bucket=1h` sums payments per hour, `bucket=1d` per UTC day, and
        `bucket=raw` returns every payment. Default `1d`.
      operationId: getUserFunding
      parameters:
        - $ref: '#/components/parameters/address'
        - $ref: '#/components/parameters/market'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - name: bucket
          in: query
          schema:
            type: string
            enum:
              - 1h
              - 1d
              - raw
            default: 1d
      responses:
        '200':
          description: Funding payments aggregated per the chosen bucket.
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  from:
                    type: integer
                    format: int64
                  to:
                    type: integer
                    format: int64
                  bucket:
                    type: string
                    enum:
                      - 1h
                      - 1d
                      - raw
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserFundingPayment'
        '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:
    UserFundingPayment:
      type: object
      description: >-
        One bucket of funding payments. `funding_payment` is signed — positive =
        received, negative = paid.
      required:
        - bucket_start
        - market
        - market_class
        - funding_payment
        - avg_position
        - avg_funding_rate
        - interval_count
      properties:
        bucket_start:
          type: integer
          format: int64
          description: Unix ms — bucket boundary (UTC)
          example: 1779302400000
        market:
          type: string
          example: BTC-PERP
        market_class:
          type: string
          enum:
            - perp
          example: perp
        funding_payment:
          type: number
          format: double
          description: Signed USDC; + received, - paid
          example: 5.23
        avg_position:
          type: number
          format: double
          description: Mean signed position over the bucket
          example: 0.1
        avg_funding_rate:
          type: number
          format: double
          example: 0.0000125
        interval_count:
          type: integer
          description: Number of funding intervals in the bucket
          example: 24
    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.