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

# Payouts Overview

> Send crypto or fiat from your virtual account to a whitelisted external account.

Payouts move funds from your BoomFi virtual account balance to an **external account** you've registered — a crypto wallet or a bank account. See [Whitelist External Account](/whitelist-external-account/overview) to register a destination first.

## Prerequisites

* Funded [Virtual Accounts](/settlement/virtual-accounts)
* A registered, enabled [external account](/whitelist-external-account/overview) to pay out to
* [Authentication](/authentication) (`X-API-KEY`, `X-API-Nonce`, `X-API-Signature`)

Because whitelisting the destination is the step-up-protected step, creating the payout itself needs no per-request OTP — it can be called by an API key alone.

## Create a payout (API)

Address the destination by the `id` or `reference` you registered it with. The currency decides the rail: a fiat symbol settles to the destination's bank account, a digital one to its wallet (and requires `chain_id`).

```bash theme={null}
curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payout" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-API-Nonce: nonce-unique-1" \
  -H "X-API-Signature: <hmac-hex>" \
  -d '{
    "destination_account_reference": "treasury-base",
    "currency": "USDC",
    "chain_id": 8453,
    "amount": "10.00"
  }'
```

| Field | Type | Required | Description |
| - | - | - | - |
| `destination_account_id` / `destination_account_reference` | | exactly one | The registered external account to pay |
| `account_id` / `account_reference` | | no | Which virtual (sub-)account to pay out from; defaults to the org's primary virtual account |
| `amount` | string | yes | Amount in major units |
| `currency` | string | yes | Fiat symbol takes the bank rail, digital takes the chain rail |
| `chain_id` | number | required for digital | Must be omitted for fiat |
| `token_address` | string | no | Only needed when the symbol maps to several tokens on the chain |
| `reference` | string | no | Your own reference for this payout; must be unique |
| `metadata` | object | no | Caller metadata returned on the payment record (max 2 KiB) |

Use the request schema from the API reference (`CreateVirtualPayoutRequest`) for exact fields.

## Direct wallet payout (no whitelisting)

For a one-off crypto send where you don't want to register a destination first, `POST /accounts/virtual/payout/address` still pays out directly to a wallet address:

```bash theme={null}
curl -X POST "https://mapi.boomfi.xyz/v1/accounts/virtual/payout/address" \
  -H "X-API-KEY: sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-API-Nonce: nonce-unique-1" \
  -H "X-API-Signature: <hmac-hex>" \
  -d '{
    "wallet_address": "0xRecipientWallet…",
    "chain_id": 8453,
    "ccy": "USDC",
    "amount": "10.00"
  }'
```

This path is digital-only and has no equivalent for fiat: use the whitelisted flow above for a bank payout, or for any destination you'll pay repeatedly.

## Dashboard

Use the Account experience (`https://app.boomfi.xyz/dashboard/account`) for payout controls in the merchant UI.

<img src="https://mintcdn.com/boom-fi/3iSUMnxX80iQMgo0/payouts/images/account-payout-boomfi.png?fit=max&auto=format&n=3iSUMnxX80iQMgo0&q=85&s=e469c4eac15ddded0577d3c63756293a" alt="BoomFi account payouts" width="1440" height="900" data-path="payouts/images/account-payout-boomfi.png" />

## Events and monitoring

Track resulting payments/transactions in the dashboard and via webhooks. Failed webhook delivery does not reverse an on-chain payout: reconcile carefully.


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