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

# Rate

## Overview

The `Rate` endpoint returns the exchange rate for a currency pair with your
platform fee already applied on top. Use it to show your users what a conversion
will cost before they commit to it.

The rate is **indicative** — it does not reserve or lock a quote, and no funds
move. Pass exactly one of `source_amount` or `destination_amount`; Superbank
computes the other side.

Endpoints

* [`GET` /v0/rates](/platform/core-resources/rate#get-/v0/rates)

## Object

### Attributes

| **Attribute**              | **Description**                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `source_currency`          | The currency code being converted from.                                                                |
| `destination_currency`     | The currency code being converted to.                                                                  |
| `mid_market_rate`          | Destination units per one source unit, before any fee.                                                 |
| `inverted_mid_market_rate` | The inverse of `mid_market_rate`, for convenience.                                                     |
| `effective_rate`           | The all-in rate the recipient actually receives per source unit, after the fee.                        |
| `source_amount`            | The amount debited in the source currency.                                                             |
| `destination_amount`       | The amount credited in the destination currency.                                                       |
| `fee`                      | The fee applied on top of the exchange rate.                                                           |
| `fee.total`                | The total fee for this conversion, denominated in the source currency. This is a single all-in figure. |
| `fee.currency`             | The currency the fee is denominated in (the source currency).                                          |

<Info>
  `fee.total` is the complete cost of the conversion. It equals the gap between
  what is debited and what would be received at the mid-market rate
  (`source_amount - destination_amount / mid_market_rate`), so the difference
  between `mid_market_rate` and `effective_rate` is fully explained by it.
</Info>

## `GET /v0/rates`

### Parameters

| **Query parameter**         | **Description**                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `source_currency_code`      | **Required.** The currency to convert from, e.g. `USDC`, `USD`.                                |
| `source_rail`               | **Required.** The source rail, e.g. `SOLANA`, `ACH`.                                           |
| `destination_currency_code` | **Required.** The currency to convert to, e.g. `CAD`, `USDC`.                                  |
| `destination_rail`          | **Required.** The destination rail, e.g. `LOCAL`, `RTP`.                                       |
| `destination_country_code`  | The ISO 3166-1 alpha-2 country code of the destination. Required when the destination is fiat. |
| `source_country_code`       | The ISO 3166-1 alpha-2 country code of the source. Required when the source is fiat (on-ramp). |
| `source_amount`             | The amount in the source currency. Mutually exclusive with `destination_amount`.               |
| `destination_amount`        | The amount in the destination currency. Mutually exclusive with `source_amount`.               |

<Note>
  At least one leg must be a stablecoin — fiat-to-fiat pairs are not supported.
  Stablecoin legs use a crypto rail (`SOLANA`, `ETHEREUM`, `POLYGON`, `TRON`);
  fiat legs use `ACH`, `RTP`, `DOMESTIC_WIRE`, or `LOCAL`.
</Note>

### Request

```bash theme={null}
curl --request GET \
    --url 'https://api-sandbox.superbank.co/v0/rates?source_currency_code=USDC&source_rail=SOLANA&destination_currency_code=CAD&destination_rail=LOCAL&destination_country_code=CA&source_amount=1000' \
    --header 'X-Api-Key: YOUR_API_KEY'
```

### Response

```json theme={null}
{
  "source_currency": "USDC",
  "destination_currency": "CAD",
  "mid_market_rate": 1.3788512205,
  "inverted_mid_market_rate": 0.7252415072,
  "effective_rate": 1.3651,
  "source_amount": 1000,
  "destination_amount": 1365.1,
  "fee": {
    "total": 9.97,
    "currency": "USDC"
  }
}
```

### Errors

| **Status** | **When**                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------- |
| `400`      | Both or neither of `source_amount` / `destination_amount` were provided.                 |
| `400`      | An unsupported currency, a rail that doesn't match the currency, or a fiat-to-fiat pair. |
| `400`      | A fiat leg without its country code.                                                     |
| `401`      | Missing or invalid API key.                                                              |