Skip to navigation

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

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.
RouteWhat it does
POST /v1/accounts/{accountId}/holdsLocks amount. Idempotency-Key is required; an exact retry returns the same hold with 200.
GET /v1/accounts/{accountId}/holdsLists holds, filtered by status (a lifecycle status or held).
GET /v1/accounts/{accountId}/holds/{holdId}Reads one hold.
POST .../holds/{holdId}/releaseTransfers the amount to to.accountId, with an optional fee to a third account. amount plus fee.amount must equal the hold.
POST .../holds/{holdId}/cancelReturns 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:

{
"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

EventWhen
account.hold.createdThe amount was locked (active).
account.hold.releasedThe amount was transferred to the destination account (and the fee, when present).
account.hold.cancelledThe amount returned to available.

Error codes are in the Balance holds section of Error Handling.