Quickstart: Make your first conversion

This quickstart validates the core Trade API flow: authenticate, discover a permitted conversion, lock a rate, confirm it, and retrieve the result.

Select the client

Choose the onboarded client before starting. The partner token authenticates your partnership; every business request below uses that client's /clients/{clientId} path. Use only identifiers returned for the same client.

Before you start

You need:

sandbox credentials with the TRADE scope;
an allowlisted egress address;
two active Axiym accounts in the chosen scope connected by a conversion pair; and
enough balance in the Axiym account matching the pair's sell side to meet its minAmount.

See Access and environments if these have not been provisioned.

Axiym funds the client's sell-side test account provisioned for this quickstart. You do not need to send a bank payment or blockchain transfer before starting.

The examples use the sandbox base URL:

https://partner-api.sandbox.axiym.io/api/v1

Set CLIENT_ID to the Axiym identifier of the represented sandbox client.

1. Authenticate

Exchange your client credentials for an access token.

curl --request POST "https://partner-api.sandbox.axiym.io/api/v1/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=$AXIYM_CLIENT_ID" \
  --data-urlencode "client_secret=$AXIYM_CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=TRADE"

Store the returned access_token securely and send it as a bearer token on the remaining requests.

2. List your Axiym accounts

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

Confirm that the Axiym accounts you intend to use are ACTIVE. Record their accountId, currency, balance, and paymentRails values.

3. Find a permitted conversion pair

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

Choose a pair whose sell and buy currencies and payment rails match the direction you want. The pair provides the minimum sell amount. Its pairId resolves the corresponding Axiym accounts server-side.

{
  "pairId": "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b",
  "pair": "USD-USDT",
  "sell": {
    "currency": "USD",
    "paymentRails": "ZENUS_BANK"
  },
  "buy": {
    "currency": "USDT",
    "paymentRails": "TRON"
  },
  "minAmount": "100.00"
}

Match sell.currency and sell.paymentRails to the Axiym account list from step 2. Match buy.currency and buy.paymentRails in the same way. Within the selected client, there is at most one Axiym account for each currency and payment-rail combination. Confirm that both matching accounts are active and that the sell-side account has sufficient balance.

4. Create a conversion

Create the conversion using the selected pairId. sellAmount is expressed in the pair's sell currency.

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: 52ea1c64-37e8-42f7-8af8-dc31233825a1" \
  --data '{
    "pairId": "7c9e1a3b-5d2f-4e8a-9b0c-6d4f2a8e1c3b",
    "sellAmount": "100.00",
    "externalReference": "sandbox-conversion-001"
  }'

The response is a PENDING conversion containing its conversionId, locked rate, resolved sellAccount and buyAccount, expected buyAmount, and fee. Review these values before confirming.

An unconfirmed conversion does not execute and is not returned by subsequent read operations. Keep the create response until you confirm it or let the quote expire.

5. Confirm before the quote expires

Confirming accepts the locked rate and starts execution. Use a new idempotency key for the confirmation operation.

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: 1c60e7cb-0bb5-43c8-b1b8-aaf02673091f"

A successful response has status ACTIVE, meaning the conversion is executing. Confirmation after the quote expires is rejected; create a new conversion to obtain a new rate.

6. Retrieve the result

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

The conversion eventually becomes:

COMPLETED when the sell-side debit and buy-side credit complete; or
CANCELED when execution cannot complete, with reasonCode when available.

Success criteria

You have completed the quickstart when you can:

obtain an access token;
match the intended sell and buy sides to your Axiym accounts;
identify the permitted direction by pairId;
create and confirm a conversion using separate idempotency keys; and
retrieve the confirmed conversion by conversionId.

This confirms access, permissions, conversion handling, and sandbox ledger movements. It does not validate settlement over an external bank or blockchain network. See Sandbox testing for the appropriate test approach for each rail.

Next, read Execute a conversion for production handling and reconciliation guidance.

On this page