Struct PerpetualPosition 

pub struct PerpetualPosition {
    pub symbol: String,
    pub quantity: Positive,
    pub entry_price: Positive,
    pub side: Side,
    pub leverage: Positive,
    pub margin: Positive,
    pub margin_type: MarginType,
    pub funding_rate: Decimal,
    pub date: DateTime<Utc>,
    pub fees: Positive,
}

Represents a perpetual swap contract position.

Perpetual swaps are derivative contracts common in cryptocurrency markets that allow traders to speculate on price movements with leverage, without an expiration date. They use a funding rate mechanism to keep the contract price anchored to the spot price.

Fields

• symbol - Trading pair (e.g., “BTC-USDT-PERP”)
• quantity - Position size in base currency
• entry_price - Average entry price
• side - Long or Short position
• leverage - Applied leverage (1x to 125x typical)
• margin - Collateral posted for this position
• margin_type - Cross or Isolated margin mode
• funding_rate - Current funding rate (updated periodically)
• date - Position open timestamp
• fees - Trading fees (maker/taker)

Fields

symbol: String

Trading pair symbol (e.g., “BTC-USDT-PERP”).

quantity: Positive

Position size in base currency units.

entry_price: Positive

Average entry price for the position.

side: Side

Position direction (Long or Short).

leverage: Positive

Leverage multiplier applied to the position.

margin: Positive

Margin/collateral posted for this position.

margin_type: MarginType

Margin mode (Cross or Isolated).

funding_rate: Decimal

Current funding rate as a decimal (e.g., 0.0001 = 0.01%).

date: DateTime<Utc>

Timestamp when the position was opened.

fees: Positive

Total trading fees paid.

Implementations

impl PerpetualPosition

pub const DEFAULT_FUNDING_INTERVAL_HOURS: u32 = 8

Default funding interval in hours (8 hours for most exchanges).

pub const DEFAULT_MAINTENANCE_MARGIN_RATIO: Decimal = Decimal::ONE_HUNDRED

Default maintenance margin ratio (typically 0.5% to 1%).

pub fn new( symbol: String, quantity: Positive, entry_price: Positive, side: Side, leverage: Positive, margin: Positive, margin_type: MarginType, funding_rate: Decimal, date: DateTime<Utc>, fees: Positive, ) -> Self

Creates a new perpetual position.

Arguments

• symbol - Trading pair symbol
• quantity - Position size in base currency
• entry_price - Average entry price
• side - Long or Short
• leverage - Leverage multiplier
• margin - Collateral posted
• margin_type - Cross or Isolated
• funding_rate - Current funding rate
• date - Position open timestamp
• fees - Trading fees

pub fn long( symbol: String, quantity: Positive, entry_price: Positive, leverage: Positive, margin: Positive, ) -> Self

Creates a long perpetual position with default settings.

Arguments

• symbol - Trading pair symbol
• quantity - Position size
• entry_price - Entry price
• leverage - Leverage multiplier
• margin - Collateral posted

pub fn short( symbol: String, quantity: Positive, entry_price: Positive, leverage: Positive, margin: Positive, ) -> Self

Creates a short perpetual position with default settings.

Arguments

• symbol - Trading pair symbol
• quantity - Position size
• entry_price - Entry price
• leverage - Leverage multiplier
• margin - Collateral posted

pub fn notional_value_at_entry(&self) -> Positive

Returns the notional value of the position.

Notional = quantity × entry_price

pub fn notional_value_at_price(&self, current_price: Positive) -> Positive

Returns the current notional value at a given price.

Arguments

• current_price - Current market price

pub fn unrealized_pnl( &self, current_price: Positive, ) -> Result<Decimal, PricingError>

Calculates the unrealized P&L at a given price.

Arguments

• current_price - Current market price

