diff options
Diffstat (limited to 'core/api-exchange.rst')
| -rw-r--r-- | core/api-exchange.rst | 119 |
1 files changed, 63 insertions, 56 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 15547ed5..2b4f3b2d 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -93,12 +93,15 @@ possibly by using HTTPS. **Request:** :query last_issue_date: optional argument specifying the maximum value of any of the "stamp_start" members of the denomination keys of a "/keys" response that is already known to the client. Allows the exchange to only return keys that have changed since that timestamp. The given value must be an unsigned 64-bit integer representing seconds after 1970. If the timestamp does not exactly match the "stamp_start" of one of the denomination keys, all keys are returned. + :query now: request that the exchange answer the request as if the current time were the value given in "now". The given value must be an unsigned 64-bit integer representing seconds after 1970. This option is used for testing, and in production is likely not supported. **Response:** - :status 200 OK: + :http:statuscode:`200 OK`: The exchange responds with a `ExchangeKeysResponse` object. This request should virtually always be successful. + :http:statuscode:`403 Forbidden`: + The client specified the "now" argument, but the exchange does not allow this option as per its configuration. **Details:** @@ -285,7 +288,8 @@ Obtaining wire-transfer information **Response:** - :status 200: The exchange responds with a `WireResponse` object. This request should virtually always be successful. + :http:statuscode:`200 Ok`: + The exchange responds with a `WireResponse` object. This request should virtually always be successful. **Details:** @@ -355,7 +359,7 @@ Withdrawal This API is used by the wallet to obtain digital coins. -When transfering money to the exchange such as via SEPA transfers, the exchange creates +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 @@ -387,9 +391,9 @@ exchange. **Response:** - :status 200 OK: + :http:statuscode:`200 OK`: The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange, - :status 404 Not Found: + :http:statuscode:`404 Not found`: The reserve key does not belong to a reserve known to the exchange. **Details:** @@ -523,13 +527,14 @@ exchange. **Response:** - :status 200 OK: - The request was succesful, and the response is a `WithdrawResponse`. Note that repeating exactly the same request + :http:statuscode:`200 OK`: + The request was successful, and the response is a `WithdrawResponse`. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coin signature to disk, the coin is not lost. - :status 401 Unauthorized: The signature is invalid. - :status 404 Not Found: + :http:statuscode:`403 Forbidden`: + The signature is invalid. + :http:statuscode:`404 Not found`: The denomination key or the reserve are not known to the exchange. If the denomination key is unknown, this suggests a bug in the wallet as the wallet should have used current denomination keys from ``/keys``. If the @@ -538,7 +543,7 @@ exchange. not yet have completed and might be known to the exchange in the near future. In this case, the wallet should repeat the exact same request later again using exactly the same blinded coin. - :status 403 Forbidden: + :http:statuscode:`403 Forbidden`: The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination. The response is `WithdrawError` object. @@ -620,15 +625,15 @@ denomination. **Response:** - :status 200 Ok: + :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that no double-spending took place. The response will include a `DepositSuccess` object. - :status 401 Unauthorized: + :http:statuscode:`401 Unauthorized`: One of the signatures is invalid. - :status 404 Not Found: + :http:statuscode:`404 Not found`: Either the denomination key is not recognized (expired or invalid) or the wire type is not recognized. - :status 409 Conflict: + :http:statuscode:`409 Conflict`: The deposit operation has either failed because the coin has insufficient residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is @@ -857,14 +862,14 @@ the API during normal operation. exchange. The exchange MUST return a 307 or 308 redirection to the correct base URL if this is the case. - :status 401 Unauthorized: + :http:statuscode:`200 OK`: + The request was successful. The response body is `MeltResponse` in this case. + :http:statuscode:`403 Forbidden`: One of the signatures is invalid. - :status 200 OK: - The request was succesful. The response body is `MeltResponse` in this case. - :status 404: + :http:statuscode:`404 Not found`: the exchange does not recognize the denomination key as belonging to the exchange, or it has expired - :status 409 Conflict: + :http:statuscode:`409 Conflict`: The operation is not allowed as the coin has insufficient residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is @@ -967,7 +972,7 @@ the API during normal operation. .. http:post:: /refreshes/$RCH/reveal - Reveal previously commited values to the exchange, except for the values + Reveal previously committed values to the exchange, except for the values corresponding to the ``noreveal_index`` returned by the /coins/-melt step. The $RCH is the hash over the refresh commitment from the /coins/-melt step @@ -988,12 +993,12 @@ the API during normal operation. not larger than the total remaining value of the coin before the melting operations. Nevertheless, this is not really useful. - :status 200 OK: + :http:statuscode:`200 OK`: The transfer private keys matched the commitment and the original request was well-formed. The response body is a `RevealResponse` - :status 409 Conflict: + :http:statuscode:`409 Conflict`: There is a problem between the original commitment and the revealed private - keys. The returned information is proof of the missmatch, and therefore + keys. The returned information is proof of the mismatch, and therefore rather verbose, as it includes most of the original /refresh/melt request, but of course expected to be primarily used for diagnostics. The response body is a `RevealConflictResponse`. @@ -1058,11 +1063,11 @@ the API during normal operation. **Response:** - :status 200 OK: + :http:statuscode:`200 OK`: All commitments were revealed successfully. The exchange returns an array, typically consisting of only one element, in which each each element contains information about a melting session that the coin was used in. - :status 404 Not Found: + :http:statuscode:`404 Not found`: The exchange has no linkage data for the given public key, as the coin has not yet been involved in a refresh operation. @@ -1131,19 +1136,19 @@ in using this API. **Response:** - :status 200 OK: - The request was succesful, and the response is a `RecoupConfirmation`. + :http:statuscode:`200 OK`: + The request was successful, and the response is a `RecoupConfirmation`. Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the client can commit the coin signature to disk, the coin is not lost. - :status 401 Unauthorized: + :http:statuscode:`401 Unauthorized`: The coin's signature is invalid. - :status 404 Not Found: + :http:statuscode:`404 Not found`: The denomination key is not in the set of denomination keys where emergency pay back is enabled, or the blinded coin is not known to have been withdrawn. - :status 409 Conflict: + :http:statuscode:`409 Conflict`: The operation is not allowed as the coin has insufficient residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is @@ -1242,10 +1247,10 @@ typically also view the balance.) **Response:** - :status 200 OK: + :http:statuscode:`200 OK`: The wire transfer is known to the exchange, details about it follow in the body. The body of the response is a `TrackTransferResponse`. - :status 404 Not Found: + :http:statuscode:`404 Not found`: The wire transfer identifier is unknown to the exchange. .. ts:def:: TrackTransferResponse @@ -1310,16 +1315,18 @@ typically also view the balance.) **Response:** - :status 200 OK: + :http:statuscode:`200 OK`: The deposit has been executed by the exchange and we have a wire transfer identifier. The response body is a `TrackTransactionResponse` object. - :status 202 Accepted: + :http:statuscode:`202 Accepted`: The deposit request has been accepted for processing, but was not yet executed. Hence the exchange does not yet have a wire transfer identifier. The merchant should come back later and ask again. The response body is a `TrackTransactionAcceptedResponse`. - :status 401 Unauthorized: The signature is invalid. - :status 404 Not Found: The deposit operation is unknown to the exchange + :http:statuscode:`401 Unauthorized`: + The signature is invalid. + :http:statuscode:`404 Not found`: + The deposit operation is unknown to the exchange **Details:** @@ -1371,20 +1378,20 @@ Refunds **Response:** - :status 200 Ok: + :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a `RefundSuccess` object. - :status 401 Unauthorized: + :http:statuscode:`401 Unauthorized`: Merchant signature is invalid. This response comes with a standard `ErrorDetail` response. - :status 404 Not found: + :http:statuscode:`404 Not found`: The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match). This response comes with a standard `ErrorDetail` response. - :status 409 Conflict: + :http:statuscode:`409 Conflict`: The exchange has previously received a refund request for the same coin, merchant and contract, but specifying a different amount for the same refund transaction ID. The response will be a `RefundFailure` object. - :status 410 Gone: + :http:statuscode:`410 Gone`: It is too late for a refund by the exchange, the money was already sent to the merchant. This response comes with a standard `ErrorDetail` response. - :status 412 Precondition Failed: + :http:statuscode:`412 Precondition failed`: The request transaction ID is identical to a previous refund request by the same merchant for the same coin and contract, but the refund amount differs. (The failed precondition is that the ``rtransaction_id`` is not unique.) @@ -1431,21 +1438,21 @@ Refunds exchange_pub: EddsaPublicKey; } - .. ts:def:: RefundFailure + .. ts:def:: RefundFailure - interface RefundFailure { + interface RefundFailure { - // Numeric error code unique to the condition, which can be either - // related to the deposit value being insufficient for the requested - // refund(s), or the requested refund conflicting due to refund - // transaction number re-use (with different amounts). - code: number; + // Numeric error code unique to the condition, which can be either + // related to the deposit value being insufficient for the requested + // refund(s), or the requested refund conflicting due to refund + // transaction number re-use (with different amounts). + code: number; - // Human-readable description of the error message - hint: string; + // Human-readable description of the error message + hint: string; - // Information about the conflicting refund request(s). - // This will not be the full history of the coin, but only - // the relevant subset of the transactions. - history: CoinSpendHistoryItem[]; - } + // Information about the conflicting refund request(s). + // This will not be the full history of the coin, but only + // the relevant subset of the transactions. + history: CoinSpendHistoryItem[]; + } |