@somnia-chain/markets-sdk / index / PerpPositionMetrics
Interface: PerpPositionMetrics
Defined in: packages/sdk/src/perp/margin.ts:786
One position, marked to the current mark and funding index.
Properties
size
size:
bigint
Defined in: packages/sdk/src/perp/margin.ts:788
SIGNED size, raw base units — echoed so a result stands alone.
notional
notional:
bigint
Defined in: packages/sdk/src/perp/margin.ts:790
|size| × mark / oneBase, raw collateral units. Zero when flat.
unrealizedPnl
unrealizedPnl:
bigint
Defined in: packages/sdk/src/perp/margin.ts:798
Mark-to-market PnL on price alone, signed: (mark − entry) × size / oneBase.
Excludes funding, deliberately — see accruedFunding. Truncates toward
zero, matching PerpMath.unrealizedPnl's plain int256 division, which is NOT
the rounding the funding leg uses.
accruedFunding
accruedFunding:
bigint
Defined in: packages/sdk/src/perp/margin.ts:816
Funding owed since the position's entry index, signed and raw collateral units. Positive means the account pays; negative means it receives.
Sign is the contract's, not a display convention, and it is the opposite of unrealizedPnl's: this is a payment, so it is SUBTRACTED to reach equityContribution. Rendering it beside PnL without flipping it shows a cost as a gain.
Includes unsettled intervals, because it is computed against the pool's projected cumulative index rather than its last settled one — settlement is permissionless and lazy, so the settled index can lag by hours, and a position measured against it under-reports what the account already owes.
Ceils toward +∞ (divCeilInt), so a payer pays at least what is owed and a
receiver receives at most it.
equityContribution
equityContribution:
bigint
Defined in: packages/sdk/src/perp/margin.ts:824
This position's contribution to account equity: unrealizedPnl − accruedFunding.
The figure the MarginBank actually sums. Across every active market these add to
equity − collateral, exactly — which is the invariant that makes this a port of
the contract rather than a re-derivation of it.
initialMarginRequirement
initialMarginRequirement:
bigint
Defined in: packages/sdk/src/perp/margin.ts:839
This position's share of the account's initial-margin requirement:
ceil(notional × effectiveImfBps / 10000).
This is "position margin" in the only sense the protocol defines one. Margin is cross, so no collateral is segregated per position and there is nothing to read; what a position does have is the requirement it adds to the account.
Note it uses the market's IMF only. An account leverage setting stricter than the
market's IMF raises the bar for a NEW order (MarginBank._meetsIM) but does not
appear here, because _marketHealthFromSnapshot does not apply it — health,
liquidation and equity are all measured without it. Use
SomniaMarketsClient.previewPerpOrderMargin for the order-gating figure.
maintenanceMarginRequirement
maintenanceMarginRequirement:
bigint
Defined in: packages/sdk/src/perp/margin.ts:841
ceil(notional × maintenanceMarginBps / 10000) — the liquidation threshold's share.
closeOutMarginRequirement
closeOutMarginRequirement:
bigint
Defined in: packages/sdk/src/perp/margin.ts:843
ceil(notional × closeOutMarginBps / 10000) — the takeover threshold's share.
returnOnMarginBps
returnOnMarginBps:
bigint|null
Defined in: packages/sdk/src/perp/margin.ts:860
equityContribution over initialMarginRequirement, in bps — "this position has returned N% of the margin it ties up".
Net of funding, because funding is a real cost of holding the position and a
gross figure flatters a position that is up on price and bleeding carry. For the
price-only ratio, use unrealizedPnl × 10000n / initialMarginRequirement.
null whenever initialMarginRequirement is zero and the ratio is
therefore undefined — not 0n, which would read as a real break-even. That is a
flat position in the ordinary case, and also a dust one whose notional
floors to zero, which the protocol likewise asks no margin for.
Floors (toward −∞) rather than truncating, so a loss never rounds toward looking smaller than it is.