1.11.6. Taler Conversion Info API¶
This chapter describes the conversion info API. The conversion info API is used by wallets for withdrawals that involve a currency conversion.
- GET /config¶
Get configuration information about the bank.
Response:
- 200 OK:
Response is a ConversionConfig.
- 501 Not implemented:
This server does not support conversion, client should check config response.
Details:
interface ConversionConfig { // libtool-style representation of the Bank protocol version, see // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning // The format is "current:revision:age". version: string; // Name of the API. name: "taler-conversion-info"; // URN of the implementation (needed to interpret 'revision' in version). // @since v4, may become mandatory in the future. implementation?: string; // Currency used by this bank. regional_currency: string; // How the bank SPA should render this currency. regional_currency_specification: CurrencySpecification; // External currency used during conversion. fiat_currency: string; // How the bank SPA should render this currency. fiat_currency_specification: CurrencySpecification; // Additional information on conversion rates. // Those informations should never be used to perform conversions, // use /cashin-rate or /cashout-rate instead. // Conversion rates can change at any time. Clients must deal with // any resulting errors and call /cashin-rate or /cashout-rate again // to use the new rates. conversion_rate: ConversionRate; }
- GET /cashin-rate¶
This public endpoint allows clients to calculate the exchange rate between the regional currency and the fiat currency of the banking system.
This endpoint shows how the bank would apply the cash-in ratio and fee to one input amount. Typically, wallets would request this endpoint before creating withdrawals that involve a currency conversion.
Request:
- Query Parameters:
amount_debit – this is the amount that the user will get deducted from their fiat bank account.
or
- Query Parameters:
amount_credit – this is the amount that the user will receive in their regional bank account.
Response:
- 200 OK:
Response is a CashinConversionResponse.
- 400 Bad request:
TALER_EC_GENERIC_PARAMETER_MISSING: none of the parameters have been provided.TALER_EC_GENERIC_PARAMETER_MALFORMED: both of the parameters have been provided or one of them is not a valid Taler amount.TALER_EC_GENERIC_CURRENCY_MISMATCH: the parameter is in the wrong currency.
- 409 Conflict:
The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
- 501 Not implemented:
This server does not support conversion, client should check config response.
Details:
- GET /cashout-rate¶
This public endpoint allows clients to calculate the exchange rate between the regional currency and the fiat currency of the banking system.
This endpoint shows how the bank would apply the cash-out ratio and fee to one input amount. Typically, frontends ask this endpoint before creating cash-in operations.
Request:
- Query Parameters:
amount_debit – this is the amount that the user will get deducted from their regional bank account.
or
- Query Parameters:
amount_credit – this is the amount that the user will receive in their fiat bank account.
Response:
- 200 OK:
Response is a CashoutConversionResponse.
- 400 Bad request:
TALER_EC_GENERIC_PARAMETER_MISSING: none of the parameters have been provided.TALER_EC_GENERIC_PARAMETER_MALFORMED: both of the parameters have been provided or one of them is not a valid Taler amount.TALER_EC_GENERIC_CURRENCY_MISMATCH: the parameter is in the wrong currency.
- 409 Conflict:
The amount is too small to be converted, either because it produces produce an amount less than zero, or because the server requires a higher minimum amount than that supplied.
- 501 Not implemented:
This server does not support conversion, client should check config response.
Details:
interface CashoutConversionResponse { // Amount that the user will get deducted from their regional // bank account, according to the 'amount_credit' value. amount_debit: Amount; // Amount that the user will receive in their fiat // bank account, according to 'amount_debit'. amount_credit: Amount; }
- POST /conversion-rate¶
This endpoint allows the administrator to update the exchange rate between the regional currency and the fiat currency of the banking system.
Request:
interface ConversionRate { // Exchange rate to buy regional currency from fiat cashin_ratio: DecimalNumber; // Regional amount fee to subtract after applying the cashin ratio. cashin_fee: Amount; // Minimum fiat amount authorised for cashin before conversion cashin_min_amount: Amount; // Smallest possible regional amount, converted amount is rounded to this amount cashin_tiny_amount: Amount; // Rounding mode used during cashin conversion cashin_rounding_mode: "zero" | "up" | "nearest"; // Exchange rate to sell regional currency for fiat cashout_ratio: DecimalNumber; // Fiat amount fee to subtract after applying the cashout ratio. cashout_fee: Amount; // Minimum regional amount authorised for cashout before conversion cashout_min_amount: Amount; // Smallest possible fiat amount, converted amount is rounded to this amount cashout_tiny_amount: Amount; // Rounding mode used during cashout conversion cashout_rounding_mode: "zero" | "up" | "nearest"; }
Response:
- 204 No content:
Operation successful.
- 401 Unauthorized:
Invalid credentials or missing rights.
- 501 Not implemented:
This server does not support conversion, client should check config response.