Skip to main content
POST
Create Crypto Payout
Submit a payout to an external blockchain address using this endpoint with transactions_type: "crypto_payout". Vita broadcasts the transaction to the selected network and reports final status via webhook.
This endpoint shares its URL with the other transaction creation flows. The transactions_type field is the discriminator — set it to "crypto_payout" for an external crypto payout.
Address–network mismatch is irreversible. Sending to a to_address on the wrong network results in permanent loss of funds. Validate the address against the network’s address_regex returned by GET /api/businesses/networks before submitting.

Request structure

Calculating the amount field

The amount field must be the sum of the amount you want the recipient to receive plus the network fee (withdraw_fee from /networks).
Common pitfall. If you submit amount without including withdraw_fee, the recipient receives less than expected (the fee gets subtracted from your submitted amount). Always add the fee on your side.

Request examples

Send 100 USDT with withdraw_fee = 0.8 USDT → amount = 100 + 0.8 = 100.8.

Response — Success, external transfer (201)

Response — Success, internal transfer (201)

If the destination address happens to belong to a Vita Wallet account, the transaction settles instantly as an internal transfer. The response includes recipient_wallet:

Common errors

Important considerations

Your wallet has balance in currency to cover both amount and withdraw_fee.
to_address matches the network’s address_regex.
to_address lives on the same blockchain as network_id. (USDT and USDC exist on multiple networks — ask the recipient to provide both the address and the network name, e.g. “USDT on Tron TRC20”.)
The order field is unique per transaction. On 500/timeout, query GET /api/businesses/transactions?order=<id> before retrying — never retry with a new order.

Step by step

1

Enable

Confirm create_crypto_payout is enabled on your business account.
2

Get networks

GET /api/businesses/networks → list of networks with withdraw_fee, withdraw_min, withdraw_max, address_regex, decimal_withdrawal.
3

Pick currency + network

Choose the currency and network_id that match the recipient’s wallet.
4

Validate address

Match to_address against the network’s address_regex client-side.
5

Compute amount

amount = amount_to_send + withdraw_fee.
6

Submit

POST /api/businesses/transactions with transactions_type: "crypto_payout" and a unique order.
7

Listen

Receive status updates via Webhooks (preferred) or url_notify (legacy).
Test environment. Some networks (e.g. Ethereum Sepolia) are available only in test environments for integration testing without using real funds.