Skip to main content

Preflight a transfer

POST 
/v1/transfers/preflight

Check whether the calling bank's liquidity and limits would cover a transfer of the given asset and amount to the receiving bank if it were submitted now, without creating a transfer, reserving funds or moving value. INTERBANK and BANK_ROUTED are supported.

Requires scope connector:transfers:create, and the calling principal must hold the maker role for the bank (otherwise 403 UNAUTHORIZED_ROLE).

The answer depends only on the two banks, the asset and the amount. The receiving bank is the only counterparty input:

transfer_kindYou sendReceiving bank
INTERBANKasset_id, amount, destination.bank_id; source is optionaldestination.bank_id
BANK_ROUTEDreceiving_bank_id, asset_id, amount (the same body as POST /v1/transfers)receiving_bank_id

Preflight does not validate accounts. For INTERBANK, the account fields (external_account_id, alias, expected_holder_name) may be sent, so you can reuse the body you will submit, but they are ignored and do not change the result. An unregistered account is only detected on submit, where the transfer ends FAILED. For the same banks, asset and amount, both kinds return the same result.

The check covers:

  • Sender capacity: the sending bank's eligible liquidity, including headroom to issue its own tokens under its mint limit.
  • Receiver acceptance: the receiving bank's exposure limit toward the sender's tokens.

A blocking constraint is reported as 200 with would_succeed: false, not as an error. Problems that would make the request itself invalid (ineligible bank or asset, malformed input) are returned as errors:

StatuscodeWhen
400(none)amount.value is not a positive integer, a bank is terminated, or there is no eligible liquidity route between the two banks for the asset (title no eligible liquidity positions found for the source bank, destination holder, and settlement asset). The reason is in title.
403UNAUTHORIZED_SCOPE, UNAUTHORIZED_ROLE, BANK_SCOPE_MISMATCHMissing scope or maker role; source.bank_id is not the calling bank; the receiving bank is the calling bank.
422(none)Body does not match the schema, including an unknown transfer_kind, missing receiving_bank_id, or account fields on a BANK_ROUTED request (title Invalid request body).
422VALIDATION_ERRORdestination.bank_id is missing on an INTERBANK request, or the supplied receiving bank id (destination.bank_id or receiving_bank_id) is not a UUID.
422BANK_NOT_ELIGIBLE, ASSET_NOT_ELIGIBLEA bank or the asset is not eligible for the transfer.

This endpoint has no side effects and takes no Idempotency-Key; repeating a call is always safe. It remains available while the network refuses new transfers (OUTBOUND_HALTED or READ_ONLY). The result is a point-in-time estimate; see TransferPreflight for its limits.

Request​

Responses​

Preflight result. blocking_constraint, remediation and available_headroom are always present and are null when would_succeed is true.