# Currency conversions Product: Client Trade API Guides follow API reference 0.3.0 and event reference 0.2.0. Canonical page: https://docs.axiym.io/trade-api/concepts/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 an address book entry. 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 `-` 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: ```mermaid flowchart LR usd["USD Axiym account"] -->|Pair A| usdt["USDT Axiym account"] usdt -->|Pair B| usd class usd,usdt accountNode classDef accountNode stroke-width:1.5px ``` 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. ```mermaid flowchart TD pairs["List permitted pairs"] --> select["Select pairId and sell amount"] select --> create["Create conversion"] create --> pending["PENDING ยท rate locked"] pending --> confirm["Confirm before expiry"] confirm --> active["ACTIVE"] active --> completed["COMPLETED"] active --> canceled["CANCELED"] class pairs,select,create,confirm actionNode class pending,active statusNode class completed completedNode class canceled stoppedNode classDef actionNode stroke-width:1.25px classDef statusNode stroke-width:1.5px classDef completedNode stroke-width:1.5px classDef stoppedNode stroke-width:1.5px ``` ### 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. The `conversion.created` event is emitted when the quote is created and is awaiting confirmation. It does not mean execution has started. Confirmation changes the status to `ACTIVE` and makes the conversion available through conversion reads. ### 4. Track the result Once confirmed, the conversion remains `ACTIVE` while it executes. It then becomes `COMPLETED`, or `CANCELED` if it cannot complete. | Status | Meaning | | ----------- | ------------------------------------------------------ | | `PENDING` | The rate is locked and awaiting confirmation. | | `ACTIVE` | The conversion was confirmed and is executing. | | `COMPLETED` | The sell-side debit and buy-side credit completed. | | `CANCELED` | The conversion did not complete; inspect `reasonCode`. | ## Reading conversion amounts | Field | Meaning | | ------------- | ------------------------------------------------------------------- | | `sellAccount` | The Axiym account from which the sold funds are debited. | | `sellAmount` | Amount sold, expressed in the sell currency. | | `buyAccount` | The Axiym account to which the purchased funds are credited. | | `buyAmount` | Amount bought and credited to the buy-side account, net of the fee. | | `rate` | Units of buy currency per one unit of sell currency. | | `fee` | Fee charged for the conversion, as `{ amount, currency }`. | Use the returned `fee.amount` and `fee.currency` 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.