> This page is for BaaS.

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

# Bloqueios de saldo

Um bloqueio (hold) trava parte do saldo disponível da conta no liquidante. O valor continua na conta, mas sai do `available` do `GET /balance` até o bloqueio ser **liberado** para outra conta CorpX ou **cancelado**.

Escrita só por M2M, com o escopo `holds.write`. Criar e liberar passam pelas travas de cashout e pelo PIN de transação, como qualquer saída. Leitura aceita `read`, `holds.read` ou `holds.write`.

## Ciclo de vida

```text
POST /holds ──► active ──► releasing ──► released     (transferência interna)
                  │
                  └──► cancelling ──► cancelled       (valor volta ao disponível)

unknown_lock: o liquidante não confirmou a trava; a CorpX reconcilia.
```

| Rota                                          | O que faz                                                                                                                                    |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/accounts/{accountId}/holds`         | Trava `amount`. `Idempotency-Key` obrigatória; a repetição exata devolve o mesmo hold com `200`.                                             |
| `GET /v1/accounts/{accountId}/holds`          | Lista, com filtro `status` (um status do ciclo de vida ou `held`).                                                                           |
| `GET /v1/accounts/{accountId}/holds/{holdId}` | Consulta um bloqueio.                                                                                                                        |
| `POST .../holds/{holdId}/release`             | Transfere o valor para `to.accountId`, com `fee` opcional para uma terceira conta. `amount` mais `fee.amount` tem de fechar o valor do hold. |
| `POST .../holds/{holdId}/cancel`              | Devolve o valor ao disponível. `reason` obrigatório.                                                                                         |

Liberação parcial não existe: cancele e crie outro bloqueio. Bloqueio criado por uma ordem P2P (`reason: p2p_order`) só é liberado ou cancelado pela própria ordem e responde `409 hold_managed_by_order` nas rotas acima.

## O que está travado agora

`GET .../holds?status=held` lista só os bloqueios que ainda seguram saldo no liquidante: os `active` e os `releasing` ou `cancelling` cuja trava ainda não foi desfeita. A soma deles é o `heldAmount` do `GET /balance`, então a lista explica o saldo travado linha a linha.

## Origem do bloqueio

Bloqueio criado por uma ordem P2P traz `source`, na lista e na consulta:

```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` é o prazo que corre agora na ordem (`null` em disputa ou status final).
* Nos bloqueios de ordem, as contas de destino (vendedor e intermediação) não aparecem, e `lastError` sai como código público.
* Bloqueio criado pela API, sem ordem, não tem `source`. Se a leitura da ordem falhar, o campo só some.

## Respostas assíncronas

* `202` na criação: o liquidante não confirmou a trava. O hold fica `unknown_lock` até a reconciliação. Não reenvie com outra chave antes de consultar o saldo.
* `202` na liberação ou no cancelamento: a operação continua. Consulte o hold ou espere o webhook.

## Webhooks

| Evento                   | Quando                                                                     |
| ------------------------ | -------------------------------------------------------------------------- |
| `account.hold.created`   | O valor foi travado (`active`).                                            |
| `account.hold.released`  | O valor foi transferido para a conta de destino (e a taxa, quando houver). |
| `account.hold.cancelled` | O valor voltou ao disponível.                                              |

Códigos de erro na seção **Bloqueios de saldo** de [Tratamento de Erros](/baas/guias/referencia/erros).