> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Balance holds

A hold locks part of the account's available balance at the banking provider. The money stays in the account but leaves `available` on `GET /balance` until the hold is **released** to another CorpX account or **cancelled**.

Writes are M2M only, with the `holds.write` scope. Creating and releasing go through the cashout locks and the transaction PIN, like any outflow. Reads accept `read`, `holds.read` or `holds.write`.

## Lifecycle

```text
POST /holds ──► active ──► releasing ──► released     (internal transfer)
                  │
                  └──► cancelling ──► cancelled       (amount back to available)

unknown_lock: the provider did not confirm the lock; CorpX reconciles it.
```

| Route                                         | What it does                                                                                                                       |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/accounts/{accountId}/holds`         | Locks `amount`. `Idempotency-Key` is required; an exact retry returns the same hold with `200`.                                    |
| `GET /v1/accounts/{accountId}/holds`          | Lists holds, filtered by `status` (a lifecycle status or `held`).                                                                  |
| `GET /v1/accounts/{accountId}/holds/{holdId}` | Reads one hold.                                                                                                                    |
| `POST .../holds/{holdId}/release`             | Transfers the amount to `to.accountId`, with an optional `fee` to a third account. `amount` plus `fee.amount` must equal the hold. |
| `POST .../holds/{holdId}/cancel`              | Returns the amount to available. `reason` is required.                                                                             |

Partial release does not exist: cancel and create another hold. A hold created by a P2P order (`reason: p2p_order`) is released or cancelled only by the order and answers `409 hold_managed_by_order` on the routes above.

## What is locked right now

`GET .../holds?status=held` lists only the holds that still lock balance at the banking provider: the `active` ones, plus `releasing` or `cancelling` ones whose lock has not been undone yet. Their sum is the `heldAmount` on `GET /balance`, so the list explains the locked balance line by line.

## Hold origin

A hold created by a P2P order carries `source`, in the list and in the single read:

```json
{
  "holdId": "hld_6b0c2d1e-…",
  "status": "active",
  "amount": "1005.00",
  "reason": "p2p_order",
  "reference": "P2P ord_4235120236fa625f2a539d0c",
  "source": {
    "type": "p2p_order",
    "orderId": "ord_4235120236fa625f2a539d0c",
    "orderStatus": "crypto_sent",
    "side": "buy",
    "pair": "USDT_TRON",
    "network": "tron",
    "cryptoAmount": "196.29",
    "price": "5.12",
    "deadlineAt": "2026-11-01T15:10:00Z"
  }
}
```

* `deadlineAt` is the deadline currently running on the order (`null` in dispute or a final status).
* On order holds, the destination accounts (seller and intermediation) do not appear, and `lastError` comes out as a public code.
* A hold created through the API, with no order, has no `source`. If reading the order fails, the field is simply omitted.

## Asynchronous answers

* `202` on creation: the provider did not confirm the lock. The hold stays `unknown_lock` until reconciled. Do not resend with another key before checking the balance.
* `202` on release or cancel: the operation is still running. Read the hold or wait for the webhook.

## Webhooks

| Event                    | When                                                                               |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `account.hold.created`   | The amount was locked (`active`).                                                  |
| `account.hold.released`  | The amount was transferred to the destination account (and the fee, when present). |
| `account.hold.cancelled` | The amount returned to available.                                                  |

Error codes are in the **Balance holds** section of [Error Handling](/baas/guias/referencia/erros).