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

# unlockFromShareGroup: Withdraw Funds from a Share Group

> Withdraw available funds from a portfolio share group margin pool to your chain-level balance, subject to group equity and margin requirement constraints.

When you want to pull funds out of a PORTFOLIO share group and return them to your chain-level balance, use `unlockFromShareGroup`. Like other withdrawal actions, you can only move up to the **withdrawable amount** — the share group's total equity minus the initial margin (IM) held against open positions and any margin frozen by active orders within that group. Unrealized profits are included in equity but cannot be withdrawn until realized.

<Warning>
  You cannot withdraw funds committed as initial margin for open positions or frozen for pending orders within the share group. Close positions and cancel orders in the group first 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": "unlockFromShareGroup",
    "groupId": 3,
    "coinId": 1,
    "amount": "1000"
  },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778859500000
}
```

### Action parameters

<ParamField body="groupId" type="int32" required>
  The ID of the source share group. Funds are deducted from this group's shared margin pool, subject to its withdrawable amount limit.
</ParamField>

<ParamField body="coinId" type="int32" required>
  The coin or currency ID to withdraw 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 available in the share group. Decimals are not accepted — use the coin's smallest unit.
</ParamField>

## Response

A successful withdrawal returns the updated balances for both the source share group and your chain-level ledger. The response type is `shareGroupFund`, consistent with other share group fund operations.

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "shareGroupFund",
    "data": {
      "coinId": 1,
      "amount": 1000,
      "fromBalanceAfter": 0,
      "toBalanceAfter": 5000
    }
  }
}
```

<ResponseField name="coinId" type="int32">
  The coin ID that was withdrawn.
</ResponseField>

<ResponseField name="amount" type="int64">
  The amount moved from the share group back to your chain-level balance.
</ResponseField>

<ResponseField name="fromBalanceAfter" type="int64">
  The share group's margin pool balance after the withdrawal.
</ResponseField>

<ResponseField name="toBalanceAfter" 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** — position IM and order-frozen margin within the group constrain how much can be withdrawn.
* **Account not in PORTFOLIO mode** — share groups are only active when your margin share type is `1`.
* **Invalid `groupId`** — the specified share group must exist and be accessible to your account.
* **Amount ≤ 0** — the `amount` field must be a positive integer string.

```json theme={"system"}
{
  "status": "ok",
  "response": {
    "type": "shareGroupFund",
    "data": {
      "coinId": 0,
      "amount": 0,
      "fromBalanceAfter": 0,
      "toBalanceAfter": 0,
      "errorCode": 1,
      "errorMessage": "requested amount exceeds withdrawable balance in share group"
    }
  }
}
```

<Tip>
  To deposit funds into a share group from your chain-level balance, use [`lockIntoShareGroup`](/exchange/lock-into-share-group). To move funds from a share group into a market deployer instead, use [`transferShareGroupToMd`](/exchange/transfer-share-group-to-md).
</Tip>