> ## 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.

# unlockCollateral: Withdraw Funds from a Market Deployer

> Move available margin from a market deployer cross margin pool back to your chain-level balance, subject to position and order margin requirements.

When you want to move funds out of a market deployer (MD) and back to your chain-level balance, use the `unlockCollateral` action. You can only withdraw up to the **withdrawable amount** — defined as your total equity in the MD minus the initial margin (IM) held against open positions and any margin frozen by active orders. Unrealized profits are included in equity but cannot be withdrawn until realized.

<Warning>
  You cannot withdraw funds that are currently committed as initial margin for open positions or frozen for pending orders. Close positions and cancel orders first if you need to free up additional margin.
</Warning>

## Endpoint

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

## Request

Every request must carry an ECDSA signature and a nonce to prevent replay attacks.

```json theme={"system"}
{
  "action": {
    "type": "unlockCollateral",
    "marketDeployerId": 1,
    "coinId": 1,
    "amount": "1000"
  },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778859100000
}
```

### Action parameters

<ParamField body="marketDeployerId" type="int32" required>
  The ID of the market deployer from which you want to withdraw funds.
</ParamField>

<ParamField body="coinId" type="int32" required>
  The coin or currency ID to transfer back to your chain-level balance.
</ParamField>

<ParamField body="amount" type="string" required>
  The amount to withdraw, expressed as a raw integer string (e.g. `"1000"`). Must be greater than zero and must not exceed the withdrawable amount. Decimals are not accepted — use the coin's smallest unit.
</ParamField>

## Response

A successful withdrawal returns the updated balances for both the market deployer's cross margin pool and your chain-level ledger.

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "unlockCollateral",
    "data": {
      "coinId": 1,
      "amount": 1000,
      "marketDeployerAfter": 2000,
      "ledgerAfter": 6000
    }
  }
}
```

<ResponseField name="coinId" type="int32">
  The coin ID that was transferred, confirming which asset was moved.
</ResponseField>

<ResponseField name="amount" type="int64">
  The amount that was withdrawn from the market deployer's cross margin pool.
</ResponseField>

<ResponseField name="marketDeployerAfter" type="int64">
  Your cross margin balance within the market deployer after the withdrawal.
</ResponseField>

<ResponseField name="ledgerAfter" type="int64">
  Your chain-level balance for this coin after the withdrawal.
</ResponseField>

## Errors

If the request cannot be fulfilled, the exchange still returns **HTTP 200** with `status: "ok"` — the rejection is reported inside `response.data`, where a server-assigned integer `errorCode` and a human-readable `errorMessage` are populated while the numeric amount and balance fields are set to `0`. Common causes include:

* **Amount exceeds withdrawable balance** — you cannot withdraw more than your equity minus position IM and order-frozen margin.
* **Amount ≤ 0** — the `amount` field must be a positive integer string.
* **Not enrolled in the market deployer** — the specified MD must be one you are enrolled in.

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "unlockCollateral",
    "data": {
      "coinId": 0,
      "amount": 0,
      "marketDeployerAfter": 0,
      "ledgerAfter": 0,
      "errorCode": 1,
      "errorMessage": "requested amount exceeds withdrawable balance"
    }
  }
}
```

<Tip>
  To move funds in the opposite direction — from your chain-level balance into a market deployer — use [`lockCollateral`](/exchange/lock-collateral).
</Tip>