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

# Preview Wallet Conversion

> Preview the exchange rate, fee, and net amount for converting a XAF/XOF wallet into your USD wallet — without moving any funds.

## Overview

`POST /partner/wallets/preview-conversion` is a read-only calculation: it returns the exchange rate, gross/net amounts, and fee for converting `amount` (in the source wallet's currency) into the destination USD wallet, computed from your company's configured exchange rate and fee tables. **No funds are moved.**

Call this before [`POST /partner/wallets/xaf-usd-conversion`](/api-reference/endpoint/post-wallet-xaf-usd-conversion) to show the converted amount to your own user before they confirm.

## When to use it

* You want to show "You will receive \~\$X" before a user confirms a top-up of their USD wallet.
* You want to check the current rate without committing to a conversion.

## Prerequisites

* An active wallet in `XAF` or `XOF`, and an active `USD` wallet, both belonging to your company.
* An exchange rate configured for your company (contact support if `POST` returns a 400 about a missing rate).

## Request

### Headers

| Name | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer <access_token>` |
| `Content-Type` | Yes | `application/json` |

### Body

| Field | Type | Required | Constraints / format |
| - | - | - | - |
| `source_wallet_id` | string | Yes | UUID of a wallet in `XAF` or `XOF`. |
| `destination_wallet_id` | string | Yes | UUID of your `USD` wallet. |
| `amount` | number | Yes | Amount to convert, in the source currency, `> 0`. |

```json theme={null}
{
  "source_wallet_id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "destination_wallet_id": "w9f8e7d6-c5b4-3210-fedc-ba0987654321",
  "amount": 50000
}
```

## Response

### 200 — Preview

```json theme={null}
{
  "sourceCurrency": "XAF",
  "destinationCurrency": "USD",
  "rate": 640,
  "sourceAmount": 50000,
  "grossAmount": 78.13,
  "feeAmount": 0.5,
  "netAmountToCredit": 77.63
}
```

| Field | Type | Description |
| - | - | - |
| `rate` | number | Current exchange rate (destination currency → source currency, e.g. `1 USD = 640 XAF`). |
| `grossAmount` | number | `sourceAmount / rate`, before fee. |
| `feeAmount` | number | Fee charged on the destination side (USD), per your fee configuration. |
| `netAmountToCredit` | number | `grossAmount - feeAmount` — what would actually be credited. |

### Error responses

| Status | `message` example | Trigger |
| - | - | - |
| `400` | `"Conversions are only allowed from XAF or XOF wallets. Source wallet currency: ..."` | `source_wallet_id` is not a XAF/XOF wallet. |
| `400` | `"Conversions can only be made to USD wallets. Destination wallet currency: ..."` | `destination_wallet_id` is not a USD wallet. |
| `400` | `"Source wallet not found"` / `"Destination wallet not found"` | Wallet ID doesn't exist or doesn't belong to your company. |
| `400` | `"No active exchange rate found for USD to XAF. Please contact support."` | No exchange rate configured for your company. |

## Code examples

```bash cURL theme={null}
curl -X POST https://api.cartevo.co/api/v1/partner/wallets/preview-conversion \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_wallet_id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "destination_wallet_id": "w9f8e7d6-c5b4-3210-fedc-ba0987654321",
    "amount": 50000
  }'
```

## Related

* [`POST /partner/wallets/xaf-usd-conversion`](/api-reference/endpoint/post-wallet-xaf-usd-conversion) — actually perform the conversion.
* [`GET /wallets`](/api-reference/endpoint/get-wallets) — list your wallets and their IDs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.