Skip to main content
POST
Create Transfer
A transfer is a same-currency book transfer inside one account. At least one leg must be a virtual account: trading account → virtual account, virtual account → trading account, or virtual account → virtual account. Converting between currencies is done with FX, not with a transfer. Transfers settle synchronously: the source is debited and the destination credited in the same request, and the returned transfer is already completed. Requires an API key with write access on the payments scope.

Path Parameters

string
required
The account’s external ID (starts with acct_)

Headers

string
required
Key for this transfer: any string up to 255 characters, a UUID recommended but not enforced. Scoped to the account: replaying it with the same payload returns the original transfer with 200, and with a different payload 409 IDEMPOTENCY_CONFLICT. See Idempotency.

Request Body

object
required
Balance location to debit. Either {"type": "trading_account"} or {"type": "virtual_account", "virtual_account_id": "va_…"}. The virtual account must belong to this account, be active, and hold the transfer currency.
object
required
Balance location to credit, same shape as source. Trading account → trading account is rejected, and the two legs cannot be the same virtual account.
string
required
Transfer amount as a decimal string, greater than 0. The available balance of the source leg must cover it.
string
required
Currency code, for example USD. Both legs settle in this currency; a trading-account leg uses the trading account’s balance in this currency.
string
Optional reference shown on the transfer (max 255 characters)
string
Optional internal note, never shown to counterparties (max 500 characters)

Response

Returns 201 with the new transfer, or 200 with the existing transfer when the Idempotency-Key was already used with the same payload.
string
Transfer identifier (starts with trf_)
string
Always returns "transfer"
string
Account ID
object
Balance location debited: {"type": "trading_account"} or {"type": "virtual_account", "virtual_account_id": "va_…"}
object
Balance location credited, same shape as source
string
Transfer amount (decimal)
string
Transfer currency code
string
Transfer status. Transfers settle synchronously, so a successful response is always completed; failed is reserved for transfers that could not be posted.
string
Reference, or null
string
Internal note, or null
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
ID of the API key that created the transfer (starts with ak_)
string
Actor that last updated the transfer, or null

Errors

Request Example

Response Example