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:

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

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.

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:

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

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:

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.