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

# Convert Currency (Quote)

> Get a quote converting an amount between two currencies using your company's configured exchange rates. Read-only — does not move money.

## Overview

`POST /company/exchange-rates/convert` returns a **quote** for converting an amount between two currencies, using the exchange rates configured for your company. This call is **read-only** — it does not move any money. To execute a conversion, follow up with [`POST /wallets/deposit`](/api-reference/endpoint/post-wallets-deposit), passing the rate returned here.

## When to use it

* Show a customer or operator the converted amount before they confirm a wallet-to-wallet conversion.
* Compute the destination amount before calling [`POST /wallets/deposit`](/api-reference/endpoint/post-wallets-deposit).

## Where rates come from

The rate returned is **your company's** configured rate for the `(fromCurrency, toCurrency)` pair, not a system-wide market rate. If you have not configured a rate, the call returns `400`. Configure rates via the dashboard (or via the company exchange-rate management endpoints).

## Quote validity

The returned quote includes an `exchangeRateId` reflecting the rate version used. Quotes do not have a built-in expiry, but Cartevo treats stale rates conservatively — if the underlying rate is updated, the original `exchangeRateId` is no longer accepted by [`POST /wallets/deposit`](/api-reference/endpoint/post-wallets-deposit). Treat quotes as good for a few minutes and re-quote before applying for long-running flows.

## Prerequisites

* Authenticated as a company user.
* An exchange rate is configured for the `(fromCurrency, toCurrency)` pair.

## Request

### Headers

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

### Body

| Field          | Type   | Required | Constraints                | Description                                 |
| -------------- | ------ | -------- | -------------------------- | ------------------------------------------- |
| `amount`       | number | Yes      | > `0`                      | Amount to convert, in `fromCurrency` units. |
| `fromCurrency` | string | Yes      | Exactly 3 chars (ISO 4217) | Source currency.                            |
| `toCurrency`   | string | Yes      | Exactly 3 chars (ISO 4217) | Target currency.                            |

```json theme={null}
{
  "amount": 600000,
  "fromCurrency": "XAF",
  "toCurrency": "USD"
}
```

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Conversion quoted successfully",
  "data": {
    "convertedAmount": 1000,
    "rate": 0.001667,
    "exchangeRateId": "er_5b7c9d2e4f6a8b1c3d5e7f9a",
    "fromCurrency": "XAF",
    "toCurrency": "USD"
  }
}
```

| Field             | Type   | Description                                                                                                                                    |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `convertedAmount` | number | The result: `amount × rate`, in `toCurrency` units.                                                                                            |
| `rate`            | number | Multiplier: `convertedAmount = amount × rate`. So `1 fromCurrency = rate × toCurrency`.                                                        |
| `exchangeRateId`  | string | Identifier of the rate version used. Pass to [`POST /wallets/deposit`](/api-reference/endpoint/post-wallets-deposit) to apply this exact rate. |
| `fromCurrency`    | string | Echoes the request.                                                                                                                            |
| `toCurrency`      | string | Echoes the request.                                                                                                                            |

### Worked example

For `amount = 600000 XAF`, `fromCurrency = "XAF"`, `toCurrency = "USD"`, with `rate = 0.001667`:

```
convertedAmount = 600000 × 0.001667 = 1000.20 USD
```

### Error responses

| Status | `message` example                             | Trigger                                                                       |
| ------ | --------------------------------------------- | ----------------------------------------------------------------------------- |
| `400`  | `"No exchange rate configured for XAF → USD"` | Your company has no configured rate for the requested pair.                   |
| `400`  | `"fromCurrency must be exactly 3 characters"` | Field validation failed.                                                      |
| `400`  | `"User does not belong to any company"`       | Token has no associated company (rare; should not happen for partner tokens). |

## Code examples

```bash cURL theme={null}
curl -X POST https://api.cartevo.co/api/v1/company/exchange-rates/convert \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 600000,
    "fromCurrency": "XAF",
    "toCurrency": "USD"
  }'
```

```js Node.js (axios) theme={null}
const { data } = await axios.post(
  "https://api.cartevo.co/api/v1/company/exchange-rates/convert",
  { amount: 600000, fromCurrency: "XAF", toCurrency: "USD" },
  { headers: { Authorization: `Bearer ${token}` } }
);
console.log(`${data.data.convertedAmount} USD at rate ${data.data.rate}`);
```

## Related

* [`POST /wallets/deposit`](/api-reference/endpoint/post-wallets-deposit) — apply a quote and actually move funds.
* [Glossary → Wallet](/getting-started/glossary#wallet)


## OpenAPI

````yaml POST /company/exchange-rates/convert
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /company/exchange-rates/convert:
    post:
      summary: Amount conversion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fromCurrency:
                  type: string
                  example: XAF
                toCurrency:
                  type: string
                  example: USD
                amount:
                  type: number
                  example: 1000
              required:
                - fromCurrency
                - toCurrency
                - amount
      responses:
        '200':
          description: Conversion result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      convertedAmount:
                        type: number
                        description: The amount converted into the target currency.
                        example: 1.63
                      rate:
                        type: number
                        description: Exchange rate applied (toCurrency per 1 fromCurrency).
                        example: 0.00163
                      exchangeRateId:
                        type: string
                        description: >-
                          ID of the exchange-rate record used (omitted when
                          fromCurrency === toCurrency).
                        format: uuid
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````