Skip to content
CryptonlyCryptonlyCryptonly

Commit a withdrawal quote

POST
/withdrawal/commit

Commits a previously-obtained quoteId and creates the withdrawal. The deduction currency, total deduction, and FX uplift were locked onto the quote at quote time; commit just locks that single balance, re-checks it still covers the locked total, and deducts inside a serializable transaction. If the locked balance has dropped below the locked total, commit returns withdrawal.insufficientBalance and the merchant must re-quote - commit does not retry against any other currency, even when cross-currency is enabled on the account.

Required scope: withdrawals.create.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
quoteId
required

Quote id from POST /withdrawal/quote.

string format: uuid
customData

Custom metadata

object
webhookUrl

HTTPS URL to receive webhook notifications. Must be a public, TLD-qualified HTTPS URL.

string

Example 

https://merchant.example.com/webhooks/cryptonly/withdrawals

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
data
required
object
id
required
string
orderId
required
string
accountId
required
string
cryptoCurrencyCode
required

Currency code.

string
Allowed values: USDT_TRC20 USDT_ERC20 USDT_BEP20 USDC_ERC20 USDC_BEP20 USDC_BASE EURC_BASE LINK_ERC20 LINK_BEP20 ETH TRX BNB BTC ETH_BASE
address
required

Destination wallet address

string
transactionHash

On-chain transaction hash

string
nullable
amount
required

Withdrawal amount in cryptoCurrencyCode

number
amountUsd
required

Withdrawal amount in USD

number
status
required
string
Allowed values: created processing completed failed cancelled
convertId

Optional funding currency_conversion that topped up the withdrawal asset before this withdrawal debit (auto-convert).

string format: uuid
nullable
feeAmount
required

Network fee debited from the user in cryptoCurrencyCode (same value used in debitedAmount = amount + this fee)

number
feeAmountUsd
required

Same fee, snapshotted to USD at commit time

number
debitedAmount
required

Exact total debited in cryptoCurrencyCode (on-chain amount + on-chain fee)

number
customData
object
webhookUrl
string
nullable
source

Commit channel; omitted when unknown (rows created before this metadata existed).

string
Allowed values: api admin_panel
createdAt
required

ISO 8601 timestamp.

string
updatedAt
required

ISO 8601 timestamp.

string
quoteId
required

Opaque id from the quote phase; equals the committed network transfer id when set.

string format: uuid
nullable
transferId
required

Network transfer backing this withdrawal once committed.

string format: uuid
nullable

Example 

{
  "data": {
    "cryptoCurrencyCode": "USDT_TRC20",
    "status": "created",
    "source": "api"
  }
}

400

Section titled “400”

Validation error, expired/already-committed quote, the locked balance no longer covers the quote, or duplicate orderId.

401

Section titled “401”

Missing or invalid x-tenant-api-key header. Code: exceptions.auth.invalidApiKey.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

403

Section titled “403”

Request origin IP is not on the tenant API allowlist (exceptions.auth.ipNotAllowed), or the API key is missing the scope required by this operation (exceptions.auth.insufficientScope).

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

429

Section titled “429”

Rate limit exceeded for this endpoint. Retry after the window resets. Code: exceptions.rateLimit.exceeded. The extension.msBeforeNext field tells you how long to wait.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}

500

Section titled “500”

Unexpected server error. Safe to retry idempotent operations after a backoff.

Media typeapplication/json
object
code
required

Stable machine-readable error code, namespaced under exceptions.. Always prefer branching on this value over message. See the per-route descriptions for the codes that route emits.

string
message
required

Human-readable explanation. Subject to wording changes; for programmatic checks use code instead.

string
extension

Optional structured payload accompanying the error. For exceptions.rateLimit.exceeded includes msBeforeNext; for validation errors includes the offending field info.

object
key
additional properties
any

Example 

{
  "code": "exceptions.auth.invalidApiKey",
  "message": "Invalid or missing API key"
}