# Quickstart: Make your first 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/quick-start

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](/direct-trade-api/api-reference#downloads)** — 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](/direct-trade-api/integration-guide/integrate-with-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](/direct-trade-api/integration-guide/access-setup) 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:

```text
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.

```sh
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

```sh
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

```sh
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.

```json
{
  "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:

```sh
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.

```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 @- <<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.

```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"
```

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

```sh
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:

```sh
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](/direct-trade-api/integration-guide/sandbox-testing)
for the appropriate test approach for each rail.

Next, read [Execute a conversion](/direct-trade-api/integration-guide/execute-a-conversion)
for production handling and reconciliation guidance.