taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

list-withdrawal-exchange-candidates.rst (1965B)

      1 .. ts:op:: listWithdrawalExchangeCandidates
      2   :read-only:
      3 
      4   List exchanges suitable for presentation in a withdrawal chooser.
      5 
      6   **Request:**
      7 
      8   The request arguments must be a
      9   `ListWithdrawalExchangeCandidatesRequest` object.  Omitted fields
     10   use their documented defaults.
     11 
     12   **Response:**
     13 
     14   On success, the result is a `ListWithdrawalExchangeCandidatesResponse`
     15   object.
     16 
     17   **Expected errors:**
     18 
     19   The caller can handle the following errors inline:
     20   ``WALLET_CORE_API_BAD_REQUEST``.
     21 
     22   **Details:**
     23 
     24   Candidates are taken from the wallet's exchange entries and from
     25   the builtin exchange list; ephemeral entries and entries with
     26   unknown currency are excluded.  Demo and test exchanges are only
     27   included when ``withDemo`` or ``withTest`` are set.  Combining
     28   ``presetOnly`` with ``withBuiltin: false`` is rejected with
     29   ``WALLET_CORE_API_BAD_REQUEST``.  Exchanges recently used for a
     30   withdrawal are sorted first, and ``recommendationReasons`` states
     31   why each candidate is suggested.
     32 
     33 .. ts:def:: ListWithdrawalExchangeCandidatesRequest
     34 
     35   type ListWithdrawalExchangeCandidatesRequest =
     36     GetDefaultExchangesRequest;
     37 
     38 .. ts:def:: ListWithdrawalExchangeCandidatesResponse
     39 
     40   interface ListWithdrawalExchangeCandidatesResponse {
     41     candidates: WithdrawalExchangeCandidate[];
     42   }
     43 
     44 .. ts:def:: WithdrawalExchangeCandidate
     45 
     46   interface WithdrawalExchangeCandidate {
     47     // A taler://withdraw-exchange URI for the exchange.
     48     talerUri: string;
     49 
     50     exchangeBaseUrl: string;
     51 
     52     currency: string;
     53 
     54     currencySpec: CurrencySpecification;
     55 
     56     exchangeEntryStatus: ExchangeEntryStatus;
     57 
     58     exchangeUpdateStatus: ExchangeUpdateStatus;
     59 
     60     source: ExchangeEntrySource;
     61 
     62     recommendationReasons: ExchangeRecommendationReason[];
     63 
     64     lastWithdrawal?: TalerPreciseTimestamp;
     65   }
     66 
     67 .. ts:def:: ExchangeRecommendationReason
     68 
     69   type ExchangeRecommendationReason =
     70     | "preset"
     71     | "user-added"
     72     | "previous-withdrawal"
     73     | "previously-used";