> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Crypto Payout

> Send USDT or USDC from your business wallet to an external blockchain address.

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.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> **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

| Key | Description |
| - | - |
| `transactions_type` | Must be `"crypto_payout"`. |
| `currency` | Cryptocurrency to send (e.g. `"USDT"`, `"USDC"`). Must be active in your wallet. |
| `amount` | Amount to send. Must be ≥ `withdraw_min` and ≤ `withdraw_max` for the selected network, **and must include the network fee** (see below). |
| `to_address` | Destination blockchain address. Must match the network's `address_regex`. |
| `network_id` | ID of the network returned by `GET /api/businesses/networks`. |
| `order` | Unique order identifier (idempotency key). |
| `url_notify` | Legacy IPN URL (use Webhooks instead). |

## Calculating the `amount` field

> [!NOTE]
>
> The `amount` field must be the **sum of the amount you want the recipient to receive plus the network fee** (`withdraw_fee` from `/networks`).

```
amount = amount_to_send + withdraw_fee
```

> [!WARNING]
>
> **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

> [tab] USDT on Tron (TRC20)
>
> Send 100 USDT with `withdraw_fee = 0.8` USDT → `amount = 100 + 0.8 = 100.8`.
>
> ```json theme={null}
> {
>   "transactions_type": "crypto_payout",
>   "currency": "USDT",
>   "amount": "100.8",
>   "to_address": "TXyZ123abc456def789ghi012jkl345mno678",
>   "network_id": 7,
>   "order": "CRYPTO-001",
>   "url_notify": "https://example.com/webhook"
> }
> ```

> [tab] USDC on Ethereum (ERC20)
>
> Send 250 USDC with `withdraw_fee = 4.0` USDC → `amount = 250 + 4.0 = 254.0`.
>
> ```json theme={null}
> {
>   "transactions_type": "crypto_payout",
>   "currency": "USDC",
>   "amount": "254.0",
>   "to_address": "0xA3f1C9B2e4D6F8a0bC1D2E3f4A5b6C7D8E9F0a1B",
>   "network_id": 4,
>   "order": "CRYPTO-002",
>   "url_notify": "https://example.com/webhook"
> }
> ```

> [tab] BTC on Bitcoin network
>
> Native Bitcoin transfer. Confirm `address_regex` matches the beneficiary's address format (bech32, P2PKH, etc.).
>
> ```json theme={null}
> {
>   "transactions_type": "crypto_payout",
>   "currency": "BTC",
>   "amount": "0.0001",
>   "to_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
>   "network_id": 1,
>   "order": "CRYPTO-003",
>   "url_notify": "https://example.com/webhook"
> }
> ```

## Response — Success, external transfer (201)

```json theme={null}
{
  "transaction": {
    "id": "ae3d367c-f49d-4489-954e-5191e548ffd8",
    "type": "business_transaction",
    "attributes": {
      "status": "checking",
      "currency": "usdt",
      "amount": "10.71",
      "total": "11.0",
      "fee_value": "0.29",
      "total_fee": "0.29",
      "created_at": "2025-12-15T16:15:50.663Z",
      "order": "CRYPTO-001",
      "category": "vita_sent",
      "recipient_wallet": null,
      "vita_transaction_id": "ae3d367c-f49d-4489-954e-5191e548ffd8",
      "tracking_url": "https://tracking.vitawallet.io/..."
    }
  }
}
```

## 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`:

```json theme={null}
{
  "transaction": {
    "id": "b18a3ef8-3b4f-4357-9e2a-6f0ebbcfc0cb",
    "attributes": {
      "status": "completed",
      "currency": "usdt",
      "amount": "11.0",
      "total": "11.0",
      "fee_value": "0.0",
      "order": "CRYPTO-002",
      "category": "vita_sent",
      "recipient_wallet": {
        "uuid": "44bced7b-7c69-45a8-9392-259aa676af60",
        "token": "master",
        "is_master": true
      }
    }
  }
}
```

## Common errors

> [accordion] Error 507 — Amount below minimum
>
> ```json theme={null}
> {
>   "error": { "code": 507, "message": "Amount is below minimum allowed: 10.0 USDT" }
> }
> ```

> [accordion] Error 509 — Insufficient balance
>
> ```json theme={null}
> {
>   "error": { "code": 509, "message": "Insufficient balance in business account" }
> }
> ```

## Important considerations

> [!TIP]
>
> Your wallet has balance in `currency` to cover both `amount` and `withdraw_fee`.

> [!TIP]
>
> `to_address` matches the network's `address_regex`.

> [!TIP]
>
> `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".)

> [!TIP]
>
> 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).

> [!NOTE]
>
> **Test environment.** Some networks (e.g. Ethereum Sepolia) are available only in test environments for integration testing without using real funds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.