# Currency conversions

Product: Account API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.sandbox.axiym.io/account-api/concepts/currency-conversions

A currency conversion exchanges funds between two Axiym accounts. The
sell-side account is debited and the buy-side account is credited.

## Conversion pairs are permissions

A conversion pair defines a permitted exchange between two Axiym accounts:

* the currency and payment rail on each side;
* the direction from the currency sold to the currency bought; and
* the minimum amount that can be sold.

Available pairs describe the conversions permitted for your Axiym accounts.
They are not a catalogue of every currency Axiym supports.

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.

## Conversion workflow

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



```mermaid
flowchart TD
  pairs["View permitted conversions"] --> select["Select direction and sell amount"]
  select --> create["Create conversion"]
  create --> pending["PENDING · rate locked"]
  pending --> review["Review amounts, rate, and fee"]
  review --> confirm["Confirm before expiry"]
  confirm --> active["ACTIVE"]
  active --> completed["COMPLETED"]
  active --> canceled["CANCELED"]

  class pairs,select,create,review,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 permitted direction and the amount to sell. The amount must meet
the pair’s minimum, and the sell-side account must have sufficient funds.

### 2. Create and review the quote

Creating a conversion locks a rate and provides the expected amount to be
received and the fee. Review these terms before confirming. The conversion
is `PENDING` and has not executed.

### 3. Confirm before expiry

Confirmation accepts the quote and begins execution. The locked rate has
limited validity; an expired quote cannot be confirmed. An unconfirmed
conversion does not execute.

### 4. Follow the outcome

A confirmed conversion is `ACTIVE` while it executes. It becomes `COMPLETED`
when the exchange finishes, or `CANCELED` if it cannot complete.

## Conversion lifecycle

| 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.                   |

## Amounts, rate, and fee

| Term        | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| Sell amount | The amount exchanged from the sell-side account, in its currency. |
| Buy amount  | The amount expected in the buy-side account, net of the fee.      |
| Rate        | Units of buy currency per one unit of sell currency.              |
| Fee         | The charge for the conversion, with its amount and currency.      |

The quote provides the amounts, rate, and fee together so you can review the
exchange before accepting it.

## Conversion record and account balances

A completed conversion produces two balance movements: a debit on the
sell-side account and a credit on the buy-side account. Both account
statements link those movements to the conversion.

For selecting a pair, creating and confirming a quote, and tracking the
result, follow [Execute a conversion](/account-api/integration-guide/execute-a-conversion).