Perps

The Perps Contract provides data for the Perpetual Futures platform. It returns all market states and is needed for the Credit Manager to be able to execute trigger orders.

Deployments

Neutron: neutron1g3catxyv0fk8zzsra2mjc0v4s69a7xygdjt85t54l7ym3gv0un4q2xhaf6 Perps Market API: https://backend.prod.mars-dev.net/v2/perps_market?chain=neutron

---

Types

The types of the Perps Contract can be found here.

For reference on the Queries and Methods:

Base Types

type Decimal = string
type Uint128 = string
type Int128 = string
type SignedDecimal = string

---

Queries

config

Returns the Contracts configuration.

Query message

{
    config: {}
}

Return output

{
    data: {
        address_provider: string
        base_denom: string
        cooldown_period: number
        deleverage_enabled: boolean
        max_positions: number
        max_unlocks: number
        protocol_fee_rate: Decimal
        target_vault_collateralization_ratio: Decimal
        vault_withdraw_enabled: boolean
    }
}

market

Query message

{
    market: {
        denom: string
    }
}

Return output

{
    data: {
        current_funding_rate: SignedDecimal
        denom: string
        enabled: boolean
        long_oi: Uint128
        long_oi_value: Uint128
        short_oi: Uint128
        short_oi_value: Uint128
    }
}

market_accounting

Query message

{
    market_accounting: {
        denom: string
    }
}

Return output

{
    data: {
        accounting: {
            balance: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                price_pnl: Int128
                total: Int128
            }
            cash_flow: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                price_pnl: Int128
                protocol_fee: Uint128
            }
            withdrawal_balance: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                price_pnl: Int128
                total: Int128
            }
        }
        unrealized_pnl: {
            accrued_funding: Int128
            closing_fee: Int128
            opening_fee: Int128
            pnl: Int128
            price_pnl: Int128
        }
    }
}

market_state

Query message

{
    market_state: {
        denom: string
    }
}

Return output

{
    data: {
        cash_flow: {
            accrued_funding: Int128
            closing_fee: Int128
            opening_fee: Int128
            price_pnl: Int128
            protocol_fee: Uint128
        }
        denom: string
        enabled: boolean
        funding: {
            last_funding_accrued_per_unit_in_base_denom: SignedDecimal
            last_funding_rate: SignedDecimal
            max_funding_velocity: Decimal
            skew_scale: Uint128
        }
        last_updated: number
        long_oi: Uint128
        short_oi: Uint128
        total_abs_multiplied_positions: Int256
        total_entry_cost: Int128
        total_entry_funding: Int128
        total_squared_positions: Uint256
    }
}

markets

Query message

{
    markets: {
        limit?: number | null
        start_after?: string | null
    }
}

Return output

{
    data: {
        data: [
            {
                denom: string
                enabled: boolean
                long_oi: Uint128
                long_oi_value: Uint128
                short_oi: Uint128
                short_oi_value: Uint128
                current_funding_rate: SignedDecimal
            },
            ...
        ]
    }
}

opening_fee

Query message

{
    opening_fee: {
        denom: string
        size: Int128
    }    
}

Return output

{
    data: {
        rate: SignedDecimal
        fee: {
            denom: string
            amount: Uint128
        }
    }
}

owner

Query message

{
    owner: {}
}

Return output

{
    data: {
        abolished: boolean
        emergency_owner?: string | null
        initialized: boolean
        owner?: string | null
        proposed?: string | null
    }
}

position

Query message

{
    position: {
        account_id: string
        denom: string
        order_size?: Int128 | null
        reduce_only?: boolean | null
    }
}

Return output

{
    data: {
        account_id: string
        position?: {
            base_denom: string
            current_exec_price: Decimal
            current_price: Decimal
            denom: string
            entry_exec_price: Decimal
            entry_price: Decimal
            realized_pnl: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                pnl: Int128
                price_pnl: Int128
            }
            size: Int128
            unrealized_pnl: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                pnl: Int128
                price_pnl: Int128
            }
        }
    }
}

position_fees

Query message

{
    position_fees: {
        account_id: string
        denom: string
        new_size: Int128
    }
}

Return output

{
    data: {
        base_denom: string
        closing_exec_price?: Decimal | null
        closing_fee: Uint128
        opening_exec_price?: Decimal | null
        opening_fee: Uint128
    }
}

