REST API›Settle (Off Exchange)›Client Allocations & Deallocations

POST

Deallocate Funds from Connection

This API call allows clients to deallocate funds from a connected partner. A successful deallocation will unlock funds and ensure that they are available for actions (withdrawal/rebalancing) at BitGo. Note: Deallocations will happen synchronously and deallocated amounts can be viewed in the BitGo Application or via a balance endpoint.

Error scenarios:

  • 400: Invalid Request Error

  • Occurs when the request parameters are invalid or malformed.

  • Examples: Invalid UUID format for connectionId, invalid enterpriseId format, malformed request body, invalid signature format.

  • 401: Authentication Error

  • Occurs when the request is not authorized.

  • Examples: Caller is not a member of the enterprise.

  • 403: Permission Denied Error

  • Occurs when the authenticated client doesn't have necessary permissions.

  • Examples: Enterprise does not have OES license.

  • 404: Not Found Error

  • Occurs when the specified connection cannot be found.

  • Examples: Connection ID doesn't exist, connection doesn't belong to this client.

  • 422: Deallocation Error with Released Status

  • Occurs when the deallocation cannot be processed due to business rules.

  • Examples: Insufficient funds available for deallocation, connection is inactive, deallocation amount exceeds available balance.

  • 500: Internal Server Error or Reserved Deallocation

  • Occurs when there's an unexpected server error processing the request.

  • Examples: Database connection issues, transient network errors.

Requires access token scopes: settlement_network_read, settlement_network_write

Path Params

  • enterpriseId string required
    The enterprise identifier of the client. This identifies the client enterprise that owns the connection.

    at least 1 characters

  • connectionId string required
    The unique identifier of the connection to deallocate from. This UUID uniquely identifies the connection between a client and a partner.

Body Params

object

  • amount object required
    The amount to deallocate from the connection. Contains both the currency identifier and the quantity in base units.
    amount object
    • currency string required
    • quantity string required
  • clientExternalId string required
    External identifier provided by the client. Used for idempotence and correlation with client systems.

    at least 1 characters

  • nonce string required
    A unique nonce value used for cryptographic operations. This provides additional security for deallocation operations.

    at least 1 characters

  • notes string
    Optional notes provided by the client when creating the deallocation. Can contain additional context or information about the purpose of the deallocation.

    at least 1 characters

  • payload string required

    Payload formed by stringifying the object containing all other request properties.

    This includes:

    • amount: The amount to deallocate.
    • clientExternalId: Your unique identifier for this deallocation.
    • nonce: A unique value to prevent replay attacks.
    • notes: Optional notes about the deallocation.
    • connectionId: The connection to deallocate funds from.
    • enterpriseId: Your enterprise ID.

    The payload must be signed using your BitGo account's private key to create the signature parameter.

    at least 1 characters

  • signature string required

    Digital signature of the payload parameter.

    This signature:

    • Must be created using your BitGo account's private key
    • Verifies that the request is authentic and hasn't been tampered with
    • Provides non-repudiation for the deallocation request

    at least 1 characters

Responses

200
OK

Response Body

