> For the complete documentation index, see [llms.txt](https://docs.ezeebit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ezeebit.com/wallets-and-withdrawal/request-conversion-quote.md).

# Request Conversion Quote

Quote a fiat and USDT wallet conversion.

**Live:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://api.ezeebit.com/open/api/v1/merchant/wallet/conversion/quote</mark>](https://api.ezeebit.com/open/api/v1/merchant/wallet/conversion/quote)

**UAT:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://uat-api.ezeebit.com/open/api/v1/merchant/wallet/conversion/quote</mark>](https://uat-api.ezeebit.com/open/api/v1/merchant/wallet/conversion/quote)

## Headers

| Name                   | Type   | Required | Value                          |
| ---------------------- | ------ | -------- | ------------------------------ |
| Content-Type           | string | Y        | application/json               |
| Ezeebit-Timestamp      | long   | Y        | Unix timestamp in milliseconds |
| Ezeebit-Nonce          | string | Y        | 32 characters                  |
| Ezeebit-Certificate-SN | string | Y        | API key issued by Ezeebit Pay  |
| Ezeebit-Signature      | string | Y        | Uppercase SHA512 signature     |

## Request Body

{% tabs %}
{% tab title="Your wallet" %}

```json
{
  "from": "ZAR",
  "to": "USDT",
  "amount": 1000.00,
  "sourceWalletId": "9865391b-3f2a-4a2b-8c3d-abcdef123456"
}
```

{% endtab %}

{% tab title="Customer account" %}

```json
{
  "from": "ZAR",
  "to": "USDT",
  "amount": 1000.00,
  "customerAccountId": "cust-1001"
}
```

{% endtab %}
{% endtabs %}

## Form data

| Parameter         | Type   | Required    | Description                                                                                 |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------- |
| from              | string | Yes         | Your fiat wallet currency or `USDT`.                                                        |
| to                | string | Yes         | The other supported currency.                                                               |
| amount            | double | Yes         | Source amount. Greater than `0`.                                                            |
| sourceWalletId    | string | Conditional | Owned wallet matching `from`. Send this or `customerAccountId`, not both.                   |
| customerAccountId | string | Conditional | Convert for one of your customer accounts instead. Send this or `sourceWalletId`, not both. |

Only fiat ↔ USDT conversions are supported. Check `expiresAt` before accepting. Quotes normally last 30 seconds. Volatility can shorten the window to 15 seconds.

With `customerAccountId`, the USDT side of the conversion is always the [customer account](https://docs.ezeebit.com/customer-accounts/customer-account-details.md) and the fiat side is always your own fiat wallet.

## Response

| Status | Description                                                  |
| ------ | ------------------------------------------------------------ |
| 200    | Quote created                                                |
| 10054  | Unsupported pair or wallet                                   |
| 10055  | Invalid amount                                               |
| 10056  | Live rate unavailable                                        |
| 10057  | Insufficient market depth                                    |
| 10058  | Conversion temporarily unavailable                           |
| 10108  | Customer account is frozen                                   |
| 10121  | Customer account not found                                   |
| 10122  | Send exactly one of `sourceWalletId` and `customerAccountId` |
| 10127  | Amount is below the minimum allowed for conversion           |
| 10128  | Amount exceeds the maximum allowed for conversion            |

{% tabs %}
{% tab title="200" %}

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "quoteId": "c2a4f8e0-1b3d-4c5e-9f7a-6b8d0e2f4a1c",
    "from": "ZAR",
    "to": "USDT",
    "amount": "1000.00",
    "outputAmount": "52.63",
    "rate": "19.0000",
    "expiresAt": 1755680430000,
    "quoteValiditySeconds": 30,
    "customerAccountId": null
  }
}
```

{% endtab %}

{% tab title="10056" %}

```json
{
  "code": 10056,
  "msg": "Unable to fetch a live exchange rate — please try again",
  "data": null
}
```

{% endtab %}

{% tab title="10128" %}

```json
{
  "code": 10128,
  "msg": "Amount exceeds the maximum allowed for conversion",
  "data": null
}
```

{% endtab %}
{% endtabs %}
