Skip to content
CryptonlyCryptonlyCryptonly

Quote a withdrawal

POST
/withdrawal/quote

Estimates the on-chain fee for the supplied withdrawal and returns a short-lived quoteId plus a fee breakdown. The quote does not reserve any balance and expires in ~60s. Submit the quoteId to POST /withdrawal/commit to actually create the withdrawal.

Required scope: withdrawals.create.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
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

Example 

USDT_TRC20
address
required

Destination wallet address

string
amount
required

Withdrawal amount in cryptoCurrencyCode

number

Example 

100
allowAutoConvert

If true and the withdrawal-asset balance is short of amount + on-chain fee, the quote may add a currency_conversion to top up that balance ($0.5 USD flat commission in the source currency) before a normal same-currency withdrawal. Commit reuses the locked currency_conversion row.

boolean
orderId
required

Merchant idempotency key, scoped to (tenant, account). Two quote requests sharing an orderId collapse to the same quote, and the pair (orderId, account) can ever back at most one committed withdrawal - re-quoting after commit fails with 409.

string

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
data
required
object
quoteId
required

Opaque quote id; submit to POST /withdrawal/commit to commit.

string
orderId
required

Echo of the merchant orderId supplied at quote time. The merchant should persist this against their order so support tickets and webhooks correlate cleanly.

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

Echo of address

string
amount
required

Echo of amount - denominated in cryptoCurrencyCode (this is what reaches the destination address).

number
autoConvert

When present, a virtual conversion is locked to top up the withdrawal asset before the withdrawal debit. Commission is in fromAssetCode.

object
fromAssetCode
required

Asset code.

string
Allowed values: USDT USDC EURC LINK ETH TRX BNB BTC
toAssetCode
required

Asset code.

string
Allowed values: USDT USDC EURC LINK ETH TRX BNB BTC
fromAmount
required
number
toAmount
required
number
totalDeduction
required

Total to debit in cryptoCurrencyCode at commit (on-chain amount + on-chain fee component in the withdrawal asset).

number
fee
required
object
feeNative
required

Real on-chain fee, in network base currency (e.g. ETH/TRX/BNB/BTC)

number
feeCurrency
required

Network base currency symbol

string
feeInCryptoCurrencyCode
required

On-chain fee at quote time, expressed in the withdrawal cryptoCurrencyCode.

number
feeUsd
required

Fee snapshotted to USD at quote time

number
expiresAt
required

ISO timestamp after which the quote can no longer be committed. Re-issue a new quote if expired.

string

Example 

{
  "data": {
    "cryptoCurrencyCode": "USDT_TRC20",
    "autoConvert": {
      "fromAssetCode": "USDT",
      "toAssetCode": "USDT"
    }
  }
}

400

Section titled “400”

Validation error, currency/address mismatch, or below-minimum amount.

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