Rates & Conversion

Fetch cached exchange rates, convert an amount between currencies, and discover which currencies are supported. All three endpoints require the standard white-label headers — Authorization: Bearer <JWT>, X-App-Id (or X-App-Slug), and X-Environment. The EndpointCard below attaches these for you from KeyVault.

Get Exchange Rates

GET /v1/fx/rates

Retrieve the latest cached FX rates. The response is a flat object mapping currency codes to their rate against the configured base currency.

This endpoint takes no request body or query parameters.

Response

{
  "success": true,
  "data": {
    "EUR": "0.92",
    "GBP": "0.79",
    "JPY": "149.50"
  }
}

curl -X GET 'https://cloud.vanitypass.com/v1/fx/rates' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \

Convert Currency

POST /v1/fx/convert

Convert a positive amount from one currency to another using the customer-facing retail rate. Amounts are passed and returned as strings to preserve precision. Wholesale/provider rates are internal and cannot be selected by request data.

Response

{
  "success": true,
  "data": {
    "original_amount": "100",
    "original_currency": "USD",
    "converted_amount": "92.00",
    "converted_currency": "EUR",
    "rate_applied": "0.92",
    "formatted_amount": "€92.00"
  }
}

curl -X POST 'https://cloud.vanitypass.com/v1/fx/convert' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \
  -d '{"amount":"100","from":"USD","to":"EUR"}'

Unknown fields are rejected. rate_applied is the effective customer rate after retail markup and rounding. Conversion is limited to 60 requests per minute per user and application, with Retry-After on 429 responses.

Supported Currencies

GET /v1/fx/supported

List the currencies available for conversion. The response is a flat object mapping each supported currency code to its display name.

This endpoint takes no request body or query parameters.

Response

{
  "success": true,
  "data": {
    "USD": "United States Dollar",
    "EUR": "Euro",
    "GBP": "British Pound Sterling",
    "JPY": "Japanese Yen"
  }
}

curl -X GET 'https://cloud.vanitypass.com/v1/fx/supported' \
  -H 'Content-Type: application/json' \
  -H 'X-Environment: Sandbox' \