> ## 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 deposits, withdrawals and ledger events

> GET /v1/analytics/user-ledger returns non-fill ledger events for a Hyperliquid address: deposits, withdrawals, vault operations, transfers and staking.

## When to use

`user-ledger` returns the events that move balance into or out of an
address other than fills and funding payments. Use it to reconcile
account-level cash flow alongside [`/v1/analytics/user-state`](/api-reference/analytics/user-state)
(positions) and [`/v1/analytics/user-funding`](/api-reference/analytics/user-funding)
(carry).

## Conventions

* `amount` is **signed**: positive = into the account (deposit, vault
  withdrawal, transfer in, airdrop claim), negative = out (withdrawal,
  vault deposit, transfer out, stake delegate).
* `type` is a discriminator. Always-supported values from the live
  tailer:
  * `deposit`, `withdrawal` — USDC bridge in / out
  * `vault_deposit`, `vault_withdraw`, `vault_transfer_in`, `vault_transfer_out`, `vault_distribute`, `vault_commission` — vault operations
  * `send` — user-to-user transfer (USDC bridge address-to-address)
  * `spot_send` — user-to-user transfer of a spot token
  * `account_class_transfer` — internal perp ↔ spot wallet move (`details.to_perp` carries the direction)
  * `rewards_claim` — HYPE airdrop / staking reward claim
  * `delegate`, `undelegate` — HYPE staking lock / unlock (`details.validator`)
  * `sub_account_transfer` — transfer between a main wallet and one of its subaccounts
  * `c_deposit`, `c_withdraw` — HL native L1 bridge events
* `details` (when present) is a free-form object with type-specific
  fields: `to_perp` for `account_class_transfer`, `validator` /
  `wei` for `delegate`/`undelegate`, etc.

## Coverage

The endpoint UNIONs four ClickHouse tables: `deposits`, `withdrawals`,
`vault_operations` (USDC + vault flows, archive depth back to the per-
table start dates documented on the pricing footnote), and
`ledger_entries` (catch-all for the misc-events `LedgerUpdate` delta
types — `send`, `spot_send`, `account_class_transfer`, `rewards_claim`,
`delegate`, `undelegate`, `sub_account_transfer`, `c_deposit`,
`c_withdraw`). `ledger_entries` is forward-only from 2026-05-21; an
S3 backfill of the misc-events archive against the existing
`hl-recovery` orchestrator is planned but not yet executed.

## Example

```bash theme={null}
# All ledger events in the last 30 days
curl -H "Authorization: Bearer $IRONFLOW_API_KEY" \
  "https://api.ironflow.sh/v1/analytics/user-ledger?address=0x0c684f...&from=$(date -u -v-30d +%s)000&to=$(date -u +%s)000"

# Withdrawals only
curl -H "Authorization: Bearer $IRONFLOW_API_KEY" \
  "https://api.ironflow.sh/v1/analytics/user-ledger?address=0x0c684f...&event_types=withdrawal"
```


## OpenAPI

````yaml GET /v1/analytics/user-ledger
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-ledger:
    get:
      tags:
        - Analytics
      summary: Non-fill ledger events for an address
      description: |
        Ledger of events affecting an address's balance other than fills:
        USDC deposits/withdrawals, vault operations, plus the misc-events
        `LedgerUpdate` catch-all (sends, account-class transfers, HYPE
        airdrops, HYPE staking delegate/undelegate, subaccount transfers,
        L1 bridge events). Mirrors HL's `userNonFundingLedgerUpdates`
        envelope shape with a `type` discriminator.

        Sign convention: `amount` is signed — positive = into the account,
        negative = out.

        The misc-events catch-all is forward-only from 2026-05-21; an S3
        backfill via the existing `hl-recovery` orchestrator is planned
        but not yet executed.
      operationId: getUserLedger
      parameters:
        - $ref: '#/components/parameters/address'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - name: event_types
          in: query
          description: |
            Comma-separated list of types to include. Supported values:
            `deposit`, `withdrawal`, `vault_deposit`, `vault_withdraw`,
            `vault_transfer_in`, `vault_transfer_out`, `vault_distribute`,
            `vault_commission`, `send`, `spot_send`,
            `account_class_transfer`, `rewards_claim`, `delegate`,
            `undelegate`, `sub_account_transfer`, `c_deposit`,
            `c_withdraw`.
          schema:
            type: string
            example: deposit,withdrawal,rewards_claim
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Ledger entries newest-first.
          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/UserLedgerEntry'
        '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'
    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
    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
  schemas:
    UserLedgerEntry:
      type: object
      required:
        - ts
        - type
        - token
        - amount
      properties:
        ts:
          type: integer
          format: int64
          description: Unix ms
          example: 1779302400000
        type:
          type: string
          description: Event type discriminator
          enum:
            - deposit
            - withdrawal
            - vault_deposit
            - vault_withdraw
            - vault_transfer_in
            - vault_transfer_out
            - vault_distribute
            - vault_commission
            - send
            - spot_send
            - account_class_transfer
            - rewards_claim
            - delegate
            - undelegate
            - sub_account_transfer
            - c_deposit
            - c_withdraw
        token:
          type: string
          example: USDC
        amount:
          type: number
          format: double
          description: 'Signed: + into account, - out'
          example: 1000
        tx_hash:
          type: string
          example: 0x...
          nullable: true
        details:
          type: object
          additionalProperties: true
          description: >-
            Type-specific fields (e.g. to_perp for account_class_transfer,
            validator/wei for delegate/undelegate)
    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.