Retrieve a withdrawal

GET

/withdrawal

Retrieves a single withdrawal by its id (UUID) or the merchant orderId on the account bound to the API key. At least one of the two query parameters must be supplied; if both are present, id takes precedence.

Required scope: withdrawals.list.

Authorizations

• TENANT_API_KEY

Parameters

Query Parameters

id

string format: uuid

Withdrawal ID (UUID) returned from POST /withdrawal. Mutually optional with orderId.

orderId

string

Merchant orderId supplied when the withdrawal was created. Mutually optional with id.

Responses

200

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

Neither id nor orderId was supplied, or a supplied value failed validation.

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

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

404

Withdrawal not found.

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

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