taler-docs

api-exchange.rst (23926B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2014-2026 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 3.0, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
   @author Christian Grothoff
   @author Özgür Kesim
 
 ====================
 Exchange RESTful API
 ====================
 
 The API specified here follows the :ref:`general conventions <http-common>`
 for all details not specified in the individual requests.
 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
 defines all specific terms used in this section.
 
 
 ---------------
 Version History
 ---------------
 
 The currently implemented protocol version is **v42**.
 
 * Wallet-core is currently targeting **vXX**.
 * The merchant is currently targeting **v34**.
 * The AML SPA is currently targeting **v41**.
 * The KYC SPA is currently targeting **v30**.
 
 **Version history:**
 
 * ``v29``: AML reporting on KYC auth transfers
 * ``v30``: various minor feature additions
 * ``v31``: improvements for AML reporting
 * ``v32``: support for extra_wire_subject_metadata
 * ``v33``: addition of accumulated_total_without_fee in :http:post:`/batch-deposit </batch-deposit>`
 * ``v34``: new offline signature; support for open_banking_gateway and
            prepared_transfer_url per wire account in :http:get:`/keys </keys>`
 * ``v35``: adds ``default_p2p_push_expiration`` to :http:get:`/keys </keys>`
 * ``v36``: adds ``kyc_swap_tos_acceptance`` to :http:get:`/keys </keys>`
 * ``v37``: adds :http:get:`/aml/$OFFICER_PUB/wallet-credit </aml/$OFFICER_PUB/wallet-credit>` endpoint
 * ``v38``: adds ``build_version`` to :http:get:`/config </config>`
 * ``v39``: adds ``exchange_payto_uri`` to
            :http:get:`/transfers/$WTID </transfers/$WTID>`
 * ``v40``: adds :http:get:`/aml/$OFFICER_PUB </aml/$OFFICER_PUB>` to report
            the authenticated AML officer's name and access level
 * ``v41``: adds :http:post:`/aml/$OFFICER_PUB/render-form </aml/$OFFICER_PUB/render-form>`
            to preview filled AML/KYC forms as PDF
 * ``v42``: batch recoup protocol: adds :http:post:`/recoup-withdraw </recoup-withdraw>`
            and :http:post:`/recoup-refresh </recoup-refresh>`, removes
            ``/coins/$COIN_PUB/recoup`` and ``/coins/$COIN_PUB/recoup-refresh``;
            adds ``planchets_h``, ``rc`` and ``coin_index`` to the recoup entries
            of coin and reserve histories;
            coin conflict proofs: specifies `CoinDenominationConflictError`
            and `CoinAgeCommitmentConflictError` for the 409 responses with
            error codes ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``
            and ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH``, which
            now carry the stored denomination signature (and age commitment
            hash) of the coin so that clients can verify the conflict;
            adds the required ``reserve_pub`` field to the
            :http:post:`/reveal-withdraw </reveal-withdraw>` request body,
            so that a withdraw operation is identified by the pair
            (reserve, commitment) everywhere
 
 **Upcoming versions:**
 
 * ``vIMPORT``: external KYC/KYB data import
 * ``vATTEST``: KYC attestation support
 
 **Ideas for future version:**
 
 * ``vXXX``: marker for features not yet targeted for release
 
 .. include:: tos.rst
 
 .. _keys:
 
 ---------------------------
 Exchange status information
 ---------------------------
 
 This API is used by wallets and merchants to obtain global information about
 the exchange, such as online signing keys, available denominations and the fee
 structure.  This is typically the first call any exchange client makes, as it
 returns information required to process all of the other interactions with the
 exchange.  The returned information is secured by (1) signature(s) from the exchange,
 especially the long-term offline signing key of the exchange, which clients should
 cache; (2) signature(s) from auditors, and the auditor keys should be
 hard-coded into the wallet as they are the trust anchors for Taler; (3)
 possibly by using HTTPS.
 
 
 .. include:: exchange/get-seed.rst
 
 .. include:: exchange/get-config.rst
 
 .. include:: exchange/get-keys.rst
 
 
 ----------------------------------------------
 Management operations authorized by master key
 ----------------------------------------------
 
 .. include:: exchange/get-management-keys.rst
 
 .. include:: exchange/post-management-keys.rst
 
 .. include:: exchange/post-management-denominations-H_DENOM_PUB-revoke.rst
 
 .. include:: exchange/post-management-signkeys-EXCHANGE_PUB-revoke.rst
 
 .. include:: exchange/post-management-auditors.rst
 
 .. include:: exchange/post-management-auditors-AUDITOR_PUB-disable.rst
 
 .. include:: exchange/post-management-wire-fee.rst
 
 .. include:: exchange/post-management-global-fees.rst
 
 .. include:: exchange/post-management-wire.rst
 
 .. include:: exchange/post-management-wire-disable.rst
 
 .. include:: exchange/post-management-drain.rst
 
 .. include:: exchange/post-management-aml-officers.rst
 
 .. include:: exchange/post-management-partners.rst
 
 ---------------
 Auditor actions
 ---------------
 
 .. _auditor_action:
 
 This part of the API is for the use by auditors interacting with the exchange.
 
 .. include:: exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.rst
 
 
 ----------------
 Blinding Prepare
 ----------------
 
 Certain denomination cipher types, such as Clause-Schnorr, require input values
 from the exchange-side as preparation for the blinding of the coins.  See the
 Bachelor thesis of Gian Demarmels and Lucien Heuzeveldt,
 `Adding Schnorr’s Blind Signature in Taler <https://www.taler.net/papers/cs-thesis.pdf>`_,
 for details.
 
 .. include:: exchange/post-blinding-prepare.rst
 
 
 .. _exchange-withdrawal:
 
 ----------
 Withdrawal
 ----------
 
 This API is used by the wallet to obtain digital coins.
 
 When transferring money to the exchange such as via SEPA transfers, the exchange creates
 a *reserve*, which keeps the money from the customer.  The customer must
 specify an EdDSA reserve public key as part of the transfer, and can then
 withdraw digital coins using the corresponding private key.  All incoming and
 outgoing transactions are recorded under the corresponding public key by the
 exchange.
 
 .. note::
 
    Eventually the exchange will need to advertise a policy for how long it will
    keep transaction histories for inactive or even fully drained reserves.  We
    will therefore need some additional handler similar to :http:get:`/keys </keys>` to
    advertise those terms of service.
 
 
 .. include:: exchange/get-reserves-RESERVE_PUB.rst
 
 .. _withdraw:
 .. include:: exchange/post-withdraw.rst
 
 
 .. ts:def:: WithdrawRequest
 
   interface WithdrawRequest {
     // Cipher that is used for the rerserve's signatures.
     // For now, only ed25519 signatures are applicable,
     // but this might change in future versions.
     cipher: "ED25519";
 
     // The reserve's public key, for the the cipher ED25519,
     // to verify the signature ``reserve_sig``.
     reserve_pub: EddsaPublicKey;
 
     // Array of ``n`` hash codes of denomination public keys to order.
     // The sum of all denomination's values and fees MUST be
     // at most the balance of the reserve. The balance of
     // the reserve will be immediatley reduced by that amount.
     // If ``max_age`` is set, these denominations MUST support
     // age restriction as defined in the output to /keys.
     denoms_h: HashCode[];
 
     // If set, the maximum age to commit to. This implies:
     // 1.) it MUST be the same value as the maximum age
     //     of the reserve.
     // 2.) ``coin_evs`` MUST be an array of ``n*kappa``
     // 3.) the denominations in ``denoms_h`` MUST support
     //      age restriction.
     max_age?: Integer;
 
     // Master seed for the Clause-Schnorr R-value creation.
     // MUST match the /blinding-prepare request.
     // MUST NOT have been used in any prior withdraw request.
     // MUST be present if one of the fresh coin's
     // denomination is of type Clause-Schnorr.
     blinding_seed?: BlindingMasterSeed;
 
     // Array of blinded coin envelopes of type `CoinEnvelope`.
     // If ``max_age`` is not set, MUST be n entries.
     // If ``max_age`` is set, MUST be ``n*kappa`` entries,
     // arranged in [0..n)..[0..n), with the first n entries
     // belonging to kappa=0 etc.
     // In case of age restriction, the exchange will
     // respond with an index ``gamma``, which is the index
     // that shall remain undisclosed during the subsequent
     // reveal phase.
     // This hash value along with the reserve's public key
     // will also be used for recoup operations, if needed.
     coin_evs:  CoinEnvelope[];
 
     // Signature of `TALER_WithdrawRequestPS` created with
     // the `reserves's private key <reserve-priv>`.
     reserve_sig: EddsaSignature;
   }
 
 .. ts:def:: WithdrawResponse
 
   interface WithdrawResponse {
     // Array of blinded signatures over each ``coin_evs``,
     // in the same order as was given in the request.
     // The blinded signatures affirm the coin's validity
     // after unblinding.
     ev_sigs: BlindedDenominationSignature[];
 
   }
 
 
 .. ts:def:: AgeWithdrawResponse
 
   interface AgeWithdrawResponse {
     // index of the commitments that the client doesn't
     // have to disclose in the subsequent call to
     // ``/reveal-withdraw``.
     noreveal_index: Integer;
 
     // Signature of `TALER_WithdrawConfirmationPS` whereby
     // the exchange confirms the ``noreveal_index``.
     exchange_sig: EddsaSignature;
 
     // `Public EdDSA key <sign-key-pub>` of the exchange that was used to
     // generate the signature.  Should match one of the exchange's signing
     // keys from ``/keys``.  Again given explicitly as the client might
     // otherwise be confused by clock skew as to which signing key was used.
     exchange_pub: EddsaPublicKey;
 
   }
 
 .. ts:def:: DenominationGoneMessage
 
   interface DenominationGoneMessage {
 
     // Taler error code.  Note that beyond
     // expiration this message format is also
     // used if the key is not yet valid, or
     // has been revoked. May be one of
     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``
     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``
     // - ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``
     code: Integer;
 
     // Signature by the exchange over a
     // `TALER_DenominationExpiredAffirmationPS`.
     // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_EXPIRED``.
     exchange_sig: EddsaSignature;
 
     // Public key of the exchange used to create
     // the 'exchange_sig.
     exchange_pub: EddsaPublicKey;
 
     // Hash of the denomination public key that is unknown.
     h_denom_pub: HashCode;
 
     // When was the signature created.
     timestamp: Timestamp;
 
     // What kind of operation was requested that now
     // failed?
     oper: string;
 
   }
 
 .. ts:def:: CoinDenominationConflictError
 
   // Response to an operation on a coin whose public key the exchange
   // already knows under a *different* denomination.  Since protocol
   // **vCONFLICT** the response is a proof: it carries the denomination
   // signature the exchange holds for the coin, which clients verify
   // against ``prev_denom_pub`` (see ``TALER_EXCHANGE_check_coin_denomination_conflict_``).
   interface CoinDenominationConflictError {
 
     // Must be ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``.
     code: Integer;
 
     // A string explaining the conflict.
     hint: string;
 
     // Public key of the coin that was already used with another
     // denomination.
     coin_pub: EddsaPublicKey;
 
     // Denomination public key under which the exchange knows the coin.
     // Its hash differs from the denomination hash used in the request.
     prev_denom_pub: DenominationKey;
 
     // Signature by ``prev_denom_pub`` over ``coin_pub`` (and
     // ``prev_h_age_commitment`` if present), i.e. the denomination
     // signature of the coin as issued by the exchange.
     prev_denom_sig: DenominationSignature;
 
     // Age commitment hash stored for the coin.  Present exactly
     // if ``prev_denom_pub`` is an age-restricted denomination.
     // @since **vCONFLICT**
     prev_h_age_commitment?: AgeCommitmentHash;
 
   }
 
 .. ts:def:: CoinAgeCommitmentConflictError
 
   // Response to an operation on a coin whose public key the exchange
   // already knows under the same denomination, but with a different
   // age commitment hash.  Since protocol **vCONFLICT** the response is
   // a proof: it carries the denomination signature the exchange holds
   // for the coin, which covers ``coin_pub`` and
   // ``expected_age_commitment_hash``.
   interface CoinAgeCommitmentConflictError {
 
     // Must be ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_AGE_HASH``.
     code: Integer;
 
     // A string explaining the conflict.
     hint: string;
 
     // Public key of the coin.
     coin_pub: EddsaPublicKey;
 
     // Hash of the denomination public key of the coin
     // (as stored by the exchange, which equals the one
     // used in the request).
     h_denom_pub: HashCode;
 
     // Age commitment hash stored for the coin, ``null`` if
     // the exchange knows the coin without one.
     expected_age_commitment_hash: AgeCommitmentHash | null;
 
     // Human-readable description of the mismatch.
     conflict_detail: string;
 
     // Signature by the denomination over ``coin_pub`` and
     // ``expected_age_commitment_hash``, i.e. the denomination
     // signature of the coin as issued by the exchange.
     // @since **vCONFLICT**
     prev_denom_sig: DenominationSignature;
 
   }
 
 
 .. ts:def:: WithdrawError
 
   interface SingleWithdrawError {
     // Text describing the error.
     hint: string;
 
     // Detailed error code.
     code: Integer;
 
     // Amount left in the reserve.
     balance: Amount;
 
   }
 
 
 
 ------------------
 
 
 .. _reveal-withdraw:
 
 **Reveal-Withdraw**
 
 This endpoint is called by the client after a call to `withdraw`_,
 *if* the original request had ``max_age`` set and
 the response was of type `AgeWithdrawResponse`.
 Now the client has to disclose for each coin all but one of the κ secrets
 that went into creating the blinded coin's planchets,
 including the commitment to age restriction,
 and prove that the age restriction was set correctly.
 
 .. include:: exchange/post-reveal-withdraw.rst
 
 
 ----------
 Refreshing
 ----------
 
 Refreshing exchanges one old coin against ``n`` new coins, where the sum of
 denominations of the new coins must be smaller than the old coin's
 denomination plus melting (refresh) and withdrawal fees charged by the exchange.
 The refreshing API can be used by wallets to melt partially spent coins, making
 transactions with the freshly exchanged coins unlinkable to previous transactions
 by anyone except the wallet itself.
 
 Refreshing is a two-step process, consisting of
 
 1. the **melting** of the old coin, together with ``kappa`` batches
    of blinded planchets candidates,
 2. the **reveal** of ``kappa-1`` secrets to prove the proper construction
    of the (revealed) batches of blinded planchets candidates.
 
 
 ^^^^
 Melt
 ^^^^
 
 .. _melt:
 .. include:: exchange/post-melt.rst
 
 ^^^^^^^^^^^
 Reveal-Melt
 ^^^^^^^^^^^
 
 This endpoint is called by the client after a call to `melt`_.
 Now the client has to disclose --for each coin--
 all but one of the κ secrets that went into creating the blinded coin's planchets,
 the transfer public keys (linking the ownership of the old and new coin),
 and the commitment to age restriction,
 as proof that the age restriction was set correctly (if applicable).
 
 .. include:: exchange/post-reveal-melt.rst
 
 
 .. _deposit-par:
 
 -------
 Deposit
 -------
 
 Deposit operations are requested f.e. by a merchant during a transaction or a
 bidder during an auction.
 
 For the deposit operation during purchase, the merchant has to obtain the
 deposit permission for a coin from their customer who owns the coin.  When
 depositing a coin, the merchant is credited an amount specified in the deposit
 permission, possibly a fraction of the total coin's value, minus the deposit
 fee as specified by the coin's denomination.
 
 For auctions, a bidder performs a deposit operation and provides all relevant
 information for the auction policy (such as timeout and public key as bidder)
 and can use the ``exchange_sig`` field from the `DepositSuccessResponse`
 message as a proof to the seller for the escrow of sufficient fund.
 
 
 .. _deposit:
 
 .. include:: exchange/post-batch-deposit.rst
 
 
 ------
 Recoup
 ------
 
 The purpose of this API is to allow coins to be cashed back in,
 in certain exceptional situations.
 This API is only used if the exchange is either about to go out of
 business or has had its private signing keys compromised (so in
 either case, the protocol is only used in **abnormal**
 situations).  In the above cases, the exchange signals to the
 wallets that the emergency cash back protocol has been activated
 by putting the affected denomination keys into the cash-back
 part of the :http:get:`/keys </keys>` response.  If and only if this has happened,
 coins that were signed with those denomination keys can be cashed
 in using this API.
 
 Since protocol **vRECOUP**, coins are recouped in batches: all coins in one
 request must originate from the same withdraw or refresh operation, which
 the client identifies by its commitment (``planchets_h`` of the withdraw
 request, or ``rc`` of the melt request).  For the coins to be recouped, the
 client discloses the secret material from which the exchange recomputes
 their blinded envelopes; for the other coins of the same operation it
 provides the hashes of the blinded envelopes.  This allows the exchange to
 recompute the commitment and thereby verify that the coins were part of the
 operation, without having to keep individual envelopes in its database.
 Coins from a withdraw operation are paid back to the reserve
 (:http:post:`/recoup-withdraw </recoup-withdraw>`), coins from a refresh
 operation to the old coin that was melted
 (:http:post:`/recoup-refresh </recoup-refresh>`).
 
 
 .. include:: exchange/post-recoup-withdraw.rst
 
 .. include:: exchange/post-recoup-refresh.rst
 
 
 .. _exchange_refund:
 
 -------
 Refunds
 -------
 
 .. include:: exchange/post-coins-COIN_PUB-refund.rst
 
 .. _reserve-history:
 
 ---------------
 Reserve History
 ---------------
 
 .. include:: exchange/get-reserves-RESERVE_PUB-history.rst
 
 
 .. _coin-history:
 
 ------------
 Coin History
 ------------
 
 .. include:: exchange/get-coins-COIN_PUB-history.rst
 
 -----------------------
 Tracking wire transfers
 -----------------------
 
 This API is used by merchants that need to find out which wire
 transfers (from the exchange to the merchant) correspond to which deposit
 operations.  Typically, a merchant will receive a wire transfer with a
 **wire transfer identifier** and want to know the set of deposit
 operations that correspond to this wire transfer.  This is the
 preferred query that merchants should make for each wire transfer they
 receive.  If a merchant needs to investigate a specific deposit
 operation (i.e. because it seems that it was not paid), then the
 merchant can also request the wire transfer identifier for a deposit
 operation.
 
 Sufficient information is returned to verify that the coin signatures
 are correct. This also allows governments to use this API when doing
 a tax audit on merchants.
 
 Naturally, the returned information may be sensitive for the merchant.
 We do not require the merchant to sign the request, as the same requests
 may also be performed by the government auditing a merchant.
 However, wire transfer identifiers should have sufficient entropy to
 ensure that obtaining a successful reply by brute-force is not practical.
 Nevertheless, the merchant should protect the wire transfer identifiers
 from his bank statements against unauthorized access, lest his income
 situation is revealed to an adversary. (This is not a major issue, as
 an adversary that has access to the line-items of bank statements can
 typically also view the balance.)
 
 
 .. include:: exchange/get-transfers-WTID.rst
 
 .. include:: exchange/get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.rst
 
 
 .. _exchange_w2w:
 
 --------------------------
 Wallet-to-wallet transfers
 --------------------------
 
 .. include:: exchange/get-purses-PURSE_PUB-merge.rst
 
 .. include:: exchange/post-purses-PURSE_PUB-create.rst
 
 .. include:: exchange/delete-purses-PURSE_PUB.rst
 
 .. include:: exchange/post-purses-PURSE_PUB-merge.rst
 
 .. include:: exchange/post-reserves-RESERVE_PUB-purse.rst
 
 .. include:: exchange/get-contracts-CONTRACT_PUB.rst
 
 .. include:: exchange/post-purses-PURSE_PUB-deposit.rst
 
 
 .. _exchange_wads:
 
 ----
 Wads
 ----
 
   .. note::
 
      This is a draft API that is not yet implemented.
 
 
 These endpoints are used to manage exchange-to-exchange payments in support of
 wallet-to-wallet payments.  Only another exchange should access this endpoint.
 
 
 .. include:: exchange/get-wads-WAD_ID.rst
 
 
 ------------------
 KYC status updates
 ------------------
 
 This section describes endpoints used to set up, complete and
 inquire about KYC operations performed by an exchange for
 regulatory compliance.
 
 .. include:: exchange/post-kyc-wallet.rst
 
 .. include:: exchange/get-kyc-check-H_NORMALIZED_PAYTO.rst
 
 .. include:: exchange/get-kyc-spa-ACCESS_TOKEN.rst
 
 .. include:: exchange/get-kyc-info-ACCESS_TOKEN.rst
 
 .. include:: exchange/post-kyc-upload-ID.rst
 
 .. include:: exchange/post-kyc-start-ID.rst
 
 .. include:: exchange/post-kyc-import-EXTERN_PUB.rst
 
 .. include:: exchange/post-kyc-bulk-EXTERN_PUB.rst
 
 .. include:: exchange/get-kyc-proof-PROVIDER_NAME.rst
 
 .. include:: exchange/get-kyc-webhook-PROVIDER_NAME-star.rst
 
 
 --------------
 AML operations
 --------------
 
 This API is only for designated AML officers. It is used
 to allow exchange staff to monitor suspicious transactions
 and freeze or unfreeze accounts suspected of money laundering.
 
 .. include:: exchange/get-aml-OFFICER_PUB.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-measures.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-decisions.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-legitimizations.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-accounts.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.rst
 
 .. include:: exchange/post-aml-OFFICER_PUB-render-form.rst
 
 .. include:: exchange/post-aml-OFFICER_PUB-decision.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-transfers-credit.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-wallet-credit.rst
 
 ---------------
 Reserve control
 ---------------
 
 This section describes the reserve control API which can be used to (1)
 prevent a reserve from expiring, to (2) pay an annual fee to allow a number of
 purses to be created for the respective reserve without paying a purse fee
 each time, to (3) obtain KYC information associated with a reserve to prove
 the identity of the person sending an invoice to the payer, and to (4) close a
 reserve before it would naturally expire and possibly (5) wire the funds to a
 designated account.
 
   .. note::
 
      This section is about a proposed API. It is not implemented. See also DD 31.
 
 .. include:: exchange/post-reserves-RESERVE_PUB-open.rst
 
 .. include:: exchange/get-reserves-RESERVE_PUB-attest.rst
 
 .. include:: exchange/post-reserves-RESERVE_PUB-attest.rst
 
 .. include:: exchange/post-reserves-RESERVE_PUB-close.rst
 
 .. _delete-reserve:
 
 .. include:: exchange/delete-reserves-RESERVE_PUB.rst