Skip to main content
POST
Preview a payout
Stable since 2025-01-01 — unchanged in 2026-04-14.

Authorizations

Authorization
string
header
required

Access token from POST /auth (the data.access_token value).

x-api-key
string
header
required

API key issued by Kira. Required on every request, including /auth.

Headers

X-Api-Version
string

Optional. The date-versioned API version to apply for this request (e.g. 2026-04-14). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default.

Example:

"2026-04-14"

Path Parameters

virtual_account_id
string<uuid>
required

Virtual account UUID.

Body

application/json

PayoutPreviewRequest. Either recipient_id or account_type is required. There is no top-level currency field — payouts are always priced in USD.

amount
string
required

Positive USD decimal amount; up to 2 decimals for fiat / fiat-to-crypto, up to 8 for crypto-funded previews.

recipient_id
string<uuid>

UUID of a saved recipient. Provide this or account_type.

account_type
enum<string>

Rail to estimate fees without a saved recipient. Provide this instead of recipient_id.

Available options:
WIRE,
ACH,
WALLET
wallet_network
enum<string>

Required when account_type is WALLET without recipient_id.

Available options:
solana,
polygon,
tron
wallet_token
enum<string>

Required with wallet_network. Note tron does not support USDC.

Available options:
USDC,
USDT
inverse_calculation
boolean

When true, treat amount as the recipient amount and solve for the source amount.

payment_instructions
object

Supply to preview a crypto-funded payout.

client_markup
object

Override your default markup.

extra_info
object
create_quote
boolean

When true, the preview also reserves a quote; the response includes quote_id and quote_expires_at.

Response

Payout preview.

PayoutPreview. The quote_id and quote_expires_at fields are present only when the request set create_quote: true; pass that quote_id to POST /v1/virtual-accounts/{virtual_account_id}/payout to execute at the exact previewed amount, fees, and FX rate. The quote must belong to the same client and must not be expired or already used. The default quote lifespan is 15 minutes.

amount
string

Source amount, USD, 2 decimals.

currency
string

Always USD.

Example:

"USD"

fees
object

The fee breakdown — see the known-limitations guide: fees.total and fees.total_fees are identical.

recipient_amount
string

Amount after fees — USD with 2 decimals for bank rails; the stablecoin amount with up to 6 decimals for fiat-to-crypto.

recipient_currency
string

USD for bank rails; USDC/USDT for fiat-to-crypto.

payment_instructions
object

Echoed back only when the request supplied it.

quote_id
string

Present only when the request set create_quote: true. Redeem on POST /v1/virtual-accounts/{virtual_account_id}/payout.

quote_expires_at
string

Present only when the request set create_quote: true. ISO-8601; default quote lifespan is 15 minutes.