> ## 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.
# Get Exchange Rate / Quote
> Generate a quote with locked rate and fee breakdown for a payout or deposit
Returns a real-time exchange rate, fee breakdown, and a `quote_id` valid for **5 minutes**. Pass the `quote_id` to `POST /wallet/payout` or `POST /wallet/deposits/new` to execute the transaction at the quoted rate.
```
POST https://api.yativo.com/api/v1/exchange-rate
```
Requires an `Idempotency-Key` header. Rate-limited to **30 requests per minute**. This endpoint both prices the transaction AND generates a binding `quote_id` — treat it as quote creation, not just a rate lookup.
## Request body
Source currency code (ISO 4217), e.g. `"USD"`, `"EUR"`.
Target currency code (ISO 4217), e.g. `"USD"`, `"CLP"`, `"BRL"`, `"MXN"`.
Amount in the source currency to convert. With `amount_type: "receive"`, the amount the customer receives in `to_currency`.
The payment method ID (from `GET /payment-methods/payout` or `GET /payment-methods/payin`). When provided, the quote is scoped to that specific payment rail and its exact fee structure is applied.
Transaction direction: `"payout"` (for sends/withdrawals) or `"payin"` (for deposits). Required when `method_id` is provided.
Payout quotes only. `send` (default): `amount` is what leaves your wallet. `receive`: `amount` is what the customer receives, and the quote works out the send amount and fees. Using `receive` with `method_type: "payin"` returns `422`. See [Pay out by receive amount](/yativo-fiat/exchange-rates#pay-out-by-receive-amount).
```bash cURL — 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' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "USD",
"method_id": 21,
"method_type": "payout",
"amount": 406
}'
```
```bash cURL — simple FX quote (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' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "CLP",
"amount": 500
}'
```
```bash cURL — payout quote by receive amount (customer gets exactly 5,000 MXN) 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-002' \
-d '{
"from_currency": "USD",
"to_currency": "MXN",
"method_id": 12,
"method_type": "payout",
"amount": 5000,
"amount_type": "receive"
}'
```
```javascript Node.js — payout quote theme={null}
const response = 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',
'Idempotency-Key': `quote-${Date.now()}`,
},
body: JSON.stringify({
from_currency: 'USD',
to_currency: 'USD',
method_id: 21,
method_type: 'payout',
amount: 406,
}),
});
const { data } = await response.json();
// data.quote_id is valid for 5 minutes — use it in /wallet/payout
```
```json With method_id (full calculator) 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",
"converted_amount": "1USD - 1.00000000 USD",
"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
},
"total_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"amount_due": 417.15,
"exchange_rate": 1,
"adjusted_rate": 1,
"target_currency": "USD",
"base_currencies": ["USD"],
"debit_amount": {
"wallet_currency": 417.15,
"payout_currency": 417.15
},
"customer_receive_amount": {
"wallet_currency": 406,
"payout_currency": 406
},
"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",
"exchange_rate_float": "0"
}
}
}
}
```
```json Receive amount (amount_type receive) 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",
"converted_amount": "1USD - 18.12340000 MXN",
"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" }
}
}
```
```json Without method_id (FX only) theme={null}
{
"status": "success",
"status_code": 200,
"message": "Request successful",
"data": {
"quote_id": "7b91acf8-9d2a-4e38-aa71-9babe9f785cd",
"from_currency": "USD",
"to_currency": "CLP",
"rate": "950.00000000",
"amount": "500.00000000",
"payout_data": {
"total_transaction_fee_in_from_currency": "11.15000000",
"total_transaction_fee_in_to_currency": "10592.50",
"customer_sent_amount": "500.00",
"customer_receive_amount": "462925.00",
"customer_total_amount_due": "511.15"
},
"calculator": {
"fee_breakdown": {
"float": { "wallet_currency": 10.15, "payout_currency": 9642.50 },
"fixed": { "wallet_currency": 1, "payout_currency": 950 },
"total": 11.15
},
"exchange_rate": 950,
"customer_receive_amount": { "wallet_currency": 500, "payout_currency": 475000 }
}
}
}
```
## Response fields
| Field | Description |
| - | - |
| `quote_id` | Binding quote identifier — valid for **5 minutes** |
| `quote_expire_at` | When the quote expires. Use it before this time. |
| `rate` | Exchange rate applied (source → target currency) |
| `amount` | The send amount, in `from_currency`. In `receive` mode this is calculated for you. |
| `amount_type` | Payout quotes: `send` or `receive`. |
| `receive_amount` | Only in `receive` mode: the amount the customer receives, in `to_currency`. |
| `payout_data.customer_total_amount_due` | Total deducted from your wallet (amount + fees) |
| `payout_data.customer_receive_amount` | In `receive` mode, the amount the customer receives. In `send` mode, read `calculator.customer_receive_amount.payout_currency` for the amount the customer receives. |
| `calculator.customer_receive_amount.payout_currency` | The amount the customer receives, in `to_currency` |
| `payout_data.total_transaction_fee_in_from_currency` | Total fees in the source currency |
| `calculator.fee_breakdown.float` | Percentage-based fee component |
| `calculator.fee_breakdown.fixed` | Flat fee component |
| `calculator.amount_due` | Final wallet debit amount |
| `calculator.PayoutMethod` | Payment method details (only when `method_id` provided) |
## Using the quote\_id
Once you have a `quote_id`, use it in the execution step within 5 minutes:
**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"
}'
```
Quotes expire after **5 minutes** and cannot be reused. Generating a quote and letting it expire before executing wastes a rate lock and a request toward your rate limit.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.