# Execute a conversion

Product: Direct Trade API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/direct-trade-api/integration-guide/execute-a-conversion

Conversions use a two-step create-and-confirm workflow. Creation locks a rate;
confirmation accepts it and starts execution.

In sandbox, conversions use isolated test balances and produce sandbox ledger
movements. They do not move real funds or settle across an external payment
network.

## 1. Discover the permitted direction

Retrieve the current Axiym accounts and conversion pairs immediately before
selecting a trade path:

```sh
curl "https://partner-api.sandbox.axiym.io/api/v1/accounts" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

```sh
curl "https://partner-api.sandbox.axiym.io/api/v1/conversion-pairs" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

Choose the `pairId` whose `sell` and `buy` currencies and payment rails match
the direction you intend to trade.

Your company has at most one Axiym account for each currency and
payment-rail combination. Match the pair sides to the
Axiym account list as follows:

* match `sell.currency` and `sell.paymentRails` to the sell-side Axiym account;
* match `buy.currency` and `buy.paymentRails` to the buy-side Axiym account;
* confirm both matching accounts are active;
* confirm the sell-side account has sufficient balance; and
* confirm the intended `sellAmount` is at least the pair's `minAmount`.

The pair does not expose account identifiers. Its `pairId` resolves the
matching Axiym accounts server-side. Do not reverse the pair sides yourself; the
reverse direction requires its own pair returned by this endpoint.

## 2. Create and inspect the quote

Set `SELL_CURRENCY` to the selected pair's `sell.currency` and `SELL_AMOUNT`
to the decimal amount you intend to sell. It must meet the pair's `minAmount`
and fit within the sell-side account balance.

```sh
curl --request POST "https://partner-api.sandbox.axiym.io/api/v1/conversions" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $CREATE_IDEMPOTENCY_KEY" \
  --data "{\
    \"pairId\": \"$PAIR_ID\",\
    \"sellAmount\": {\"amount\": \"$SELL_AMOUNT\", \"currency\": \"$SELL_CURRENCY\"},\
    \"externalReference\": \"$YOUR_REFERENCE\"\
  }"
```

Before confirming, inspect:

| Field                           | Check                                                                      |
| ------------------------------- | -------------------------------------------------------------------------- |
| `sellAccount` and `buyAccount`  | They match the Axiym accounts inferred from the pair's sell and buy sides. |
| `sellAmount`                    | It matches the amount you requested.                                       |
| `buyAmount`                     | It is the amount expected in the buy-side Axiym account, net of the fee.   |
| `rate`                          | It is acceptable for this transaction.                                     |
| `fee` (`amount` and `currency`) | It matches your business rules.                                            |
| `status`                        | It is `PENDING`.                                                           |

Keep the full create response, including `conversionId`, for review. A pending,
unconfirmed quote is returned only by the create request and does not execute.

## 3. Confirm the conversion

```sh
curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/conversions/$CONVERSION_ID/confirm" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Idempotency-Key: $CONFIRM_IDEMPOTENCY_KEY"
```

Create and confirm are distinct operations and require distinct idempotency
keys. If either HTTP response is lost, retry that exact operation with its
original key.

Confirm promptly. If the locked quote expires, confirmation fails and you
must create a new conversion to receive a new rate.

The `conversion.created` event is emitted when the quote is created and awaits
confirmation. Use the retained create response while it is unconfirmed.
Confirmation starts execution with status `ACTIVE` and makes the conversion
available through subsequent reads.

## 4. Track execution

Retrieve the conversion by ID until it reaches a terminal state:

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/conversions/$CONVERSION_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

`ACTIVE` means execution is in progress. `COMPLETED` and `CANCELED` are
terminal. When canceled, inspect `reasonCode` before deciding whether a new
conversion is appropriate.

## 5. Reconcile both Axiym accounts

A completed conversion produces a debit on `sellAccount` and a credit on
`buyAccount`. Retrieve both Axiym account statements and join entries using
`relatedResourceType: CONVERSION` and `conversionId`.

Use `externalReference` to correlate the conversion with your business record;
do not use it as a substitute for an idempotency key.