> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsidemax.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# updateIsolatedMargin: Add or Remove Isolated Position Margin

> Adjust the margin allocated to an isolated position without closing it, moving funds between your cross margin pool and the isolated position.

The `updateIsolatedMargin` action lets you add or remove collateral from an existing isolated position without closing or modifying the position itself. Funds are simply moved between your cross margin pool and the isolated position — your total account balance stays constant.

<Info>
  This action uses full field names (`asset`, `isBuy`, `ntli`) rather than the compact single-character keys used by order and cancel actions.
</Info>

## How margin transfer works

**Adding margin** (`ntli > 0`): the specified amount is deducted from your cross available margin and credited to the isolated position's margin balance. The operation is limited by how much cross margin is currently available.

**Removing margin** (`ntli < 0`): the specified amount is deducted from the isolated position's margin balance and returned to your cross pool. After the removal, the remaining isolated equity must still be sufficient to cover the position's initial margin requirement — you cannot remove margin to the point where your isolated position would be under-margined.

## Endpoint

```
POST https://dev.upsidemax.xyz/exchange
```

## Request

All requests must include an ECDSA signature and a millisecond-precision nonce.

```json theme={"system"}
{
  "action": {
    "type": "updateIsolatedMargin",
    "asset": 1,
    "isBuy": true,
    "ntli": 5000
  },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778858500000
}
```

### Action fields

<ParamField body="type" type="string" required>
  Fixed value: `"updateIsolatedMargin"`.
</ParamField>

<ParamField body="asset" type="int32" required>
  The contract ID of the position you want to adjust margin for.
</ParamField>

<ParamField body="isBuy" type="boolean">
  Identifies the position side in **hedge mode**: `true` = LONG position, `false` = SHORT position. Omit this field when your account is in ONE\_WAY position mode.
</ParamField>

<ParamField body="ntli" type="int64" required>
  Net transfer amount expressed in the collateral's minimum units. Positive values add margin to the isolated position; negative values remove margin. Must not be `0`.
</ParamField>

## Response

### Success

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "updateIsolatedMargin",
    "data": { "isoBefore": 10000, "isoAfter": 15000 }
  }
}
```

### Rejection

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "updateIsolatedMargin",
    "data": {
      "isoBefore": 0,
      "isoAfter": 0,
      "errorCode": 4,
      "errorMessage": "no isolated position to adjust"
    }
  }
}
```

<Note>
  Rejections still return HTTP 200 with `status: "ok"`. Check for the presence of `errorCode` in `data` to detect failures.
</Note>

### Response fields

<ResponseField name="isoBefore" type="int64">
  The isolated position margin balance before the operation. Returns `0` on rejection.
</ResponseField>

<ResponseField name="isoAfter" type="int64">
  The isolated position margin balance after the operation. Returns `0` on rejection.
</ResponseField>

<ResponseField name="errorCode" type="int">
  Present only on rejection. Identifies the failure reason.
</ResponseField>

<ResponseField name="errorMessage" type="string">
  Present only on rejection. Human-readable description of the failure.
</ResponseField>

## Error reference

| `errorMessage`                                                  | Cause                                                                                         |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `action.ntli must be non-zero`                                  | `ntli` was set to `0`.                                                                        |
| `no isolated position to adjust`                                | No isolated position exists for the given `asset` and `isBuy` combination.                    |
| `no isolated collateral slot`                                   | The account has no available isolated collateral slot for this contract.                      |
| `insufficient cross balance`                                    | Your cross margin pool doesn't have enough available margin to fund the addition.             |
| `amount exceeds withdrawable cross margin`                      | The addition amount exceeds the cross margin available to transfer into isolated.             |
| `not enough isolated margin to remove`                          | The removal amount exceeds the current isolated margin balance.                               |
| `removal would push effective leverage above position leverage` | After removal, the remaining isolated equity would fall below the initial margin requirement. |
| `mark price not ready`                                          | The mark price for this contract is temporarily unavailable; retry shortly.                   |