Decision (issue #471): fallible because pnl_at_price is

This is the whole body of LegAble::pnl_at_price for a perpetual, so leaving it infallible would have moved that method’s abort one frame down rather than removing it. entry_price and quantity are pub, so no constructor guard bounds the product.

Errors

Returns PricingError::Decimal when the price difference or the quantity scaling leaves the representable Decimal range.

pub fn roe_percentage( &self, current_price: Positive, ) -> Result<Decimal, PricingError>

Calculates the ROE (Return on Equity) percentage.

ROE = (Unrealized P&L / Margin) × 100

A zero margin has no return on equity to report, and the function keeps its existing answer of Decimal::ZERO for that case rather than turning it into an error.

Arguments

• current_price - Current market price

Errors

Propagates PerpetualPosition::unrealized_pnl, and returns PricingError::Decimal when the ratio or its percentage scaling leaves the representable Decimal range.

pub fn margin_ratio( &self, current_price: Positive, ) -> Result<Decimal, PricingError>

Calculates the margin ratio at a given price.

Margin Ratio = (Margin + Unrealized P&L) / Notional Value

A zero notional has no margin ratio to report, and the function keeps its existing answer of Decimal::ZERO for that case rather than turning it into an error.

Arguments

• current_price - Current market price

Errors

Propagates PerpetualPosition::unrealized_pnl, and returns PricingError::Decimal when the equity sum or the ratio leaves the representable Decimal range.

pub fn update_funding_rate(&mut self, new_rate: Decimal)

Updates the funding rate.

Arguments

• new_rate - New funding rate

pub fn effective_leverage( &self, current_price: Positive, ) -> Result<Decimal, PricingError>

Calculates the effective leverage at a given price.

Effective Leverage = Notional Value / (Margin + Unrealized P&L)

A position whose equity has been wiped out is infinitely levered, and the function keeps its existing answer of Decimal::MAX for that case rather than turning it into an error.

Arguments

• current_price - Current market price

Errors

Propagates PerpetualPosition::unrealized_pnl, and returns PricingError::Decimal when the equity sum or the quotient leaves the representable Decimal range.

Trait Implementations

impl Clone for PerpetualPosition

fn clone(&self) -> PerpetualPosition

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ComposeSchema for PerpetualPosition

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

impl Debug for PerpetualPosition

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PerpetualPosition

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for PerpetualPosition

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for PerpetualPosition

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<PerpetualPosition> for Leg

fn from(position: PerpetualPosition) -> Self

Converts to this type from the input type.

impl Fundable for PerpetualPosition

fn funding_rate(&self) -> Decimal

Returns the current funding rate (as a decimal, e.g., 0.0001 = 0.01%).

fn funding_interval_hours(&self) -> u32

Returns the funding interval in hours (typically 8 for most exchanges).

fn funding_payment(&self, mark_price: Positive) -> Decimal

Calculates the funding payment for the current period.

fn annualized_funding(&self, mark_price: Positive) -> Decimal

Calculates the annualized funding cost/income.

impl LegAble for PerpetualPosition

fn get_symbol(&self) -> &str

Returns the symbol/ticker of the underlying instrument.

fn get_quantity(&self) -> Positive

Returns the position quantity (number of units/contracts).

fn get_side(&self) -> Side

Returns the position side (Long or Short).

fn pnl_at_price(&self, price: Positive) -> Result<Decimal, PricingError>

Calculates the profit/loss at a given price.

fn total_cost(&self) -> Result<Positive, PositionError>

Returns the total cost to establish this position.

fn fees(&self) -> Result<Positive, PositionError>

Returns the total fees associated with this position.

fn delta(&self) -> Result<Decimal, GreeksError>

Returns the delta of this position.

fn theta(&self) -> Result<Decimal, GreeksError>

Returns the theta of this position.

fn gamma(&self) -> Result<Decimal, GreeksError>

Returns the gamma of this position.

fn vega(&self) -> Result<Decimal, GreeksError>

Returns the vega of this position.

fn rho(&self) -> Result<Decimal, GreeksError>

Returns the rho of this position.

fn is_long(&self) -> bool

Checks if this is a long position.

fn is_short(&self) -> bool

Checks if this is a short position.

fn notional_value(&self, price: Positive) -> Positive

Returns the notional value of the position at a given price.

impl Marginable for PerpetualPosition

fn initial_margin(&self) -> Positive

Returns the initial margin requirement.

fn maintenance_margin(&self) -> Positive

Returns the maintenance margin requirement.

fn leverage(&self) -> Positive

Returns the current leverage applied to the position.

fn liquidation_price(&self, _current_price: Positive) -> Positive

Calculates the liquidation price for this position.

fn is_liquidation_risk( &self, current_price: Positive, _margin_ratio: Decimal, ) -> bool

Checks if the position is at risk of liquidation.

impl PartialEq for PerpetualPosition

fn eq(&self, other: &PerpetualPosition) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for PerpetualPosition

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for PerpetualPosition

impl ToSchema for PerpetualPosition

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.