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