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.

Select the client before starting and use /clients/{clientId} throughout. Use a pairId returned for that client; never reuse a pair or account identifier from another client.

1. Discover the permitted direction

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

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

curl "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/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.

Within the selected client, there is 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

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

Before confirming, inspect:

Keep the returned conversionId. A pending, unconfirmed quote is returned only by the create request and does not execute.

3. Confirm the conversion

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/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.

4. Track execution

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

curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/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.