> For the complete documentation index, see [llms.txt](https://docs.symm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.symm.io/contract-documentation/symmio-perps-v0.8.5/account-layer-diamond/margin-facet.md).

# Margin Facet

### Overview

The Margin Facet provides:

* **Add Margin:** Transfer deposited balance from a parent sub-account to a virtual account's allocated balance.
* **Add Margin to Next VA:** Pre-fund the next virtual account that will be created for a given isolation key, before the quote is even sent.
* **Remove Margin:** Deallocate and transfer margin from a virtual account back to its parent sub-account.
* **Emergency Recover Margin:** Recover funds from orphaned or lost virtual account addresses.

***

#### addMargin()

Transfers deposited balance from a parent sub-account to a virtual account's allocated balance using `internalTransfer` on the Symmio core.

**Function Signature:**

```solidity
function addMargin(address virtualAccount, uint256 amount) external whenNotPaused nonReentrant onlyAccountOwner(virtualAccount);
```

**Parameters:**

* `virtualAccount`: The virtual account to add margin to.
* `amount`: The amount to transfer (in 18 decimals).

**Events:** `AddMargin(address virtualAccount, address parent, uint256 amount)`

***

#### addMarginToNextVA()

Pre-funds the next virtual account that will be created for a given isolation key. This is useful for frontends that want to fund the virtual account before the sendQuote call creates it. The function predicts the address by checking the reuse pool first, then singleVAMode, then the next nonce.

The isolation type must be compatible with the sub-account's isolation type (e.g., POSITION sub-account can only pre-fund POSITION virtual accounts).

**Function Signature:**

```solidity
function addMarginToNextVA(
    address subAccount,
    VirtualAccountIsolationType isolationType,
    uint256 symbolId,
    uint256 amount
) external whenNotPaused nonReentrant onlyAccountOwner(subAccount);
```

**Parameters:**

* `subAccount`: The parent sub-account.
* `isolationType`: The virtual account isolation type to pre-fund.
* `symbolId`: The symbol ID for the target virtual account.
* `amount`: The amount to transfer (in 18 decimals).

**Events:** `AddMargin(address predictedVA, address subAccount, uint256 amount)`

***

#### removeMargin()

Deallocates funds from a virtual account and transfers the balance back to its parent sub-account. Requires a Muon uPnL signature to verify solvency after deallocation.

**Function Signature:**

```solidity
function removeMargin(
    address virtualAccount,
    uint256 amount,
    ISymmio.SingleUpnlSig memory upnlSig
) external whenNotPaused nonReentrant onlyAccountOwner(virtualAccount);
```

**Parameters:**

* `virtualAccount`: The virtual account to remove margin from.
* `amount`: The amount to deallocate and transfer (in 18 decimals).
* `upnlSig`: The Muon signature proving the account's uPnL for solvency verification.

The function calls `deallocate` followed by `internalTransfer` on the Symmio core, moving funds from the virtual account back to the parent sub-account's allocated balance.

**Events:** `RemoveMargin(address virtualAccount, address parent, uint256 amount)`

***

#### emergencyRecoverMargin()

Recovers funds from a lost or orphaned virtual account address back to the parent sub-account. This is used when a virtual account address has funds (from a pre-fund via `addMarginToNextVA` or `internalTransfer`) but was never formally created, or was orphaned due to an edge case.

The function deallocates any allocated balance (using `zeroUpnlDeallocate`, which requires no open positions) and then transfers the full balance to the parent via `internalTransferToBalance`.

**Function Signature:**

```solidity
function emergencyRecoverMargin(address subAccount, uint256 nonce) external whenNotPaused nonReentrant onlyAccountOwner(subAccount);
```

**Parameters:**

* `subAccount`: The parent sub-account to recover funds to.
* `nonce`: The nonce used to derive the lost virtual account address. Must be between 1 and the current nonce + 1.

**Preconditions:** The derived address must not be an existing sub-account or virtual account. It must have a non-zero balance or allocated balance.

**Events:** `EmergencyMarginRecovered(address lostAccount, address subAccount, uint256 totalBalance)`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.symm.io/contract-documentation/symmio-perps-v0.8.5/account-layer-diamond/margin-facet.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.