# Fx Quotes

## Get FX Quote

 - [GET /v1/fx-quotes](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/fx-quotes/fxquotes_get.md): Retrieves a foreign exchange quote for converting between currencies (for the requested pair and amount).
The same quote will be automatically applied by the system to any internal transfer or payment involving two different currencies, provided it is used within its expiry time.
            
### High-Value Exchange Requests (> 100 000 BMD)
If the requested exchange amount exceeds 100 000 BMD, the system will not return an automatic quote in the GET /v1/fx-quotes response.  
Instead, the request is routed for manual processing by our treasury desk to secure the most competitive rate available.

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL:
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/fx-quotes

### Validation Rules
- Currencies must be valid three-letter ISO 4217 codes
- Unit currency and currency of transfer must be different
- Instructed amount must be a valid decimal number with up to 2 decimal places

### Sample Request in JavaScript:
javascript
// Get FX quote for converting 100 USD to EUR
const getFxQuote = async (unitCurrency, currencyOfTransfer, instructedAmount) => {
  try {
    const response = await fetch(
      'https://api.bcb.bm/v1/fx-quotes?' + 
      new URLSearchParams({
        unitCurrency: unitCurrency,
        currencyOfTransfer: currencyOfTransfer,
        instructedAmount: instructedAmount
      }), {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
    });

    // Check if the response is ok (status in the range 200-299)
    if (!response.ok) {
      // Parse error response
      const errorData = await response.json();
      throw new Error(Error ${response.status}: ${errorData.error} - ${errorData.message});
    }

    // Parse successful response
    const quote = await response.json();
    
    // Log the complete quote details
    console.log('FX Quote Details:');
    console.log(Source Currency: ${quote.sourceCurrency.currency});
    console.log(Source Amount: ${quote.sourceCurrency.amount});
    console.log(Target Currency: ${quote.targetCurrency.currency});
    console.log(Target Amount: ${quote.targetCurrency.amount});
    console.log(Exchange Rate: ${quote.exchangeRate});
    console.log(Quote Expires: ${new Date(quote.expiryDateTime).toLocaleString()});

    // Return the processed quote
    return {
      ...quote,
      // Add formatted values for display
      formattedSourceAmount: new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: quote.sourceCurrency.currency
      }).format(quote.sourceCurrency.amount),
      formattedTargetAmount: new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: quote.targetCurrency.currency
      }).format(quote.targetCurrency.amount)
    };
  } catch (error) {
    // Handle different types of errors
    if (error.name === 'TypeError') {
      console.error('Network error:', error.message);
    } else {
      console.error('API error:', error.message);
    }
    throw error; // Re-throw to let caller handle it
  }
};
            
// Example usage with error handling:
try {
  const quote = await getFxQuote('USD', 'EUR', '100.00');
  console.log('Formatted Quote:', quote.formattedSourceAmount, '→', quote.formattedTargetAmount);
} catch (error) {
  console.error('Failed to get FX quote:', error.message);
}


Required Permission: get-fx-quote

This endpoint requires the permission claim get-fx-quote to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.