taler-docs

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

api-exchange.rst (25434B)


      1 ..
      2   This file is part of GNU TALER.
      3   Copyright (C) 2014-2026 Taler Systems SA
      4 
      5   TALER is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero General Public License as published by the Free Software
      7   Foundation; either version 3.0, or (at your option) any later version.
      8 
      9   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 
     16   @author Christian Grothoff
     17   @author Özgür Kesim
     18 
     19 ====================
     20 Exchange RESTful API
     21 ====================
     22 
     23 The API specified here follows the :ref:`general conventions <http-common>`
     24 for all details not specified in the individual requests.
     25 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
     26 defines all specific terms used in this section.
     27 
     28 
     29 ---------------
     30 Version History
     31 ---------------
     32 
     33 The currently implemented protocol version is **v46**.
     34 
     35 * Wallet-core is currently targeting **vXX**.
     36 * The merchant is currently targeting **v34**.
     37 * The AML SPA is currently targeting **v41**.
     38 * The KYC SPA is currently targeting **v30**.
     39 
     40 **Version history:**
     41 
     42 * ``v29``: AML reporting on KYC auth transfers
     43 * ``v30``: various minor feature additions
     44 * ``v31``: improvements for AML reporting
     45 * ``v32``: support for extra_wire_subject_metadata
     46 * ``v33``: addition of accumulated_total_without_fee in :http:post:`/batch-deposit </batch-deposit>`
     47 * ``v34``: new offline signature; support for open_banking_gateway and
     48            prepared_transfer_url per wire account in :http:get:`/keys </keys>`
     49 * ``v35``: adds ``default_p2p_push_expiration`` to :http:get:`/keys </keys>`
     50 * ``v36``: adds ``kyc_swap_tos_acceptance`` to :http:get:`/keys </keys>`
     51 * ``v37``: adds :http:get:`/aml/$OFFICER_PUB/wallet-credit </aml/$OFFICER_PUB/wallet-credit>` endpoint
     52 * ``v38``: adds ``build_version`` to :http:get:`/config </config>`
     53 * ``v39``: adds ``exchange_payto_uri`` to
     54            :http:get:`/transfers/$WTID </transfers/$WTID>`
     55 * ``v40``: adds :http:get:`/aml/$OFFICER_PUB </aml/$OFFICER_PUB>` to report
     56            the authenticated AML officer's name and access level
     57 * ``v41``: adds :http:post:`/aml/$OFFICER_PUB/render-form </aml/$OFFICER_PUB/render-form>`
     58            to preview filled AML/KYC forms as PDF
     59 * ``v42``: batch recoup protocol: adds :http:post:`/recoup-withdraw </recoup-withdraw>`
     60            and :http:post:`/recoup-refresh </recoup-refresh>`, removes
     61            ``/coins/$COIN_PUB/recoup`` and ``/coins/$COIN_PUB/recoup-refresh``;
     62            adds ``planchets_h``, ``rc`` and ``coin_index`` to the recoup entries
     63            of coin and reserve histories;
     64            coin conflict proofs: specifies `CoinDenominationConflictError`
     65            and `CoinAgeCommitmentConflictError` for the 409 responses with
     66            error codes ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``
     67            and ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH``, which
     68            now carry the stored denomination signature (and age commitment
     69            hash) of the coin so that clients can verify the conflict;
     70            adds the required ``reserve_pub`` field to the
     71            :http:post:`/reveal-withdraw </reveal-withdraw>` request body,
     72            so that a withdraw operation is identified by the pair
     73            (reserve, commitment) everywhere;
     74            bounds ``purse_expiration`` by the new ``max_p2p_expiration``
     75            of :http:get:`/keys </keys>` and by the legal expiration of the
     76            denominations of the coins in the purse, with the new error
     77            codes ``TALER_EC_EXCHANGE_PURSE_CREATE_EXPIRATION_TOO_LATE``,
     78            ``TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_TOO_LATE`` and
     79            ``TALER_EC_EXCHANGE_PURSE_DENOMINATION_LEGAL_EXPIRES_TOO_SOON``
     80 * ``v45``: the refresh commitment :ref:`TALER_RefreshCommitmentP <TALER_RefreshCommitmentP>` now includes
     81            the transfer public keys of the :http:post:`/melt </melt>`
     82            request; clients must include them with exchanges of v45 or
     83            later.  The exchange still accepts the commitment without
     84            them from older clients.
     85 * ``v46``: the ``MELT`` entries of the coin history
     86            (:http:get:`/coins/$COIN_PUB/history </coins/$COIN_PUB/history>`)
     87            include ``noreveal_index`` and the ``transfer_pubs`` of the
     88            batch at ``noreveal_index``;
     89            :http:post:`/melt </melt>` of a zombie coin returns the
     90            `CoinDenominationConflictError` proof like all other paths;
     91            :http:post:`/withdraw </withdraw>` and :http:post:`/melt </melt>`
     92            refuse a Clause-Schnorr envelope whose ``cs_nonce`` is not the
     93            nonce derived from the request's ``blinding_seed`` (see
     94            `CSCoinEnvelope`)
     95 
     96 **Upcoming versions:**
     97 
     98 * ``vIMPORT``: external KYC/KYB data import
     99 * ``vATTEST``: KYC attestation support
    100 
    101 **Ideas for future version:**
    102 
    103 * ``vXXX``: marker for features not yet targeted for release
    104 
    105 .. include:: tos.rst
    106 
    107 .. _keys:
    108 
    109 ---------------------------
    110 Exchange status information
    111 ---------------------------
    112 
    113 This API is used by wallets and merchants to obtain global information about
    114 the exchange, such as online signing keys, available denominations and the fee
    115 structure.  This is typically the first call any exchange client makes, as it
    116 returns information required to process all of the other interactions with the
    117 exchange.  The returned information is secured by (1) signature(s) from the exchange,
    118 especially the long-term offline signing key of the exchange, which clients should
    119 cache; (2) signature(s) from auditors, and the auditor keys should be
    120 hard-coded into the wallet as they are the trust anchors for Taler; (3)
    121 possibly by using HTTPS.
    122 
    123 
    124 .. include:: exchange/get-seed.rst
    125 
    126 .. include:: exchange/get-config.rst
    127 
    128 .. include:: exchange/get-keys.rst
    129 
    130 
    131 ----------------------------------------------
    132 Management operations authorized by master key
    133 ----------------------------------------------
    134 
    135 .. include:: exchange/get-management-keys.rst
    136 
    137 .. include:: exchange/post-management-keys.rst
    138 
    139 .. include:: exchange/post-management-denominations-H_DENOM_PUB-revoke.rst
    140 
    141 .. include:: exchange/post-management-signkeys-EXCHANGE_PUB-revoke.rst
    142 
    143 .. include:: exchange/post-management-auditors.rst
    144 
    145 .. include:: exchange/post-management-auditors-AUDITOR_PUB-disable.rst
    146 
    147 .. include:: exchange/post-management-wire-fee.rst
    148 
    149 .. include:: exchange/post-management-global-fees.rst
    150 
    151 .. include:: exchange/post-management-wire.rst
    152 
    153 .. include:: exchange/post-management-wire-disable.rst
    154 
    155 .. include:: exchange/post-management-drain.rst
    156 
    157 .. include:: exchange/post-management-aml-officers.rst
    158 
    159 .. include:: exchange/post-management-partners.rst
    160 
    161 ---------------
    162 Auditor actions
    163 ---------------
    164 
    165 .. _auditor_action:
    166 
    167 This part of the API is for the use by auditors interacting with the exchange.
    168 
    169 .. include:: exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.rst
    170 
    171 
    172 ----------------
    173 Blinding Prepare
    174 ----------------
    175 
    176 Certain denomination cipher types, such as Clause-Schnorr, require input values
    177 from the exchange-side as preparation for the blinding of the coins.  See the
    178 Bachelor thesis of Gian Demarmels and Lucien Heuzeveldt,
    179 `Adding Schnorr’s Blind Signature in Taler <https://www.taler.net/papers/cs-thesis.pdf>`_,
    180 for details.
    181 
    182 .. include:: exchange/post-blinding-prepare.rst
    183 
    184 
    185 .. _exchange-withdrawal:
    186 
    187 ----------
    188 Withdrawal
    189 ----------
    190 
    191 This API is used by the wallet to obtain digital coins.
    192 
    193 When transferring money to the exchange such as via SEPA transfers, the exchange creates
    194 a *reserve*, which keeps the money from the customer.  The customer must
    195 specify an EdDSA reserve public key as part of the transfer, and can then
    196 withdraw digital coins using the corresponding private key.  All incoming and
    197 outgoing transactions are recorded under the corresponding public key by the
    198 exchange.
    199 
    200 .. note::
    201 
    202    Eventually the exchange will need to advertise a policy for how long it will
    203    keep transaction histories for inactive or even fully drained reserves.  We
    204    will therefore need some additional handler similar to :http:get:`/keys </keys>` to
    205    advertise those terms of service.
    206 
    207 
    208 .. include:: exchange/get-reserves-RESERVE_PUB.rst
    209 
    210 .. _withdraw:
    211 .. include:: exchange/post-withdraw.rst
    212 
    213 
    214 .. ts:def:: WithdrawRequest
    215 
    216   interface WithdrawRequest {
    217     // Cipher that is used for the rerserve's signatures.
    218     // For now, only ed25519 signatures are applicable,
    219     // but this might change in future versions.
    220     cipher: "ED25519";
    221 
    222     // The reserve's public key, for the the cipher ED25519,
    223     // to verify the signature ``reserve_sig``.
    224     reserve_pub: EddsaPublicKey;
    225 
    226     // Array of ``n`` hash codes of denomination public keys to order.
    227     // The sum of all denomination's values and fees MUST be
    228     // at most the balance of the reserve. The balance of
    229     // the reserve will be immediatley reduced by that amount.
    230     // If ``max_age`` is set, these denominations MUST support
    231     // age restriction as defined in the output to /keys.
    232     denoms_h: HashCode[];
    233 
    234     // If set, the maximum age to commit to. This implies:
    235     // 1.) it MUST be the same value as the maximum age
    236     //     of the reserve.
    237     // 2.) ``coin_evs`` MUST be an array of ``n*kappa``
    238     // 3.) the denominations in ``denoms_h`` MUST support
    239     //      age restriction.
    240     max_age?: Integer;
    241 
    242     // Master seed for the Clause-Schnorr R-value creation.
    243     // MUST match the /blinding-prepare request.
    244     // MUST NOT have been used in any prior withdraw request.
    245     // MUST be present if one of the fresh coin's
    246     // denomination is of type Clause-Schnorr.
    247     // The ``cs_nonce`` of every Clause-Schnorr envelope in ``coin_evs``
    248     // MUST be derived from it, see `CSCoinEnvelope`.
    249     blinding_seed?: BlindingMasterSeed;
    250 
    251     // Array of blinded coin envelopes of type `CoinEnvelope`.
    252     // If ``max_age`` is not set, MUST be n entries.
    253     // If ``max_age`` is set, MUST be ``n*kappa`` entries,
    254     // arranged in [0..n)..[0..n), with the first n entries
    255     // belonging to kappa=0 etc.
    256     // In case of age restriction, the exchange will
    257     // respond with an index ``gamma``, which is the index
    258     // that shall remain undisclosed during the subsequent
    259     // reveal phase.
    260     // This hash value along with the reserve's public key
    261     // will also be used for recoup operations, if needed.
    262     coin_evs:  CoinEnvelope[];
    263 
    264     // Signature of `TALER_WithdrawRequestPS` created with
    265     // the `reserves's private key <reserve-priv>`.
    266     reserve_sig: EddsaSignature;
    267   }
    268 
    269 .. ts:def:: WithdrawResponse
    270 
    271   interface WithdrawResponse {
    272     // Array of blinded signatures over each ``coin_evs``,
    273     // in the same order as was given in the request.
    274     // The blinded signatures affirm the coin's validity
    275     // after unblinding.
    276     ev_sigs: BlindedDenominationSignature[];
    277 
    278   }
    279 
    280 
    281 .. ts:def:: AgeWithdrawResponse
    282 
    283   interface AgeWithdrawResponse {
    284     // index of the commitments that the client doesn't
    285     // have to disclose in the subsequent call to
    286     // ``/reveal-withdraw``.
    287     noreveal_index: Integer;
    288 
    289     // Signature of `TALER_WithdrawConfirmationPS` whereby
    290     // the exchange confirms the ``noreveal_index``.
    291     exchange_sig: EddsaSignature;
    292 
    293     // `Public EdDSA key <sign-key-pub>` of the exchange that was used to
    294     // generate the signature.  Should match one of the exchange's signing
    295     // keys from ``/keys``.  Again given explicitly as the client might
    296     // otherwise be confused by clock skew as to which signing key was used.
    297     exchange_pub: EddsaPublicKey;
    298 
    299   }
    300 
    301 .. ts:def:: DenominationGoneMessage
    302 
    303   interface DenominationGoneMessage {
    304 
    305     // Taler error code.  Note that beyond
    306     // expiration this message format is also
    307     // used if the key is not yet valid, or
    308     // has been revoked. May be one of
    309     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``
    310     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``
    311     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``
    312     code: Integer;
    313 
    314     // Signature by the exchange over a
    315     // `TALER_DenominationExpiredAffirmationPS`.
    316     // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``.
    317     exchange_sig: EddsaSignature;
    318 
    319     // Public key of the exchange used to create
    320     // the 'exchange_sig.
    321     exchange_pub: EddsaPublicKey;
    322 
    323     // Hash of the denomination public key that is unknown.
    324     h_denom_pub: HashCode;
    325 
    326     // When was the signature created.
    327     timestamp: Timestamp;
    328 
    329     // What kind of operation was requested that now
    330     // failed?
    331     oper: string;
    332 
    333   }
    334 
    335 .. ts:def:: CoinDenominationConflictError
    336 
    337   // Response to an operation on a coin whose public key the exchange
    338   // already knows under a *different* denomination.  Since protocol
    339   // **v42** the response is a proof: it carries the denomination
    340   // signature the exchange holds for the coin, which clients verify
    341   // against ``prev_denom_pub`` (see ``TALER_EXCHANGE_check_coin_denomination_conflict_``).
    342   interface CoinDenominationConflictError {
    343 
    344     // Must be ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``.
    345     code: Integer;
    346 
    347     // A string explaining the conflict.
    348     hint: string;
    349 
    350     // Public key of the coin that was already used with another
    351     // denomination.
    352     coin_pub: EddsaPublicKey;
    353 
    354     // Denomination public key under which the exchange knows the coin.
    355     // Its hash differs from the denomination hash used in the request.
    356     prev_denom_pub: DenominationKey;
    357 
    358     // Signature by ``prev_denom_pub`` over ``coin_pub`` (and
    359     // ``prev_h_age_commitment`` if present), i.e. the denomination
    360     // signature of the coin as issued by the exchange.
    361     prev_denom_sig: DenominationSignature;
    362 
    363     // Age commitment hash stored for the coin.  Present exactly
    364     // if ``prev_denom_pub`` is an age-restricted denomination.
    365     // @since **v42**
    366     prev_h_age_commitment?: AgeCommitmentHash;
    367 
    368   }
    369 
    370 .. ts:def:: CoinAgeCommitmentConflictError
    371 
    372   // Response to an operation on a coin whose public key the exchange
    373   // already knows under the same denomination, but with a different
    374   // age commitment hash.  Since protocol **v42** the response is
    375   // a proof: it carries the denomination signature the exchange holds
    376   // for the coin, which covers ``coin_pub`` and
    377   // ``expected_age_commitment_hash``.
    378   interface CoinAgeCommitmentConflictError {
    379 
    380     // Must be ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH``.
    381     code: Integer;
    382 
    383     // A string explaining the conflict.
    384     hint: string;
    385 
    386     // Public key of the coin.
    387     coin_pub: EddsaPublicKey;
    388 
    389     // Hash of the denomination public key of the coin
    390     // (as stored by the exchange, which equals the one
    391     // used in the request).
    392     h_denom_pub: HashCode;
    393 
    394     // Age commitment hash stored for the coin, ``null`` if
    395     // the exchange knows the coin without one.
    396     expected_age_commitment_hash: AgeCommitmentHash | null;
    397 
    398     // Human-readable description of the mismatch.
    399     conflict_detail: string;
    400 
    401     // Signature by the denomination over ``coin_pub`` and
    402     // ``expected_age_commitment_hash``, i.e. the denomination
    403     // signature of the coin as issued by the exchange.
    404     // @since **v42**
    405     prev_denom_sig: DenominationSignature;
    406 
    407   }
    408 
    409 
    410 .. ts:def:: WithdrawError
    411 
    412   interface SingleWithdrawError {
    413     // Text describing the error.
    414     hint: string;
    415 
    416     // Detailed error code.
    417     code: Integer;
    418 
    419     // Amount left in the reserve.
    420     balance: Amount;
    421 
    422   }
    423 
    424 
    425 
    426 ------------------
    427 
    428 
    429 .. _reveal-withdraw:
    430 
    431 **Reveal-Withdraw**
    432 
    433 This endpoint is called by the client after a call to `withdraw`_,
    434 *if* the original request had ``max_age`` set and
    435 the response was of type `AgeWithdrawResponse`.
    436 Now the client has to disclose for each coin all but one of the κ secrets
    437 that went into creating the blinded coin's planchets,
    438 including the commitment to age restriction,
    439 and prove that the age restriction was set correctly.
    440 
    441 .. include:: exchange/post-reveal-withdraw.rst
    442 
    443 
    444 ----------
    445 Refreshing
    446 ----------
    447 
    448 Refreshing exchanges one old coin against ``n`` new coins, where the sum of
    449 denominations of the new coins must be smaller than the old coin's
    450 denomination plus melting (refresh) and withdrawal fees charged by the exchange.
    451 The refreshing API can be used by wallets to melt partially spent coins, making
    452 transactions with the freshly exchanged coins unlinkable to previous transactions
    453 by anyone except the wallet itself.
    454 
    455 Refreshing is a two-step process, consisting of
    456 
    457 1. the **melting** of the old coin, together with ``kappa`` batches
    458    of blinded planchets candidates,
    459 2. the **reveal** of ``kappa-1`` secrets to prove the proper construction
    460    of the (revealed) batches of blinded planchets candidates.
    461 
    462 
    463 ^^^^
    464 Melt
    465 ^^^^
    466 
    467 .. _melt:
    468 .. include:: exchange/post-melt.rst
    469 
    470 ^^^^^^^^^^^
    471 Reveal-Melt
    472 ^^^^^^^^^^^
    473 
    474 This endpoint is called by the client after a call to `melt`_.
    475 Now the client has to disclose --for each coin--
    476 all but one of the κ secrets that went into creating the blinded coin's planchets,
    477 the transfer public keys (linking the ownership of the old and new coin),
    478 and the commitment to age restriction,
    479 as proof that the age restriction was set correctly (if applicable).
    480 
    481 .. include:: exchange/post-reveal-melt.rst
    482 
    483 
    484 .. _deposit-par:
    485 
    486 -------
    487 Deposit
    488 -------
    489 
    490 Deposit operations are requested f.e. by a merchant during a transaction or a
    491 bidder during an auction.
    492 
    493 For the deposit operation during purchase, the merchant has to obtain the
    494 deposit permission for a coin from their customer who owns the coin.  When
    495 depositing a coin, the merchant is credited an amount specified in the deposit
    496 permission, possibly a fraction of the total coin's value, minus the deposit
    497 fee as specified by the coin's denomination.
    498 
    499 For auctions, a bidder performs a deposit operation and provides all relevant
    500 information for the auction policy (such as timeout and public key as bidder)
    501 and can use the ``exchange_sig`` field from the `DepositSuccessResponse`
    502 message as a proof to the seller for the escrow of sufficient fund.
    503 
    504 
    505 .. _deposit:
    506 
    507 .. include:: exchange/post-batch-deposit.rst
    508 
    509 
    510 ------
    511 Recoup
    512 ------
    513 
    514 The purpose of this API is to allow coins to be cashed back in,
    515 in certain exceptional situations.
    516 This API is only used if the exchange is either about to go out of
    517 business or has had its private signing keys compromised (so in
    518 either case, the protocol is only used in **abnormal**
    519 situations).  In the above cases, the exchange signals to the
    520 wallets that the emergency cash back protocol has been activated
    521 by putting the affected denomination keys into the cash-back
    522 part of the :http:get:`/keys </keys>` response.  If and only if this has happened,
    523 coins that were signed with those denomination keys can be cashed
    524 in using this API.
    525 
    526 Since protocol **v42**, coins are recouped in batches: all coins in one
    527 request must originate from the same withdraw or refresh operation, which
    528 the client identifies by its commitment (``planchets_h`` of the withdraw
    529 request, or ``rc`` of the melt request).  For the coins to be recouped, the
    530 client discloses the secret material from which the exchange recomputes
    531 their blinded envelopes; for the other coins of the same operation it
    532 provides the hashes of the blinded envelopes.  This allows the exchange to
    533 recompute the commitment and thereby verify that the coins were part of the
    534 operation, without having to keep individual envelopes in its database.
    535 Coins from a withdraw operation are paid back to the reserve
    536 (:http:post:`/recoup-withdraw </recoup-withdraw>`), coins from a refresh
    537 operation to the old coin that was melted
    538 (:http:post:`/recoup-refresh </recoup-refresh>`).
    539 
    540 
    541 .. include:: exchange/post-recoup-withdraw.rst
    542 
    543 .. include:: exchange/post-recoup-refresh.rst
    544 
    545 
    546 .. _exchange_refund:
    547 
    548 -------
    549 Refunds
    550 -------
    551 
    552 .. include:: exchange/post-coins-COIN_PUB-refund.rst
    553 
    554 .. _reserve-history:
    555 
    556 ---------------
    557 Reserve History
    558 ---------------
    559 
    560 .. include:: exchange/get-reserves-RESERVE_PUB-history.rst
    561 
    562 
    563 .. _coin-history:
    564 
    565 ------------
    566 Coin History
    567 ------------
    568 
    569 .. include:: exchange/get-coins-COIN_PUB-history.rst
    570 
    571 -----------------------
    572 Tracking wire transfers
    573 -----------------------
    574 
    575 This API is used by merchants that need to find out which wire
    576 transfers (from the exchange to the merchant) correspond to which deposit
    577 operations.  Typically, a merchant will receive a wire transfer with a
    578 **wire transfer identifier** and want to know the set of deposit
    579 operations that correspond to this wire transfer.  This is the
    580 preferred query that merchants should make for each wire transfer they
    581 receive.  If a merchant needs to investigate a specific deposit
    582 operation (i.e. because it seems that it was not paid), then the
    583 merchant can also request the wire transfer identifier for a deposit
    584 operation.
    585 
    586 Sufficient information is returned to verify that the coin signatures
    587 are correct. This also allows governments to use this API when doing
    588 a tax audit on merchants.
    589 
    590 Naturally, the returned information may be sensitive for the merchant.
    591 We do not require the merchant to sign the request, as the same requests
    592 may also be performed by the government auditing a merchant.
    593 However, wire transfer identifiers should have sufficient entropy to
    594 ensure that obtaining a successful reply by brute-force is not practical.
    595 Nevertheless, the merchant should protect the wire transfer identifiers
    596 from his bank statements against unauthorized access, lest his income
    597 situation is revealed to an adversary. (This is not a major issue, as
    598 an adversary that has access to the line-items of bank statements can
    599 typically also view the balance.)
    600 
    601 
    602 .. include:: exchange/get-transfers-WTID.rst
    603 
    604 .. include:: exchange/get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.rst
    605 
    606 
    607 .. _exchange_w2w:
    608 
    609 --------------------------
    610 Wallet-to-wallet transfers
    611 --------------------------
    612 
    613 .. include:: exchange/get-purses-PURSE_PUB-merge.rst
    614 
    615 .. include:: exchange/post-purses-PURSE_PUB-create.rst
    616 
    617 .. include:: exchange/delete-purses-PURSE_PUB.rst
    618 
    619 .. include:: exchange/post-purses-PURSE_PUB-merge.rst
    620 
    621 .. include:: exchange/post-reserves-RESERVE_PUB-purse.rst
    622 
    623 .. include:: exchange/get-contracts-CONTRACT_PUB.rst
    624 
    625 .. include:: exchange/post-purses-PURSE_PUB-deposit.rst
    626 
    627 
    628 .. _exchange_wads:
    629 
    630 ----
    631 Wads
    632 ----
    633 
    634 .. note::
    635 
    636    This is a draft API that is not yet implemented.
    637 
    638 
    639 These endpoints are used to manage exchange-to-exchange payments in support of
    640 wallet-to-wallet payments.  Only another exchange should access this endpoint.
    641 
    642 
    643 .. include:: exchange/get-wads-WAD_ID.rst
    644 
    645 
    646 ------------------
    647 KYC status updates
    648 ------------------
    649 
    650 This section describes endpoints used to set up, complete and
    651 inquire about KYC operations performed by an exchange for
    652 regulatory compliance.
    653 
    654 .. include:: exchange/post-kyc-wallet.rst
    655 
    656 .. include:: exchange/get-kyc-check-H_NORMALIZED_PAYTO.rst
    657 
    658 .. include:: exchange/get-kyc-spa-ACCESS_TOKEN.rst
    659 
    660 .. include:: exchange/get-kyc-info-ACCESS_TOKEN.rst
    661 
    662 .. include:: exchange/post-kyc-upload-ID.rst
    663 
    664 .. include:: exchange/post-kyc-start-ID.rst
    665 
    666 .. include:: exchange/post-kyc-import-EXTERN_PUB.rst
    667 
    668 .. include:: exchange/post-kyc-bulk-EXTERN_PUB.rst
    669 
    670 .. include:: exchange/get-kyc-proof-PROVIDER_NAME.rst
    671 
    672 .. include:: exchange/get-kyc-webhook-PROVIDER_NAME-star.rst
    673 
    674 
    675 --------------
    676 AML operations
    677 --------------
    678 
    679 This API is only for designated AML officers. It is used
    680 to allow exchange staff to monitor suspicious transactions
    681 and freeze or unfreeze accounts suspected of money laundering.
    682 
    683 .. include:: exchange/get-aml-OFFICER_PUB.rst
    684 
    685 .. include:: exchange/get-aml-OFFICER_PUB-measures.rst
    686 
    687 .. include:: exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.rst
    688 
    689 .. include:: exchange/get-aml-OFFICER_PUB-decisions.rst
    690 
    691 .. include:: exchange/get-aml-OFFICER_PUB-legitimizations.rst
    692 
    693 .. include:: exchange/get-aml-OFFICER_PUB-accounts.rst
    694 
    695 .. include:: exchange/get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.rst
    696 
    697 .. include:: exchange/post-aml-OFFICER_PUB-render-form.rst
    698 
    699 .. include:: exchange/post-aml-OFFICER_PUB-decision.rst
    700 
    701 .. include:: exchange/get-aml-OFFICER_PUB-transfers-credit.rst
    702 
    703 .. include:: exchange/get-aml-OFFICER_PUB-wallet-credit.rst
    704 
    705 ---------------
    706 Reserve control
    707 ---------------
    708 
    709 This section describes the reserve control API which can be used to (1)
    710 prevent a reserve from expiring, to (2) pay an annual fee to allow a number of
    711 purses to be created for the respective reserve without paying a purse fee
    712 each time, to (3) obtain KYC information associated with a reserve to prove
    713 the identity of the person sending an invoice to the payer, and to (4) close a
    714 reserve before it would naturally expire and possibly (5) wire the funds to a
    715 designated account.
    716 
    717 .. note::
    718 
    719    This section is about a proposed API. It is not implemented. See also DD 31.
    720 
    721 .. include:: exchange/post-reserves-RESERVE_PUB-open.rst
    722 
    723 .. include:: exchange/get-reserves-RESERVE_PUB-attest.rst
    724 
    725 .. include:: exchange/post-reserves-RESERVE_PUB-attest.rst
    726 
    727 .. include:: exchange/post-reserves-RESERVE_PUB-close.rst
    728 
    729 .. _delete-reserve:
    730 
    731 .. include:: exchange/delete-reserves-RESERVE_PUB.rst