[POST] /external/v1/withdrawal-intents

Overview

Creates a withdrawal intent for the authenticated merchant.

Authentication

Requires an API key. See Authentication.

Request Body

Field	Type	Required	Description
`senderWalletId`	`string`	Yes	Source wallet ID to debit. Use a wallet `id` returned by the wallet list or retrieve endpoints. e.g: WT0ir6F1
`serviceFeeMode`	`string`	Yes	Determines whether the service fee is included in or added on top of `amount`. Allowed values: `inclusive`, `exclusive`.
`currencyCode`	`string`	Yes	Currency code for the withdrawal amount. Allowed value: `USDT`.
`amount`	`NumericString`	Yes	Withdrawal amount. Send this value as a string with up to 2 decimal places. e.g. "100.32"
`destination`	`CreateWithdrawalDestination`	Yes	Destination that receives the withdrawal.

Service Fee Mode

serviceFeeMode determines how the service fee is applied to amount.

Value	Description
`inclusive`	The service fee is deducted from `amount`.
`exclusive`	The service fee is charged in addition to `amount`.

For example, if amount is 100 and amountFee is 1:

Mode	`amountNet`	`amountGross`
`inclusive`	`99`	`100`
`exclusive`	`100`	`101`

CreateWithdrawalDestination

Field	Type	Required	Description
`type`	`string`	Yes	Destination type. Allowed value: `crypto`.
`rail`	`string`	Yes	Destination rail. Allowed value: `tron`.
`identifier`	`string`	Yes	Destination identifier. For the Tron rail, this is the recipient Tron address. e.g TQPipjn73wBnKDodCtZAUCLoMdsgjBc3K5

Supported Destinations

Currency	Destination Type	Rail	Identifier
`USDT`	`crypto`	`tron`	Tron address

Response

Returns an ApiResponse<WithdrawalIntent>.

Field	Type	Description
`code`	`string`	Response code. Successful responses use `ok`.
`message`	`string`	Human-readable response message.
`data`	`WithdrawalIntent`	Created withdrawal intent.

Example Request

POST /external/v1/withdrawal-intents
Content-Type: application/json

{
  "senderWalletId": "WT0ir6F1",
  "serviceFeeMode": "inclusive",
  "currencyCode": "USDT",
  "amount": "100",
  "destination": {
    "type": "crypto",
    "rail": "tron",
    "identifier": "TJScotwGB69dbkzgEnjw5rKaeehxzv8pax"
  }
}

Example Response

{
  "code": "ok",
  "message": "Ok.",
  "data": {
    "id": "WI_rSCtIlp0",
    "wallet": {
      "id": "WT0ir6F1",
      "type": "merchant_wallet"
    },
    "transaction": null,
    "destination": {
      "type": "crypto",
      "rail": "tron",
      "routingCode": "tron:nile",
      "identifier": "TJScotwGB69dbkzgEnjw5rKaeehxzv8pax"
    },
    "status": "preparing",
    "serviceFeeMode": "inclusive",
    "amount": "100.0000000000000000",
    "amountFee": "1.0000000000000000",
    "amountNet": "99.0000000000000000",
    "amountGross": "100.0000000000000000",
    "submittedAt": "2026-05-21T15:24:36.468Z",
    "finalizedAt": null,
    "createdAt": "2026-05-21T15:24:36.468Z",
    "updatedAt": "2026-05-21T15:24:41.496Z"
  }
}

Error Responses

All error responses use ErrorResponse.

HTTP Status	Code	Message	Description
`400`	`data_invalid`	Validation error message	The request body shape or field value does not match the API contract.
`400`	`withdrawal_intent.config_incomplete`	Error message	Withdrawal configuration is incomplete, so the intent cannot be created.
`400`	`withdrawal_intent.destination_invalid`	Error message	The destination is outside the supported scope or failed validation.
`400`	`withdrawal_intent.destination_internal`	Error message	The destination points to an internal system endpoint and cannot be used as an external withdrawal destination.
`400`	`withdrawal_intent.service_fee_not_covered`	`No withdrawable amount remains after the service fee.`	With `inclusive` mode, the service fee is equal to or greater than `amount`.
`400`	`withdrawal_intent.balance_insufficient`	Error message	The source wallet does not have enough available balance.
`400`	`withdrawal_intent.daily_limit_exceeded`	Error message	The requested amount exceeds the daily withdrawal limit.
`400`	`withdrawal_intent.monthly_limit_exceeded`	Error message	The requested amount exceeds the monthly withdrawal limit.
`401`	`unauthorized`	`Unauthorized.`	The API key is missing or invalid.
`403`	`forbidden`	`Forbidden.`	The authenticated caller is not allowed to create this withdrawal intent.

Example Validation Error

{
  "code": "data_invalid",
  "message": "destination.rail must be tron",
  "data": null
}

Overview​

Authentication​

Request Body​

Service Fee Mode​

CreateWithdrawalDestination​

Supported Destinations​

Response​

Example Request​

Example Response​

Error Responses​

Example Validation Error​

Related Models​