Create Crypto Transfers
Overview
A crypto transfer sends USDT from the user's available balance to an external wallet address on the TRON network. Once the transfer is created, the specified amount is immediately deducted from the user's balance.
If the transfer is rejected or fails, the funds are automatically refunded back to the user's balance.
Every crypto transfer points to a payout destination: a saved wallet address, optionally identified with a friendly label so it is easy to find later. You can either reference a destination you already created, or describe the wallet inline and let the API create it for you.
Endpoint
POST /payout/withdrawal
API Reference: Create a crypto payout
Authentication
This endpoint requires a valid x-api-key and a Bearer Token issued to a store role in headers.
x-api-key: <your_api_key>
Authorization: Bearer <access_token>
Non store user requests will be rejected.
See the Authentication Guide to see more details.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | Positive decimal amount with up to two decimals. Example: "1000.50" |
currency | string | Yes | Must be USDT |
destination | object | Yes | The wallet that receives the funds. See Payout Destination |
Payout Destination
The destination object accepts one of two shapes. They are mutually exclusive: sending id together with the wallet fields is rejected.
Option A — Reuse a saved destination
Send the id of an existing, active payout destination.
{
"destination": {
"id": "123e4567-e89b-12d3-a456-426614174000"
}
}
Option B — Provide the wallet inline
Send the wallet details and the API finds the matching destination or creates it if it does not exist yet.
| Field | Required | Description |
|---|---|---|
rail | Yes | Network used to reach the wallet. Use TRON for USDT on TRON |
accountIdentifierValue | Yes | The destination wallet address. It is validated against the selected rail |
label | No | Friendly name for the wallet, e.g. "Treasury wallet" |
{
"destination": {
"rail": "TRON",
"accountIdentifierValue": "TKbVBEh8tDZCnqw9EqL7fTRHxbTAPBrnEX",
"label": "Treasury wallet"
}
}
Wallet destinations do not require
country,institutionorbeneficiarydata.
An invalid wallet address for the selected rail will result in a validation error.
Managing destinations ahead of time
You can also create and look up destinations on their own, which is useful to build a saved list of wallets for your users:
- Create a payout destination
- List payout destinations — supports searching by
label - Get a payout destination by ID
- Edit a payout destination
Editing a destination never affects past crypto transfers: each transfer keeps a snapshot of the destination as it was when the transfer was created.
Request Examples
A created crypto transfer starts with
pendingstatus
Using a wallet address
curl -X POST "/api/v1/payout/withdrawal" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-d '{
"amount": "1000.50",
"currency": "USDT",
"destination": {
"rail": "TRON",
"accountIdentifierValue": "TKbVBEh8tDZCnqw9EqL7fTRHxbTAPBrnEX",
"label": "Treasury wallet"
}
}'
Using a saved destination
curl -X POST "/api/v1/payout/withdrawal" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-d '{
"amount": "1000.50",
"currency": "USDT",
"destination": {
"id": "123e4567-e89b-12d3-a456-426614174000"
}
}'
Response Behavior
A successful request returns 201 Created with the created payout:
typeiswithdrawalpayoutNumberis the unique reference of the transferdestinationis a snapshot of the wallet used, including theidandlabelof the saved destination
You can retrieve it later with Get payout by ID, or list your transfers with Get paginated list of payouts filtering by type=withdrawal.
Transfer Lifecycle
The status field of the payout progresses through the following values:
| Status | Description |
|---|---|
pending | Transfer created. Awaiting processing. |
in_progress | Transfer is being actively processed. |
sanction_review | Transfer is on hold while a compliance review is completed. |
paid | Transfer completed successfully. Terminal state. |
rejected | Transfer rejected. Funds are restored. Terminal state. |
Balance Impact
| Event | Effect on Balance |
|---|---|
| Transfer created | Amount is immediately deducted from the user's available balance |
| Transfer rejected | Amount is automatically restored to the user's balance |
Daily Limit
Crypto transfers count toward the store's daily payout limit, which is shared with bank transfers. Check the remaining amount before creating a transfer with Get the daily payout limit usage. Exceeding it returns the PAYOUT_DAILY_LIMIT_EXCEEDED error code.
Important Notes
- A transfer with an amount higher than the user's available balance will result in an error
- Crypto transfers initiate real and irreversible on-chain operations. Double-check the wallet address and network before submitting
- Sending a currency your account is not allowed to operate returns
403 Forbidden