Skip to main content
Use account reads to turn Perps activity into a reliable local view of account health, trading history, and performance.
Owner account reads use an authenticated session. Position snapshots also support public reads.

​
Review Account Health

Start with the account’s current collateral and exposure when showing portfolio health or checking whether a trade fits the account’s risk state.

​
Balances

Use balances to show collateral by asset and account value.
Use this shape to render collateral balances and account value by asset.

​
Portfolio

Use the portfolio to show open positions, margin usage, withdrawable collateral, and liquidation state.
Use this shape to render positions, margin usage, and liquidation state.

​
Account Stats

Use account stats to review trailing 7-day trading activity such as volume and maker share. Stats are cached by UTC day and may be stale by up to 24 hours. See Fee Metrics for what each metric means.
Use this shape to render trailing 7-day volume and maker-share activity.

​
Reconcile Orders and Fills

Use order state and fills to connect submitted orders with resting liquidity, executions, fees, and exposure changes.

​
Open Orders

Use open orders to show what is still resting on the book.
Use this shape to render resting orders that can still fill or be canceled.

​
Orders

Use orders to inspect the latest known state for submitted orders.
Use this shape to reconcile submitted orders with their latest known state.

​
Fills

Use fills to reconcile executions, fees, realized PnL, and exposure changes.
Each page returns execution records you can use to reconcile fees, PnL, and exposure.
settlement: true identifies a position close at the final instrument-settlement price. The same flag is available on each fill in a session "fill" event payload; it defaults to false on older responses.
Settlement fills carry no fees or liquidation penalties. Reconcile them as position closures, separately from ordinary market executions and ADL.

​
Inspect Position Snapshots

Inspect a position now or immediately after a selected fill. Each snapshot covers one position cycle, from opening until the position becomes flat or changes side. Select up to 20 active instruments and 4 historical fills in one request, with at least one selection. Results keep the selection order within each group.
Use the existing authenticated session to read your own positions. The example selects instrument 1; replace it with the instrument you want to inspect.
A successful active selection returns:
For Ok, snapshot is a PerpsPositionSnapshot. Financial values such as pnl use DecimalString; timestamps are Unix milliseconds. pnlPercent and leverage can be null.
To inspect the fill shown in the Fills example, add historyFills. Keep the original decimal trade ID as a string; do not round it through a JavaScript number.
For a public read, call client.fetchPerpsPositionSnapshots({ address, activeInstrumentIds: [1] }) with a createPublicClient() instance and the registered account’s address. This method does not add session credentials, including when inherited by a secure client.

​
Interpret a Snapshot

While a cycle remains open, PnL is gross unrealized profit or loss on its remaining size. After it closes, PnL is the gross realized total for that cycle. Both exclude fees, funding, and previous cycles. A fill that closes or flips a position returns the closed cycle; the new cycle appears in the active selection or its later fills. Leverage and PnL percentage are visible only to the authenticated owner. Historical leverage uses the value captured at the selected fill and can remain unavailable. PnL percentage uses nominal entry margin, so it can differ from portfolio return on equity. Chart candles and markers use numeric coordinates and approximate prices; the selected minute’s candle includes the whole minute’s aggregate.

​
Handle Unavailable Selections

Only successful selections contain a snapshot. The completed-history horizon indicates how far the serving gateway has processed history; gateways can report different horizons. Handle each selection independently instead of discarding the whole batch when one selection is unavailable. Reconstruction limits and unsafe-accounting results are not signals to poll indefinitely.

​
Reconcile Funding and Transfers

Funding, deposits, and withdrawals explain collateral changes that did not come from order fills. Use Fund Your Account for deposit and withdrawal submission workflows.

​
Funding Payments

Use funding payments to explain periodic funding debits or credits for a market.
Each page returns funding records you can use to explain non-trade PnL changes. Each record has a unique id for storing or deduplicating funding payments.

​
Deposits

Use deposits to reconcile collateral added to the Perps account.
Each page returns deposits you can match against collateral arriving in the account.

​
Withdrawals

Use withdrawals to reconcile collateral leaving the Perps account.
Each page returns withdrawals you can match against collateral leaving the account.
Branch on status using the PerpsKnownWithdrawalStatus enum.The status set can grow between SDK releases. status is typed PerpsWithdrawalStatus, so a status added after your release arrives as a plain string instead of failing the response parse.

​
Track Equity and PnL

Use equity and PnL history to explain how the account’s value changed over time.

​
Equity

Use equity history to chart account value over time. Each point is the last equity sample in its interval bucket, stamped with that sample’s own timestamp. A coarser interval lets each 1000-point page cover a longer window before more is set.
Each page returns points you can plot as account equity over time.

​
PnL

Use PnL history to chart account profit and loss over the same interval. Each point is the PnL realized inside its interval bucket — not a running total — and buckets in which nothing was realized are omitted, so the series is sparse.
Each page returns points you can plot as account PnL over time.