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

# Exchange Rates & Quotes

> Generate locked quotes for payouts and deposits, or fetch live rates for display

Yativo has two rate endpoints:

| Endpoint | Use it to |
| - | - |
| [`GET /exchange-rates`](#live-market-rates) | Show live market rates for every wallet currency. No fees, no quote. |
| [`POST /exchange-rate`](#generate-a-quote) | Price a specific payout or deposit with fees, and lock it with a `quote_id`. |

`POST /exchange-rate` is the single source for pricing any transaction on Yativo. It returns a `quote_id` valid for 5 minutes — use this ID in the execution step to guarantee the rate and fee shown to your customer.

There are two modes:

| Mode | When to use |
| - | - |
| **With `method_id` + `method_type`** | Quote a specific payment method — returns exact fees for that rail |
| **Without `method_id`** | Generic FX rate for display only |

<Accordion title="Type Definitions">
  ```typescript theme={null}
  interface ExchangeRateRequest {
    from_currency: string;    // source currency (ISO 4217)
    to_currency: string;      // target currency (ISO 4217)
    amount: number;           // amount in source currency
    method_id?: number;       // payment method ID (from /payment-methods/payout or /payin)
    method_type?: "payout" | "payin";  // required when method_id is provided
    amount_type?: "send" | "receive";  // payout quotes only; default "send"
  }

  interface Quote {
    quote_id: string;         // valid for 5 minutes — use in /wallet/payout or /wallet/deposits/new
    quote_expire_at: string;  // ISO 8601
    from_currency: string;
    to_currency: string;
    rate: string;
    amount: string;           // send amount, in from_currency
    amount_type?: "send" | "receive";
    receive_amount?: string;  // receive mode only, in to_currency
    payout_data: {
      total_transaction_fee_in_from_currency: string;
      total_transaction_fee_in_to_currency: string;
      customer_sent_amount: string;
      customer_receive_amount: string;
      customer_total_amount_due: string;  // total deducted from wallet
    };
    calculator: {
      amount_due: number;
      exchange_rate: number;
      fee_breakdown: {
        float: { wallet_currency: number; payout_currency: number };
        fixed: { wallet_currency: number; payout_currency: number };
        total: number;
      };
      PayoutMethod?: {        // present when method_id was provided
        id: number;
        method_name: string;
        country: string;
        currency: string;
        base_currency: string;
      };
    };
  }
  ```
</Accordion>

***

## Generate a Quote

```
POST /exchange-rate
```

<ParamField body="from_currency" type="string" required>
  Source currency (ISO 4217), e.g. `"USD"`, `"EUR"`.
</ParamField>

<ParamField body="to_currency" type="string" required>
  Target currency (ISO 4217), e.g. `"USD"`, `"CLP"`, `"BRL"`, `"MXN"`.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount in the source currency.
</ParamField>

<ParamField body="method_id" type="integer">
  Payment method ID from `GET /payment-methods/payout` or `GET /payment-methods/payin`. Scopes the quote to the exact fees for that rail — required for checkout flows where you will execute at the quoted price.
</ParamField>

<ParamField body="method_type" type="string">
  `"payout"` for sends/withdrawals or `"payin"` for deposits. Required when `method_id` is provided.
</ParamField>

<ParamField body="amount_type" type="string" default="send">
  Payout quotes only. Set to `"receive"` to make `amount` the amount the customer receives, in `to_currency`. See [Pay out by receive amount](#pay-out-by-receive-amount).
</ParamField>

<RequestExample>
  ```bash Payout quote (USD → USD via PayPal, method 21) theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
    -H 'X-Api-Key: YOUR_API_KEY' \
    -H 'X-Api-Secret: YOUR_API_SECRET' \
    -H 'Content-Type: application/json' \
    -d '{
      "from_currency": "USD",
      "to_currency": "USD",
      "method_id": 21,
      "method_type": "payout",
      "amount": 406
    }'
  ```

  ```bash FX display only (no method) theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
    -H 'X-Api-Key: YOUR_API_KEY' \
    -H 'X-Api-Secret: YOUR_API_SECRET' \
    -H 'Content-Type: application/json' \
    -d '{
      "from_currency": "USD",
      "to_currency": "MXN",
      "amount": 200
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
    method: 'POST',
    headers: { 'X-Api-Key': process.env.YATIVO_API_KEY, 'X-Api-Secret': process.env.YATIVO_API_SECRET, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      from_currency: 'USD',
      to_currency: 'USD',
      method_id: 21,
      method_type: 'payout',
      amount: 406,
    }),
  });
  const { data } = await res.json();
  // Show data.payout_data to customer, then use data.quote_id in /wallet/payout
  ```
</RequestExample>

<ResponseExample>
  ```json With method_id theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
      "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
      "from_currency": "USD",
      "to_currency": "USD",
      "rate": "1.00000000",
      "amount": "406.00000000",
      "payout_data": {
        "total_transaction_fee_in_from_currency": "11.15000000",
        "total_transaction_fee_in_to_currency": "11.15",
        "customer_sent_amount": "406.00",
        "customer_receive_amount": "406.00",
        "customer_total_amount_due": "417.15"
      },
      "calculator": {
        "total_fee": { "wallet_currency": 11.15, "payout_currency": 11.15, "usd": 11.15 },
        "amount_due": 417.15,
        "exchange_rate": 1,
        "fee_breakdown": {
          "float": { "wallet_currency": 10.15, "payout_currency": 10.15 },
          "fixed": { "wallet_currency": 1, "payout_currency": 1 },
          "total": 11.15
        },
        "PayoutMethod": {
          "id": 21,
          "method_name": "PayPal",
          "country": "PER",
          "currency": "USD",
          "base_currency": "USD"
        }
      }
    }
  }
  ```
</ResponseExample>

<Warning>
  Quotes expire after **5 minutes**. Execute the transaction within this window — after expiry the `quote_id` is rejected and a new quote is required.
</Warning>

***

## Execute the Quote

Use the `quote_id` in the appropriate execution endpoint:

### For payouts

```bash theme={null}
curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-001' \
  -d '{
    "debit_wallet": "USD",
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
    "payment_method_id": 555,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"
  }'
```

### For deposits (payin)

```bash theme={null}
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deposit-001' \
  -d '{
    "gateway": 20,
    "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
    "currency": "USD",
    "redirect_url": "https://your-app.com/deposit/complete"
  }'
```

***

## Pay out by receive amount

By default, a payout's `amount` is what you **send** from your wallet, and the customer receives that amount converted into the payout currency. To fix what the customer **receives** instead, for example exactly 5,000 MXN, set `amount_type` to `receive`. Yativo works out the send amount and fees, then debits your wallet for both. The customer always gets the full requested amount.

| `amount_type` | `amount` means | Currency of `amount` |
| - | - | - |
| `send` (default) | What leaves your wallet, before fees | Your debit wallet (`from_currency` / `debit_wallet`) |
| `receive` | What the customer receives | The payout currency (`to_currency`) |

`amount_type` works on `POST /exchange-rate` (payout quotes) and `POST /wallet/payout`.

### Option A: quote first (recommended)

A quote fixes the rate and fees for 5 minutes, so you can show the exact debit before you commit.

<Steps>
  <Step title="Get a receive-mode quote">
    ```bash theme={null}
    curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
      -H 'X-Api-Key: YOUR_API_KEY' \
      -H 'X-Api-Secret: YOUR_API_SECRET' \
      -H 'Content-Type: application/json' \
      -H 'Idempotency-Key: quote-receive-001' \
      -d '{
        "method_type": "payout",
        "method_id": 12,
        "from_currency": "USD",
        "to_currency": "MXN",
        "amount": 5000,
        "amount_type": "receive"
      }'
    ```

    ```json theme={null}
    {
      "status": "success",
      "status_code": 200,
      "message": "Request successful",
      "data": {
        "quote_id": "9c1e5b2a-3f4d-4e6a-8b7c-2d1e0f9a8b7c",
        "quote_expire_at": "2026-10-01T12:05:00.000000Z",
        "from_currency": "USD",
        "to_currency": "MXN",
        "rate": "18.12340000",
        "amount": "275.88642300",
        "amount_type": "receive",
        "receive_amount": "5000.00000000",
        "payout_data": {
          "customer_sent_amount": "275.89",
          "customer_receive_amount": "5,000.00",
          "customer_total_amount_due": "278.39"
        },
        "calculator": { "...": "full fee and rate breakdown" }
      }
    }
    ```

    `amount` is the send amount in `from_currency`, `receive_amount` is what the customer gets, and `payout_data.customer_total_amount_due` is the total your wallet is debited.
  </Step>

  <Step title="Create the payout with the quote">
    ```bash theme={null}
    curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
      -H 'X-Api-Key: YOUR_API_KEY' \
      -H 'X-Api-Secret: YOUR_API_SECRET' \
      -H 'Content-Type: application/json' \
      -H 'Idempotency-Key: payout-receive-001' \
      -d '{
        "quote_id": "9c1e5b2a-3f4d-4e6a-8b7c-2d1e0f9a8b7c",
        "payment_method_id": 555,
        "debit_wallet": "USD",
        "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"
      }'
    ```

    The quote supplies the amount, so don't send `amount` or `amount_type`. Any `amount_type` you send with a `quote_id` is ignored. The quote's `method_id` must be the payout method behind `payment_method_id`.
  </Step>
</Steps>

### Option B: pay out directly

```bash theme={null}
curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-receive-002' \
  -d '{
    "amount": 5000,
    "amount_type": "receive",
    "payment_method_id": 555,
    "debit_wallet": "USD",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2"
  }'
```

The send amount is calculated at the current rate when the request is processed. Use Option A if you need to know the debit in advance.

### Payout response

Every `POST /wallet/payout` response includes these fields, in either mode:

| Field | Meaning |
| - | - |
| `amount_type` | `send` or `receive`, as applied. |
| `send_amount` | The amount sent, in the debit wallet currency, before fees. |
| `customer_receive_amount` | The amount the customer receives, in `currency`. |
| `debit_amount` | The total debited from your wallet, fees included. |

When the debit wallet and payout currency are the same (for example USD to USD), the send amount equals the receive amount. Fees are still added on top.

### Limits and errors

* The payout method's minimum and maximum are checked against the calculated **send** amount, so a receive amount can be rejected for being above or below a limit. The error shows the limit in your wallet currency.
* If your wallet can't cover the send amount plus fees, the request fails with `Insufficient wallet balance` and nothing is debited.
* An `amount_type` other than `send` or `receive` returns `422`.
* `amount_type: "receive"` on a payin quote returns `422`.

***

## Live market rates

To show live rates to your customers, without fees or a quote, use:

```
GET /exchange-rates?base=USD
```

<ParamField query="base" type="string" default="USD">
  The currency rates are quoted against. Must be a supported wallet currency.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl 'https://api.yativo.com/api/v1/exchange-rates?base=USD' \
    -H 'X-Api-Key: YOUR_API_KEY' \
    -H 'X-Api-Secret: YOUR_API_SECRET'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
      "base": "USD",
      "rates": {
        "ARS": 1185.5,
        "BRL": 5.4321,
        "EUR": 0.9187,
        "MXN": 18.6024,
        "USD": 1
      },
      "updated_at": "2026-10-01T12:00:00+00:00"
    }
  }
  ```
</ResponseExample>

Each rate means **1 `base` = `rate` units of that currency**. To convert from the base currency, multiply by the rate. To convert back, divide. A rate of `null` means no rate is available for that currency right now.

* Rates are indicative market rates. They refresh about once a minute and **don't include fees**.
* You can call this endpoint **once per minute** per account. Further calls in the same minute get `429` with a `Retry-After` header. To show several bases, make one request and divide: the rate from `A` to `B` is `rates[B] / rates[A]`.
* Team members need the **Currency Exchange → view** permission.
* An unsupported `base` returns `422` with the allowed values. `503` means rates are temporarily unavailable.

See [Get Market Rates](/fiat-api-reference/payments/market-rates) for the full reference.

***

## Get a Locked Quote for Send Money

For sending money specifically (rather than wallet payouts), use the dedicated send money quote endpoint which also returns a `quote_id`:

```
POST /sendmoney/quote
```

<RequestExample>
  ```bash USD → MXN theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/sendmoney/quote' \
    -H 'X-Api-Key: YOUR_API_KEY' \
    -H 'X-Api-Secret: YOUR_API_SECRET' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: quote-001' \
    -d '{
      "from_currency": "USD",
      "to_currency": "MXN",
      "amount": 200,
      "beneficiary_payment_method_id": "pm-3a4b5c6d-7e8f-9a0b"
    }'
  ```
</RequestExample>

***

## Complete Quote Workflow

```
1. GET /payment-methods/payout?country=...    → get method_id (e.g. 21)
2. POST /exchange-rate                         → quote with method_id + method_type
                                               → shows exact fees to customer
                                               → returns quote_id (5-min window)
3. POST /wallet/payout (or /deposits/new)      → execute with quote_id
4. GET /transaction/tracking/{id}              → monitor status
```

***

## Fee Breakdown

The `calculator.fee_breakdown` object contains two fee components:

| Component | Description |
| - | - |
| `float` | Percentage-based fee — scales with amount |
| `fixed` | Flat fee — charged regardless of amount |
| `total` | Sum of float + fixed in both wallet and payout currencies |

Always display `payout_data.customer_total_amount_due` to the customer — this is the exact amount that will be debited from their wallet.

***

## Rate Limits

`POST /exchange-rate` is limited to **30 requests per minute** per API key. Cache quotes client-side for display rather than calling on every user keystroke.

`GET /exchange-rates` is limited to **1 request per minute** per account. Its rates only refresh once a minute.


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