> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert currencies

> Lock an exchange rate with a quote, execute the conversion, and track it to settlement.

[Stablecoin Account API Publisher Disclaimer](/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer)

Conversions exchange one currency in your account for another — crypto to fiat, fiat to crypto, or crypto to crypto — at a rate you lock in advance. The flow is always two calls: create a **quote**, then create the **conversion** referencing it before the quote expires.

<Info>
  **Prerequisites**

  * An API token sent as the `x-auth-token` header
  * Sufficient `available_balance` in the selling currency
</Info>

## Step 1: Create a quote

Call [Create Quote](/stablecoin-account/v1.6/api-reference/create-quote) with the currency pair, the amount, and which side the amount fixes:

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/ramp/conversion/quote \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sell_currency": "USDT",
    "buy_currency": "SGD",
    "amount": "100",
    "fixed_currency": "USDT"
  }'
```

`fixed_currency` names the side `amount` applies to — fix the sell side to spend an exact amount, or the buy side to receive an exact amount.

<Note>
  Pair restrictions: for crypto-to-crypto, only USDT paired with one other supported coin is allowed. If either side is a volatile asset (for example BTC or ETH), only USDT can be the fixed currency.
</Note>

**Response:**

```json theme={null}
{
  "code": 200,
  "message": "Success",
  "data": {
    "quote_id": "958813b7-8523-4b93-862e-46eddb87b56d",
    "sell_currency": "USDT",
    "sell_amount": "100",
    "buy_currency": "SGD",
    "buy_amount": "133.84",
    "currency_pair": "USDTSGD",
    "direct_rate": "1.3384723",
    "inverse_rate": "0.74712043",
    "processing_fee": "0",
    "network_fee": "0",
    "valid_from": "2026-04-27T10:47:26+08:00",
    "valid_to": "2026-04-27T10:50:26+08:00"
  }
}
```

The quoted rate holds between `valid_from` and `valid_to`. If the window passes before you execute, request a new quote — an expired `quote_id` is rejected.

## Step 2: Execute the conversion

Call [Create Conversion](/stablecoin-account/v1.6/api-reference/create-conversion) with the `quote_id` and the amounts exactly as quoted, plus an idempotency key:

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/ramp/conversion \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "958813b7-8523-4b93-862e-46eddb87b56d",
    "sell_currency": "USDT",
    "sell_amount": "100",
    "buy_currency": "SGD",
    "buy_amount": "133.84",
    "reason": "treasury rebalance"
  }'
```

The response returns the conversion order — `order_id`, `short_order_id`, `status`, both currency sides, the `quote_price` used, and fees. `order_type` is `Sell` or `Buy` depending on direction.

## Step 3: Track the conversion

Conversion status flows through `Submitted` / `Pending` to `Success`, `Failed`, or `Submit Failed`. Updates arrive on the [Conversion webhook](/stablecoin-account/v1.6/webhooks/conversion):

| Event type                        | Meaning                |
| --------------------------------- | ---------------------- |
| `ramp.conversion.trade.pending`   | Conversion in progress |
| `ramp.conversion.trade.completed` | Conversion completed   |
| `ramp.conversion.trade.failed`    | Conversion failed      |

Query on demand with [Retrieve Conversion](/stablecoin-account/v1.6/api-reference/retrieve-conversion) or reconcile with [List Conversions](/stablecoin-account/v1.6/api-reference/list-conversions) (filter by `order_status`, `order_id`, or `balance_currency`). Completed conversions carry a `settle_time`.

## Related

* [Create Quote API](/stablecoin-account/v1.6/api-reference/create-quote)
* [Create Conversion API](/stablecoin-account/v1.6/api-reference/create-conversion)
* [Conversion webhook](/stablecoin-account/v1.6/webhooks/conversion)
* [Manage asset balances](/stablecoin-account/v1.6/guide/manage-asset-balances) — conversions appear as `Sell` / `Buy` / `Swap` in the ledger