Get Exchange Rate / Quote

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
  }'

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
  }'

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"
  }'

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

{
  "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"
      }
    }
  }
}

{
  "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" }
  }
}

{
  "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 }
    }
  }
}

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
  }'

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
  }'

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"
  }'

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

{
  "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"
      }
    }
  }
}

{
  "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" }
  }
}

{
  "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 }
    }
  }
}

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

string

required

Source currency code (ISO 4217), e.g. "USD", "EUR".

string

required

Target currency code (ISO 4217), e.g. "USD", "CLP", "BRL", "MXN".

number

required

Amount in the source currency to convert. With amount_type: "receive", the amount the customer receives in to_currency.

integer

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.

string

Transaction direction: "payout" (for sends/withdrawals) or "payin" (for deposits). Required when method_id is provided.

string

default:"send"

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.

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
  }'

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
  }'

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"
  }'

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

{
  "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"
      }
    }
  }
}

{
  "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" }
  }
}

{
  "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:

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):

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.

Overview

Authentication

Customers

KYC / KYB

Payments & Transfers

Deposits

Virtual Accounts

Wallets

Beneficiaries

Transactions

Virtual Cards

Payouts

Currency Swap

Gift Cards

IP Whitelist & Security

Webhooks

Developer

Get Exchange Rate / Quote

Request body

Response fields

Using the quote_id

​Request body

​Response fields

​Using the quote_id

Request body

Response fields

Using the quote_id