> ## 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.
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.
```bash cURL — payout quote (USD → USD via PayPal, method 21) theme={null}
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quote-001' \
-d '{
"from_currency": "USD",
"to_currency": "CLP",
"amount": 500
}'
```
```javascript Node.js — payout quote theme={null}
const response = await fetch('https://api.yativo.com/api/v1/exchange-rate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'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 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** |
| `rate` | Exchange rate applied (source → target currency) |
| `payout_data.customer_total_amount_due` | Total deducted from your wallet (amount + fees) |
| `payout_data.customer_receive_amount` | Amount the recipient receives |
| `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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: payout-001' \
-d '{
"debit_wallet": "USD",
"quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
"amount": 406,
"payment_method_id": 21
}'
```
**For deposits (payin):**
```bash theme={null}
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-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.