Quickstart: Make your first conversion

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

Integration tools

Postman collection — Try requests in Sandbox. Set clientId and clientSecret, then send the Auth token request; the collection saves the token for subsequent requests.
Integrate using AI — Documentation formats and an optional integration prompt for your coding agent.

Before you start

You need:

sandbox credentials with the TRADE scope;
an allowlisted egress address;
two active Axiym accounts 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 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 AXIYM_CLIENT_ID and AXIYM_CLIENT_SECRET to your sandbox OAuth credentials.

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"

Set AXIYM_ACCESS_TOKEN to the returned access_token in your shell. Keep it secure; the remaining requests send it as a bearer token.

2. List your Axiym accounts

curl "https://partner-api.sandbox.axiym.io/api/v1/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/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. Your company has 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

Set PAIR_ID to the pairId returned for your selected pair and SELL_CURRENCY to its sell.currency. Set SELL_AMOUNT to a decimal string that meets minAmount and does not exceed the sell-side balance. The USD-USDT pair above is illustrative; use values returned for your organization.

Generate separate keys once for each new conversion attempt:

CREATE_IDEMPOTENCY_KEY=$(uuidgen)
CONFIRM_IDEMPOTENCY_KEY=$(uuidgen)

Keep these keys for the attempt. When retrying after a timeout or lost response, rerun only the relevant request with its original key, path, and payload. Generate fresh keys when starting a new conversion, including after quote expiry.

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 @- <<EOF
{
  "pairId": "$PAIR_ID",
  "sellAmount": { "amount": "$SELL_AMOUNT", "currency": "$SELL_CURRENCY" },
  "externalReference": "sandbox-$CREATE_IDEMPOTENCY_KEY"
}
EOF

The response is a PENDING conversion containing its conversionId, locked rate, resolved sellAccount and buyAccount, expected buyAmount, and fee. Review these values before confirming. Set CONVERSION_ID to the returned conversionId, SELL_ACCOUNT_ID to sellAccount.accountId, and BUY_ACCOUNT_ID to buyAccount.accountId for the following requests.

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 the separate confirmation key generated for this attempt.

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"

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

If it is still ACTIVE, retrieve it again later. If it is CANCELED, inspect the reason and resolve the issue before starting a new attempt.

7. Verify the account movements

Once the conversion is COMPLETED, retrieve both account statements:

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

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

Find entries with relatedResourceType: CONVERSION and relatedResourceId equal to CONVERSION_ID. Verify a sell-side DEBIT matching sellAmount and a buy-side CREDIT matching buyAmount, including their currencies. Follow pagination using pageInfo.endCursor as after while hasNextPage is true if the entries are not on the first page.

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;
retrieve the conversion by conversionId and observe COMPLETED; and
verify the corresponding debit and credit in both account statements.

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