taler-docs

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

get-exchange-entry-by-url.rst (4339B)

      1 .. ts:op:: getExchangeEntryByUrl
      2   :read-only:
      3 
      4   Get the wallet's exchange entry for an exchange base URL.
      5 
      6   **Request:**
      7 
      8   The request arguments must be a `GetExchangeEntryByUrlRequest`
      9   object.
     10 
     11   **Response:**
     12 
     13   On success, the result is a `GetExchangeEntryByUrlResponse` object,
     14   which is an alias for `ExchangeListItem` (see
     15   :ts:op:`listExchanges`).
     16 
     17   **Expected errors:**
     18 
     19   The caller can handle the following errors inline:
     20   ``WALLET_EXCHANGE_ENTRY_NOT_FOUND``.
     21 
     22 .. ts:def:: ExchangeListItem
     23 
     24   // Info about an exchange entry in the wallet.
     25   interface ExchangeListItem {
     26     exchangeBaseUrl: string;
     27 
     28     source?: ExchangeEntrySource;
     29 
     30     masterPub: string | undefined;
     31 
     32     // Master public keys this exchange URL used before its current
     33     // key.  The array is sorted and does not include masterPub.
     34     legacyMasterPubs: string[];
     35 
     36     // Set when the exchange changed its key set and the user has not
     37     // confirmed the change yet.  Operations that send money to the
     38     // exchange or disclose coin authorizations are refused while this
     39     // is present.
     40     unconfirmedKeyChange?: ExchangeKeyChangeInfo;
     41 
     42     currency: string;
     43 
     44     paytoUris: string[];
     45 
     46     tosStatus: ExchangeTosStatus;
     47 
     48     exchangeEntryStatus: ExchangeEntryStatus;
     49 
     50     exchangeUpdateStatus: ExchangeUpdateStatus;
     51 
     52     ageRestrictionOptions: number[];
     53 
     54     walletKycStatus?: ExchangeWalletKycStatus;
     55 
     56     walletKycReservePub?: string;
     57 
     58     walletKycAccessToken?: string;
     59 
     60     walletKycUrl?: string;
     61 
     62     // Threshold that we've requested to satisfy.
     63     walletKycRequestedThreshold?: string;
     64 
     65     // P2P payments are disabled with this exchange
     66     // (e.g. because no global fees are configured).
     67     peerPaymentsDisabled: boolean;
     68 
     69     directDepositsDisabled: boolean;
     70 
     71     // Set to true if this exchange doesn't charge any fees.
     72     noFees: boolean;
     73 
     74     // Most general scope that the exchange is a part of.
     75     scopeInfo: ScopeInfo;
     76 
     77     // Instructs wallets to use certain bank-specific language (for
     78     // buttons) and/or other UI/UX customization for compliance with
     79     // the rules of that bank.
     80     bankComplianceLanguage?: string;
     81 
     82     lastUpdateTimestamp: TalerPreciseTimestamp | undefined;
     83 
     84     // Most recent successful withdrawal through this exchange.
     85     lastWithdrawal?: TalerPreciseTimestamp;
     86 
     87     // Information about the last error that occurred when trying
     88     // to update the exchange info.
     89     lastUpdateErrorInfo?: OperationErrorInfo;
     90 
     91     // Currency spec for the currency offered by the exchange.
     92     currencySpec: CurrencySpecification;
     93   }
     94 
     95 .. ts:def:: ExchangeKeyChangeInfo
     96 
     97   // An exchange that changed its key set, pending the user's
     98   // confirmation.  The wallet has already adopted the new key set, so
     99   // the entry works and the older coins stay spendable; withdrawing is
    100   // withheld until the change is confirmed.
    101   interface ExchangeKeyChangeInfo {
    102     // Master public key the exchange now uses, and the wallet now
    103     // trusts.
    104     currentMasterPub: string;
    105 
    106     currentCurrency: string;
    107 
    108     // Master public key the wallet's older funds were issued under.
    109     supersededMasterPub: string;
    110 
    111     supersededCurrency: string;
    112 
    113     // Whether the new key set still advertises denominations the
    114     // wallet holds coins of.  False means the exchange does not offer
    115     // to settle the older coins at all; true is only the exchange's
    116     // claim, not proof of continuity.
    117     sharesDenominations: boolean;
    118 
    119     firstSeen: TalerPreciseTimestamp;
    120   }
    121 
    122 .. ts:def:: OperationErrorInfo
    123 
    124   interface OperationErrorInfo {
    125     error: TalerErrorDetail;
    126   }
    127 
    128 .. ts:def:: ExchangeTosStatus
    129 
    130   type ExchangeTosStatus =
    131     | "pending"
    132     | "proposed"
    133     | "accepted"
    134     | "missing-tos";
    135 
    136 .. ts:def:: ExchangeEntrySource
    137 
    138   // How an exchange entry became known to the wallet.
    139   type ExchangeEntrySource =
    140     | "builtin"
    141     | "user"
    142     | "discovered"
    143     | "unknown";
    144 
    145 .. ts:def:: ExchangeUpdateStatus
    146 
    147   type ExchangeUpdateStatus =
    148     | "initial"
    149     | "initial-update"
    150     | "suspended"
    151     | "unavailable-update"
    152     | "ready"
    153     | "ready-update"
    154     | "outdated-update";
    155 
    156 .. ts:def:: GetExchangeEntryByUrlRequest
    157 
    158   interface GetExchangeEntryByUrlRequest {
    159     exchangeBaseUrl: string;
    160   }
    161 
    162 .. ts:def:: GetExchangeEntryByUrlResponse
    163 
    164   type GetExchangeEntryByUrlResponse = ExchangeListItem;