Currency conversions

A currency conversion exchanges funds held in one Axiym account for funds in another. You sell the funds held in one Axiym account and buy funds in another. The sell-side Axiym account is debited and the buy-side Axiym account is credited.

A conversion moves value entirely between Axiym accounts. It does not receive funds from or send funds to a registered external account.

Before creating a conversion, retrieve the conversion pairs available to you. These pairs are the permitted conversion operations for your Axiym accounts.

Conversion pairs are permissions

A conversion pair defines:

• the pair symbol in <sellCurrency>-<buyCurrency> format;
• the sell.currency and sell.paymentRails values;
• the buy.currency and buy.paymentRails values;
• the permitted direction from sell to buy;
• the minAmount, expressed in the sell currency; and
• the pairId used to create the conversion.

The pair does not expose Axiym account identifiers. Within one client's resources, there is at most one Axiym account for each currency and payment-rail combination. The pairId therefore resolves the sell-side and buy-side Axiym accounts server-side. The created conversion response identifies them as sellAccount and buyAccount.

Registering an external account permits deposits and withdrawals. It does not grant permission to convert currencies. Conversion permission comes from the conversion pairs returned in the represented client.

For example:

Pair A and pair B are different permissions. If only pair A is returned, you can convert USD to USDT but not USDT back to USD.

In this example, pair A has the symbol USD-USDT: its sell side is USD and its buy side is USDT. Pair B has the opposite sell and buy sides.

For an onboarded client, /clients/{clientId}/conversion-pairs returns the conversion directions permitted for that client's Axiym accounts. It is not a global catalogue of all currencies Axiym supports.

Conversion workflow

Conversions use a two-step quote-and-confirm flow.

1. Select a pair

Choose the pair whose sell and buy currencies and payment rails match the trade you intend to make. Ensure the amount you intend to sell meets the pair's minAmount.

Confirm that the Axiym accounts resolved by the pair are available for use and that the sell-side account has sufficient balance for the conversion.

2. Create the conversion

Create a conversion using the pair's pairId and a sellAmount expressed in the pair's sell currency.

The response contains the resolved sellAccount and buyAccount, locked rate, expected buyAmount, fee, and a new conversionId. At this point the conversion is PENDING; it has not been executed.

3. Confirm promptly

Confirm the conversionId to accept the quote and begin execution. The locked rate has limited validity. Confirmation after it expires is rejected.

An unconfirmed PENDING conversion remains a draft: it does not execute and is not returned by later conversion reads. Keep the create response until you either confirm the conversion or decide not to proceed.

4. Track the result

Once confirmed, the conversion becomes ACTIVE while it executes. It then becomes COMPLETED, or CANCELED if it cannot complete.

Reading conversion amounts

Use the returned feeAmount and feeCurrency as the authoritative fee for the conversion. Use buyAmount as the amount expected to be credited to the buy-side Axiym account. Do not reconstruct the fee or credited amount by assuming how the fee is applied in a particular conversion direction.

Correlation and reconciliation

Supply an externalReference when you create a conversion to connect it with your own order or transaction record. Axiym echoes it on the conversion.

After completion, reconcile both Axiym account statements: the sellAccount shows the debit and the buyAccount shows the credit, each linked to the conversion identifier.