# Vault

The Perp v3 vault is a collection of contracts responsible for holding and managing all user collateral (maker, taker).

## `Vault`

Deposit and withdraw.

{% code overflow="wrap" %}

```solidity
/// @notice `amountXCD` uses collateral token decimals (6 decimals for USDT)
function deposit(
    address trader, 
    uint256 amountXCD
)

function withdraw(
    uint256 amountXCD
)
```

{% endcode %}

Add / remove margin. Get `marketId` from [Contracts](/nekodex-playground/docs-for-devs/contracts.md#metadata).

{% code overflow="wrap" %}

```solidity
/// @inheritdoc IVault
/// @notice `amountXCD` uses collateral token decimals (6 decimals for USDT)
function transferFundToMargin(
    uint256 marketId, 
    uint256 amountXCD
)

function transferMarginToFund(
    uint256 marketId, 
    uint256 amountXCD
)
```

{% endcode %}

Read PnL, margin and other account data. Get `marketId` from [Contracts](/nekodex-playground/docs-for-devs/contracts.md#metadata).

{% code overflow="wrap" %}

```solidity
/// @notice Read pending (unrealized) PnL for a given market.
function getUnsettledPnl(
    uint256 marketId, 
    address trader
)
returns (
    int256 unsettledPnl
)

/// @notice Read `fund`; the user's free (usable) collateral balance.
function getFund(
    address trader
)
returns (
    uint256 fund
)

/// @notice Read position margin exclusive of pending fees, unsettledPnLetc.
function getSettledMargin(
    uint256 marketId, 
    address trader
)
returns (
    int256 marginWithoutPending
)

/// @notice Read total position margin
/// @dev margin = settledMargin + unsettledPnl
function getMargin(
    uint256 marketId,
    address trader
)
returns (
    int256 margin
)

/// @notice Read position free margin (removable margin)
/// @dev free margin = max(margin state + pending margin + settleable unsettled pnl, 0)
function getFreeMargin(
    uint256 marketId,
    address trader
)
returns (
    uint256 freeMargin
)

/// @notice Read position size
function getPositionSize(
    uint256 marketId,
    address trader
)
returns (
    int256 positionSize
)

/// @notice Read position open notional (position value in settlement token at time of position entry.
function getOpenNotional(
    uint256 marketId,
    address trader
)
returns (
    int256 openNotional
)

/// @notice Read position pending margin; margin after current unsettled PnL, borrowing fees, funding fees are settled.
function getPendingMargin(
    uint256 marketId, 
    address trader
)
returns (
    int256 pendingMargin
)
```

{% endcode %}

## `IMarginProfile`

{% code overflow="wrap" %}

```solidity
/// @notice Margin requirement types
enum MarginRequirementType {
    INITIAL,
    MAINTENANCE
}

/// @notice margin ratio = account value / open notional
function getMarginRatio(
    uint256 marketId, 
    address trader, 
    uint256 price
)
returns (
    int256 marginRatio
)

/// @notice free collateral (for withdrawal) = min(free margin, account value) - initial margin requirement
/// @notice See free collateral for trades below
function getFreeCollateral(
    uint256 marketId, 
    address trader, 
    uint256 price
)
returns (
    uint256 freeCollateral
)

/// @notice free collateral (for trades) = min(margin, account value) - initial or maintenance margin requirement
/// INITIAL is for increasing position, MAINTENANCE is for reducing position
function getFreeCollateralForTrade(
    uint256 marketId,
    address trader,
    uint256 price, // User supplied price (recommend using latest Pyth price)
    MarginRequirementType marginRequirementType
)
returns (
    int256 freeCollateralForTrade
);

/// @notice margin requirement = open notional * required margin ratio (initial or maintenance)
function getMarginRequirement(
    uint256 marketId,
    address trader,
    MarginRequirementType marginRequirementType
) external view returns (uint256);

/// @notice unrealized pnl = position value + open notional
function getUnrealizedPnl(uint256 marketId, address trader, uint256 price) external view returns (int256);

/// @notice account value = margin (note it should include unsettled pnl and borrowing fee) + unrealized pnl
function getAccountValue(uint256 marketId, address trader, uint256 price) external view returns (int256);

/// @notice the margin trader can use for trading. when positive, it's always greater than or equal to "free margin"
function getMargin(uint256 marketId, address trader) external view returns (int256);

/// @notice the margin trader can access in any cases. it may be less than margin when pnl pool doesn't has enough
/// liquidity for unsettled profit
function getFreeMargin(uint256 marketId, address trader) external view returns (uint256);

function getOpenNotional(uint256 marketId, address trader) external view returns (int256);

function getPositionSize(uint256 marketId, address trader) external view returns (int256);
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nekodex.org/nekodex-playground/docs-for-devs/contracts/vault.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.