Create FX trade

Create an FX trade to convert wallet funds and either pay out to a beneficiary or move funds into another wallet.

Sender information

The sender object is required when using convertWalletPayout as the paymentType and you are a fintech or financial institution making a payout on behalf of an underlying customer from your master wallet. It is not required for convertWithinWallets transfers.

Not required if you are:

  • An Atlas for Platform client — sender identity is established through the sub-account's KYB data
  • A corporate sending on your own principal basis (e.g. supplier payments, payroll, merchant settlements)
  • Initiating a payout from a sub-account — sender information is inherited from the sub-account directly
📘

If you are unsure whether your use case requires a sender object, contact [email protected] before going live. See the Sender object guide for full field requirements.

📘

Check your base URL

Each Verto service has its own host. Use the base URL shown in the endpoint definition on this page — do not reuse a host from another service.

Sandbox hosts end in -sandbox.vertofx.com; the matching production host replaces sandbox with beta. Sending a request to the wrong environment returns 403.

See URLs (Sandbox vs Production) for the full service-by-service list.



Body Params
enum
required

Selects the flow. convertWithinWallets converts between two of your own wallets; convertWalletPayout converts and pays the proceeds out to a beneficiary.

Allowed:
number

Wallet the funds are converted from. Use this with sourceAmount for a single funding wallet, or use sources to fund from several.

sources
array of objects

Fund the conversion from more than one wallet. Each entry gives a walletId and the amount to draw from it. Use instead of sourceWalletId / sourceAmount.

sources
number

Amount to sell, in the source currency. Send either sourceAmount or targetAmount — whichever side of the trade is fixed.

number

Amount to buy, in the target currency. Send either sourceAmount or targetAmount — whichever side of the trade is fixed.

number
required

Wallet that receives the converted funds.

string | null

Your own reference for this trade. Stored and returned on the trade, not used for de-duplication.

number | null

Mandatory for APIKey login, if they are adding supportingDocS3Key.

string | null

Key of a supporting document previously uploaded through the upload-link endpoint.

string
required

Quote token returned by Get FX rate or Get FX quote. It locks the rate for this trade and expires with the quote.

string | null

Mandatory for APIKey login, helps identify a unique payment request. If the same value is sent in a duplicate payment request, it will be rejected.

fxMarkup
object

Markup to apply to this trade, as either a percentage or a rate. Overrides your configured default markup.

integer | null
≥ 0

Estimated whole hours (non-negative integer) for funds to reflect in the target account.

Responses

Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json