Perpetual Futures Data: Positions, Funding and PnL Records
Keep trades, open positions, funding observations and valuation calculations separate when building a derivatives data view.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Perpetual futures data can include orders, trades, open positions, collateral, funding and profit-and-loss observations. A trading interface may combine these into one account summary, but the records answer different questions and can use different observation times or calculation methods.
A useful analytical integration preserves the instrument and account context before deriving a concise result. It separates technical execution records, position state and valuation inputs, making it possible to explain a changed quantity or PnL figure without assuming that every movement in the summary represents a new trade or cash transfer.
Retain instrument identity and contract units
A familiar market symbol does not fully describe a derivatives instrument. Keep the platform or network context, instrument reference and documented quantity or contract-unit conventions. An underlying asset name alone cannot establish that two position quantities are comparable.
Retain the specification version relevant to the observation. If a dataset normalizes several instrument models, keep original units and supported conversion rules beneath the shared shape. A synthetic case can use two instruments with the same display label and different quantity conventions. The application should preserve distinct identities through storage, valuation and export rather than summing their apparent sizes into one undefined position merely because a dashboard groups them under the same asset name.
Keep orders, fills and position snapshots distinct
An order can be unfilled, partially filled or associated with several execution observations. A position snapshot describes accepted state at a boundary. Neither should be substituted for the other when building activity history or calculating a position change.
Preserve stable fill identifiers and the relationship to the order and account. Test a partial fill, a cancelled remainder and repeated retrieval of an accepted execution. Deduplication should retain each execution once without collapsing several fills into one simply because they belong to the same order. A current position can then be compared with retained activity under a documented scope, while unresolved historical intervals remain visible instead of being reconstructed from a single snapshot.
Represent funding as its own observation stream
Funding records can affect a position or account calculation without being ordinary trade executions. Keep their instrument, account, period or observation reference, quantity unit and sign convention separate from fill quantities and fees.
The Hyperliquid funding documentation provides one primary mechanism example. A generic integration still needs its selected interface contract and accepted observation boundary. Test a funding record arriving between two position snapshots without a new trade. The application should explain its effect under the declared calculation policy rather than inventing a fill or labeling every account-value change as realized trading profit. Preserve unresolved periods instead of assuming no observed record means zero funding.
Name the price input used by each calculation
Last trade, mark and reference prices can serve different roles under an instrument's contract. Retain the specific observation type, timestamp and unit used by a calculation. A familiar field called price should not silently switch between them across views.
A synthetic linear-contract example can compare one declared unit with an entry observation of 100 and a valuation observation of 105, giving a five-unit difference before separately defined fees and funding. This illustrates the need to preserve calculation assumptions; it is not a universal contract formula. Other instrument models need their own supported method. Keep the original observations so a changed valuation input can be explained without rewriting trade history.
Separate realized results, unrealized values and account flows
A displayed PnL field can include or exclude different components. Retain the method, entry or cost convention, quantity context and treatment of fees and funding. Keep external collateral movements separate so they are not mistaken for trading results.
The Hyperliquid liquidation documentation illustrates that position and account state can interact under platform-specific rules. A data view should not infer a complete risk or liquidation outcome from one isolated field. Test an unchanged position with a new valuation, a collateral contribution and a funding observation. The result should identify which component changed instead of collapsing all three into an unexplained gain or loss headline.
Make derivatives datasets reproducible and bounded
Retain the account and instrument population, requested interval, accepted executions, position snapshots and unresolved scope. Keep original quantities and calculation versions through exports. A successful current-state query does not establish every historical trade, funding event or account adjustment.
Test repeated fills, missing funding periods, changed valuation observations and an unsupported instrument convention using synthetic records. Useful derivatives data supports an inspectable analytical view while keeping execution and application-specific financial decisions separate. A consumer should be able to reproduce the included calculation, locate its evidence and understand which components remain unknown rather than treating a concise account summary as a complete explanation of every position, cash movement and future outcome.
Questions about the topic
Frequently asked questions
Is a position snapshot a full trade history?
No. It describes state under a selected contract and boundary. Preserve executions, funding and other relevant observations separately, together with the inspected historical scope.
Should funding be stored as another trade?
Keep it as its documented observation type with instrument, account, period and quantity context. A calculation can combine compatible components without erasing their distinct meanings.
Can all PnL fields be compared directly?
Only after aligning instrument units, price inputs, quantity conventions and treatment of fees, funding and flows. Preserve the method and original observations behind each figure.
Standards & technical documentation
