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

# Calculate exchange

> Get a real-time exchange rate quote including Qash spread and fees.

<Note>
  Requires `Authorization: Bearer <user-access-token>` — the token from [Verify login code](/api-reference/users/verify-otp). See [Authentication](/api-reference/financials/introduction#authentication) for details.
</Note>

Calculates how much the user would receive when converting one currency to another, applying the Qash spread and fees to the market rate. This endpoint is **read-only** — it does not execute any transaction or reserve funds.

The returned quote is valid until `expiresAt` (typically 30–60 seconds). Pass the quoted rate to your UI before asking the user to confirm the exchange.

## Request

```http theme={null}
POST /api/v1/user/exchange/calculate
Authorization: Bearer <user-access-token>
```

### Body

| Field        | Type   | Required | Description                                                                                   |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `fromAsset`  | string | Yes      | Source currency: `"USD"`, `"COP"`, or `"USDC"`                                                |
| `toAsset`    | string | Yes      | Target currency: `"USD"`, `"COP"`, or `"USDC"`                                                |
| `fromAmount` | number | Yes      | Amount to convert, as a decimal value in `fromAsset`'s major unit — e.g. `100` for USD 100.00 |

```json theme={null}
{
  "fromAsset": "USD",
  "toAsset": "COP",
  "fromAmount": 100
}
```

## Response

**200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "fromAsset": "USD",
    "toAsset": "COP",
    "fromAmount": 100,
    "toAmount": 415823,
    "rate": 4158.23,
    "expiresAt": "2026-06-05T14:05:00.000Z",
    "signature": "eyJhbGciOiJIUzI1NiJ9.eyJmcm9tQXNzZXQiOiJVU0QiLCJ0b0Fzc2V0IjoiQ09QIn0.abc123",
    "signatureVersion": "v1"
  }
}
```

### `data`

| Field              | Type   | Description                                                                                  |
| ------------------ | ------ | -------------------------------------------------------------------------------------------- |
| `fromAsset`        | string | Source currency                                                                              |
| `toAsset`          | string | Target currency                                                                              |
| `fromAmount`       | number | Input amount, decimal value in `fromAsset`'s major unit                                      |
| `toAmount`         | number | Output amount, decimal value in `toAsset`'s major unit, after applying the quoted rate       |
| `rate`             | number | Exchange rate including the Qash spread                                                      |
| `expiresAt`        | string | ISO 8601 timestamp — quote is invalid after this time                                        |
| `signature`        | string | Cryptographic signature of the quote — pass this to the execute endpoint to lock in the rate |
| `signatureVersion` | string | Signature algorithm version — currently `"v1"`                                               |

<Warning>
  Both `fromAmount` and `toAmount` are decimal values in their respective asset's major unit — `toAmount: 415823` above means COP 415,823.00, not COP 4,158.23. Never use floating point arithmetic to compute these values before sending them.
</Warning>

<Info>
  Store the `signature` and `expiresAt` values — they are required to execute the exchange. A quote cannot be executed after `expiresAt`.
</Info>