summaryrefslogtreecommitdiff
path: root/core/api-exchange.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2022-09-17 23:27:42 +0200
committerChristian Grothoff <christian@grothoff.org>2022-09-17 23:27:42 +0200
commitbe69b01fcc7b5cfc3e2575b50211b2d74e47f83d (patch)
treec89674dbbbb1af78c7ff1773def4aa6558642276 /core/api-exchange.rst
parent8b499f03b48be201ef5afdb1494ccd1011c23eb0 (diff)
downloaddocs-be69b01fcc7b5cfc3e2575b50211b2d74e47f83d.tar.gz
docs-be69b01fcc7b5cfc3e2575b50211b2d74e47f83d.tar.bz2
docs-be69b01fcc7b5cfc3e2575b50211b2d74e47f83d.zip
-propose reserve open/close API
Diffstat (limited to 'core/api-exchange.rst')
-rw-r--r--core/api-exchange.rst172
1 files changed, 172 insertions, 0 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 3e71ba4f..357aa565 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -4372,3 +4372,175 @@ KYC status updates
The webhook succeeded.
:http:statuscode:`404 Not found`:
The specified logic is unknown.
+
+
+---------------
+Reserve control
+---------------
+
+This section is about a proposed API. It is not implemented.
+
+.. http:post:: /reserves/$RESERVE_PUB/open
+
+ Request keeping a reserve open for tipping or invoicing.
+
+ **Request:**
+
+ The request body must be a `ReserveOpenRequest` object.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The exchange responds with a `ReserveOpenResponse` object.
+ :http:statuscode:`402 Payment Required`:
+ The reserve balance is insufficient to pay for the open operation.
+ The exchange responds with a `RequiredBalanceResponse` object.
+ :http:statuscode:`403 Forbidden`:
+ The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid.
+ This response comes with a standard `ErrorDetail` response.
+ :http:statuscode:`404 Not found`:
+ The reserve key does not belong to a reserve known to the exchange.
+ :http:statuscode:`451 Unavailable For Legal Reasons`:
+ This account has not yet passed the KYC checks.
+ The client must pass KYC checks before the reserve can be opened.
+ The response will be an `KycNeededRedirect` object.
+
+ **Details:**
+
+ .. ts:def:: ReserveOpenRequest
+
+ interface ReserveOpenRequest {
+ // Signature of purpose
+ // ``TALER_SIGNATURE_WALLET_RESERVE_OPEN`` over
+ // a `TALER_ReserveOpenRequestSignaturePS`.
+ reserve_sig: EddsaSignature;
+
+ // Time when the client made the request.
+ // Timestamp must be reasonably close to the time of
+ // the exchange, otherwise the exchange may reject
+ // the request (with a status code of 400).
+ request_timestamp: Timestamp;
+
+ // Desired new expiration time for the reserve.
+ // If the reserve would expire before this time,
+ // the exchange will charge account fees (and
+ // possibly KYC fees) until the expiration time
+ // exceeds this timestamp. Note that the exchange
+ // will refuse requests (with a status code of 400)
+ // if the time is so far in the future that the
+ // fees are not yet known (see /keys).
+ reserve_expiration: Timestamp;
+
+ // Desired open purse limit. Can be used to pay the
+ // annual account fee more than once to get a larger
+ // purse limit.
+ purse_limit: Integer;
+
+ }
+
+ .. ts:def:: ReserveOpenResponse
+
+ interface ReserveOpenResponse {
+ // Balance left in the reserve after the account_fee
+ // was charged.
+ balance: Amount;
+
+ // Transaction cost for extending the expiration time.
+ // Excludes KYC fees.
+ open_cost: Amount;
+
+ // New expiration time for the reserve.
+ reserve_expiration: Timestamp;
+ }
+
+ .. ts:def:: RequiredBalanceResponse
+
+ interface RequiredBalanceResponse {
+ // Balance left in the reserve after the account_fee
+ // was charged.
+ balance: Amount;
+
+ // Transaction cost for extending to the
+ // requested expiration time.
+ // Includes applicable KYC fees.
+ required: Amount;
+
+ }
+
+
+
+.. http:post:: /reserves/$RESERVE_PUB/close
+
+ Force immediate closure of a reserve. Does not actually
+ delete the reserve or the KYC data, but merely forces
+ the reserve's current balance to be wired back to the
+ account where it originated from, or another account of
+ the user's choosing if they performed the required KYC
+ check and designated another target account.
+
+ **Request:**
+
+ The request body must be a `ReserveCloseRequest` object.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The exchange responds with a `ReserveCloseResponse` object.
+ :http:statuscode:`403 Forbidden`:
+ The *TALER_SIGNATURE_WALLET_RESERVE_CLOSE* signature is invalid.
+ This response comes with a standard `ErrorDetail` response.
+ :http:statuscode:`404 Not found`:
+ The reserve key does not belong to a reserve known to the exchange.
+ :http:statuscode:`409 Conflict`:
+ No target account was given, and the exchange does not know an
+ origin account for this reserve.
+ :http:statuscode:`451 Unavailable For Legal Reasons`:
+ This account has not yet passed the KYC checks, hence wiring
+ funds to a non-origin account is not allowed.
+ The client must pass KYC checks before the reserve can be opened.
+ The response will be an `KycNeededRedirect` object.
+
+ **Details:**
+
+ .. ts:def:: ReserveCloseRequest
+
+ interface ReserveCloseRequest {
+ // Signature of purpose
+ // ``TALER_SIGNATURE_WALLET_RESERVE_CLOSE`` over
+ // a `TALER_ReserveCloseRequestSignaturePS`.
+ reserve_sig: EddsaSignature;
+
+ // Time when the client made the request.
+ // Timestamp must be reasonably close to the time of
+ // the exchange, otherwise the exchange may reject
+ // the request (with a status code of 400).
+ request_timestamp: Timestamp;
+
+ // Maximum amount to transfer to the indicated
+ // account (after fees). If not given, the
+ // reserve will be completely drained. The amount
+ // given may exceed the reserve balance, in which case
+ // the reserve will also be completely drained.
+ maximum_transfer?: Amount;
+
+ // payto://-URI of the account the reserve balance is to be
+ // wired to. Must be of the form: 'payto://$METHOD' for a
+ // wire method supported by this exchange (if the
+ // method is not supported, this is a bad request (400)).
+ // If not given, the reserve's origin account
+ // will be used. If no origin account is known for the
+ // reserve and not given, this is a conflict (409).
+ payto_uri?: string;
+
+ }
+
+ .. ts:def:: ReserveCloseResponse
+
+ interface ReserveCloseResponse {
+ // Balance left in the reserve after the close.
+ balance: Amount;
+
+ // Actual amount that will be wired (excludes closing fee).
+ wire_amount: Amount;
+
+ }