positions

Query message

{
    positions: {
        limit?: number | null
        start_after?: [string, string] | null
    }
}

Return output

{
    data: [
        {
            account_id: string
            position?: {
                base_denom: string
                current_exec_price: Decimal
                current_price: Decimal
                denom: string
                entry_exec_price: Decimal
                entry_price: Decimal
                realized_pnl: {
                    accrued_funding: Int128
                    closing_fee: Int128
                    opening_fee: Int128
                    pnl: Int128
                    price_pnl: Int128
                }
                size: Int128
                unrealized_pnl: {
                    accrued_funding: Int128
                    closing_fee: Int128
                    opening_fee: Int128
                    pnl: Int128
                    price_pnl: Int128
                }
            }
        },
        ...
    ]
}

positions_by_account

Query message

{
    positions_by_account: {
        account_id: string
        action?: 'default' | 'liquidation' | null
    }
}

Return output

{
    data: {
        account_id: string
        positions: [
            {
                base_denom: string
                current_exec_price: Decimal
                current_price: Decimal
                denom: string
                entry_exec_price: Decimal
                entry_price: Decimal
                realized_pnl: {
                    accrued_funding: Int128
                    closing_fee: Int128
                    opening_fee: Int128
                    pnl: Int128
                    price_pnl: Int128
                }
                size: Int128
                unrealized_pnl: {
                    accrued_funding: Int128
                    closing_fee: Int128
                    opening_fee: Int128
                    pnl: Int128
                    price_pnl: Int128
                }
            },
            ...
        ]
    }
}

realized_pnl_by_account_and_market

Query message

{
    realized_pnl_by_account_and_market: {
        account_id: string
        denom: string
    }
}

Return output

{
    data: {
        accrued_funding: Int128
        closing_fee: Int128
        opening_fee: Int128
        pnl: Int128
        price_pnl: Int128
    }
}

total_accounting

Query message

{
    total_accounting: {}
}

Return output

{
    data: {
        accounting: {
            balance: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                price_pnl: Int128
                total: Int128
            }
            cash_flow: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                price_pnl: Int128
                protocol_fee: Uint128
            }
            withdrawal_balance: {
                accrued_funding: Int128
                closing_fee: Int128
                opening_fee: Int128
                price_pnl: Int128
                total: Int128
            }
        }
        unrealized_pnl: {
            accrued_funding: Int128
            closing_fee: Int128
            opening_fee: Int128
            pnl: Int128
            price_pnl: Int128
        }
    }
}

vault

Query message

{
    vault: {
        action?: 'default' | 'liquidation' | null
    }
}

Return output

{
    data: {
        collateralization_ratio?: Decimal | null
        share_price?: Decimal | null
        total_balance: Int128
        total_debt: Uint128
        total_liquidity: Uint128
        total_shares: Uint128
        total_unlocking_or_unlocked_amount: Uint128
        total_unlocking_or_unlocked_shares: Uint128
        total_withdrawal_balance: Uint128
    }
}

vault_position

Query message

{
    vault_position: {
        account_id?: string | null
        user_address: string
    }
}

Return output

{
    data: {
        denom: string
        deposit: {
              amount: Uint128
              shares: Uint128
        }
        unlocks: [
            {
                amount: Uint128
                cooldown_end: number
                created_at: number
                shares: Uint128
            },
            ...
        ]
    }
}

---

Methods

close_all_positions

Execution message

{
    close_all_positions: {
        account_id: string
        action?: 'default' | 'liquidation' | null
    }
}

deleverage

Execution message

{
    deleverage: {
        account_id: string
        denom: string
    }
}

deposit

Execution message

{
    deposit: {
        account_id?: string | null
        max_shares_receivable?: Uint128 | null
    }
}

execute_order

Execution message

{
    execute_order: {
        account_id: string
        denom: string
        reduce_only?: boolean | null
        size: Int128
    }
}

unlock

Execution message

{
    unlock: {
        account_id?: string | null
        shares: Uint128
    }
}

withdraw

Execution message

{
    withdraw: {
        account_id?: string | null
        min_receive?: Uint128 | null
    }
}

---

Audit

382KB

2024-12-04 Audit Report - Mars Perps v1.0.pdf

PDF

Open