ONE OF

  • deallocation object required
    The deallocation record in its cleared state. This contains all deallocation details with a status of 'cleared', indicating the allocation was successfully completed.
    deallocation object
    • id string required
      The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
    • amount object required
      The amount of the allocation/deallocation. Contains both the currency identifier and the quantity in base units.

      ONE OF

      • currency string required

        at least 1 characters

      • quantity string required
    • connectionId string required
      The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
    • clientExternalId string required
      External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.

      at least 1 characters

    • partnerExternalId string
      External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.

      at least 1 characters

    • initiatedBy string required
      The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.

      at least 1 characters

    • notes string
      Optional notes provided by the client when creating the allocation/deallocation. Can contain additional context or information about the purpose of the allocation.

      at least 1 characters

    • createdAt string date-time required
      The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
    • updatedAt string date-time required
      The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
    • retriable boolean enum required
      Indicates whether or not the allocation/deallocation is retriable. When true, clients may retry the operation if it did not complete successfully. Retry can be performed by re-sending the same allocation request that was originally sent.
      false
    • evaluationId string
      The unique identifier of the policy evaluation for this allocation/deallocation. Present when policy evaluation was performed as part of the allocation flow.

      at least 1 characters

    • pendingApprovalId string
      The unique identifier of the pending approval for this allocation/deallocation. Present when policy evaluation resulted in a PENDING status requiring manual approval.

      at least 1 characters

    • policyResult string enum

      The result of the policy evaluation for this allocation/deallocation.

      • 'approved': Policy evaluation passed and the operation was allowed
      • 'rejected': Policy evaluation failed and the operation was denied Not present if no policy evaluation was performed or if evaluation is still pending.
      approvedrejected
    • status string enum required

      Status of the allocation/deallocation.

      Possible values:

      • reserved: The amount for allocation/deallocation is reserved but operation has not completed. This is a temporary state awaiting final resolution.
      • cleared: Terminal state; the amount for allocation/deallocation is cleared and funds have been successfully allocated. This indicates a successful operation.
      • released: Terminal state; the amount for allocation/deallocation is released and funds have been returned. This indicates the operation failed, either because balance was insufficient for allocation/deallocation, or that the partner rejected the request to allocate/deallocate.
      cleared
400
Bad Request
No response body
401
Unauthorized

Response Body

object

  • error string required
403
Forbidden

Response Body

object

  • error string required
404
Not Found

Response Body

object

  • error string required
422
Unprocessable Entity

Response Body

object

  • deallocation object required
    The deallocation record in its released state. This contains all deallocation details with a status of 'released', indicating the allocation was not completed and funds were returned. The reason field will explain why the deallocation was released.
    deallocation object
    • id string required
      The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
    • amount object required
      The amount of the allocation/deallocation. Contains both the currency identifier and the quantity in base units.

      ONE OF

      • currency string required

        at least 1 characters

      • quantity string required
    • connectionId string required
      The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
    • clientExternalId string required
      External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.

      at least 1 characters

    • partnerExternalId string
      External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.

      at least 1 characters

    • initiatedBy string required
      The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.

      at least 1 characters

    • notes string
      Optional notes provided by the client when creating the allocation/deallocation. Can contain additional context or information about the purpose of the allocation.

      at least 1 characters

    • createdAt string date-time required
      The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
    • updatedAt string date-time required
      The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
    • retriable boolean enum required
      Indicates whether or not the allocation/deallocation is retriable. When true, clients may retry the operation if it did not complete successfully. Retry can be performed by re-sending the same allocation request that was originally sent.
      false
    • evaluationId string
      The unique identifier of the policy evaluation for this allocation/deallocation. Present when policy evaluation was performed as part of the allocation flow.

      at least 1 characters

    • pendingApprovalId string
      The unique identifier of the pending approval for this allocation/deallocation. Present when policy evaluation resulted in a PENDING status requiring manual approval.

      at least 1 characters

    • policyResult string enum

      The result of the policy evaluation for this allocation/deallocation.

      • 'approved': Policy evaluation passed and the operation was allowed
      • 'rejected': Policy evaluation failed and the operation was denied Not present if no policy evaluation was performed or if evaluation is still pending.
      approvedrejected
    • status string enum required

      Status of the allocation/deallocation.

      Possible values:

      • reserved: The amount for allocation/deallocation is reserved but operation has not completed. This is a temporary state awaiting final resolution.
      • cleared: Terminal state; the amount for allocation/deallocation is cleared and funds have been successfully allocated. This indicates a successful operation.
      • released: Terminal state; the amount for allocation/deallocation is released and funds have been returned. This indicates the operation failed, either because balance was insufficient for allocation/deallocation, or that the partner rejected the request to allocate/deallocate.
      released
    • reason string required
      The reason that the allocation/deallocation is not cleared. Provides a descriptive explanation for why the allocation is in the reserved state. Will not be defined if the allocation is cleared.

      at least 1 characters

  • error string required
500
Internal Server Error

Response Body

ONE OF

  • error string required