Skip to main content
GET
Non-fill ledger events for an address

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 (positions) and /v1/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

Authorizations

Authorization
string
header
required

Ironflow API key, format if_xxxx. Free keys at https://ironflow.sh/key. Optional on read endpoints.

Query Parameters

address
string

Wallet address filter (hex string, e.g. 0xabc123).

Example:

"0xabc123def456"

from
integer<int64>

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.

Example:

1718313600000

to
integer<int64>

End time as Unix milliseconds. Defaults to now.

Example:

1718400000000

event_types
string

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.

Example:

"deposit,withdrawal,rewards_claim"

limit
integer
default:100

Maximum number of results per page. Default 100, max 1000.

Required range: x <= 1000
Example:

100

Response

Ledger entries newest-first.

address
string
from
integer<int64>
to
integer<int64>
data
object[]