commit 585b70aff0cc381e70f9f523691095980a9588d5
parent 18186c640534bef371de1e303e9c49bb8387202f
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 6 Nov 2025 16:18:35 +0100
expand API to allow fixing #10413
Diffstat:
| M | core/api-exchange.rst | | | 142 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- |
1 file changed, 141 insertions(+), 1 deletion(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -60,7 +60,7 @@ possibly by using HTTPS.
as well as the list of possible KYC requirements. This endpoint is largely
for the SPA for AML officers. Merchants should use ``/keys`` which also
contains the protocol version and currency.
- This specification corresponds to ``current`` protocol being **v30**.
+ This specification corresponds to ``current`` protocol being **v31**.
**Response:**
@@ -5848,6 +5848,146 @@ and freeze or unfreeze accounts suspected of money laundering.
}
+.. http:get:: /aml/$OFFICER_PUB/accounts
+
+ **Request:**
+
+ *Accept*:
+ The client may specify the desired MIME-type for the result.
+ Supported are the usual "application/json", but also
+ "text/csv" (RFC 4180)
+ and "application/vnd.ms-excel" (XML of Excel 2003).
+
+ *Taler-AML-Officer-Signature*:
+ The client must provide Base-32 encoded EdDSA signature with
+ ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that
+ this is merely a simple authentication mechanism, the details of the
+ request are not protected by the signature.
+
+ This endpoint was introduced in this form in protocol **v31**.
+
+ :query limit:
+ *Optional*. takes value of the form ``N (-N)``, so that at
+ most ``N`` values strictly older (younger) than ``start`` are returned.
+ Defaults to ``-20`` to return the last 20 entries (before ``start``).
+ :query offset:
+ *Optional*. Row number threshold, see ``delta`` for its
+ interpretation. Defaults to ``INT64_MAX``, namely the biggest row id
+ possible in the database.
+ :query investigation:
+ *Optional*. If set to yes, only return accounts that are under
+ AML investigation, if no only accounts that are not under investigation.
+ Do not give (or use "all") to see all accounts regardless of
+ investigation status.
+ :query open:
+ *Optional*. If set to yes, only return accounts that are open,
+ which means they crossed some initial limit and now have custom rules.
+ Do not give (or use "all") to see all accounts regardless of
+ open status.
+ :query high_risk:
+ *Optional*. If set to yes, only return accounts that were flagged
+ as high risk.
+ Do not give (or use "all") to see all accounts regardless of
+ risk status.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The response will be an `AmlAccountsResponse` message (if the
+ client's header "Accept" was "application/json"). Other encodings
+ may differ in the exact returned data and format.
+ :http:statuscode:`204 No content`:
+ There are no accounts at all (within the specified constraints).
+ :http:statuscode:`403 Forbidden`:
+ The signature is invalid.
+ :http:statuscode:`404 Not found`:
+ The designated AML account is not known.
+ :http:statuscode:`409 Conflict`:
+ The designated AML account is not enabled.
+
+ **Details:**
+
+ .. ts:def:: AmlAccountsResponse
+
+ interface AmlAccountsResponse {
+
+ // Array of customer accounts matching the query.
+ accounts: CustomerAccountSummary[];
+ }
+
+ .. ts:def:: CustomerAccountSummary
+
+ interface CustomerAccountSummary {
+
+ // Which payto-address is this record about.
+ // Identifies a GNU Taler wallet or an affected bank account.
+ h_payto: NormalizedPaytoHash;
+
+ // Full payto URL of the account that the decision is
+ // about.
+ full_payto: string;
+
+ // True if the account was assessed as being high risk.
+ high_risk: boolean;
+
+ // Latest comments about the account (if any).
+ comments?: string;
+
+ // Row of the account in the exchange tables. Useful to filter
+ // by offset.
+ rowid: Integer;
+
+ // When was the account opened? "never" if it was never opened.
+ open_time: Timestamp;
+
+ // When was the account opened? "never" if it was never closed.
+ close_time: Timestamp;
+
+ // True if the account is under investigation by AML staff
+ // after this decision.
+ to_investigate: boolean;
+
+ }
+
+ .. ts:def:: AccountProperties
+
+ // All fields in this object are optional. The actual
+ // properties collected depend fully on the discretion
+ // of the exchange operator;
+ // however, some common fields are standardized
+ // and thus described here.
+ interface AccountProperties {
+
+ // True if this is a politically exposed account.
+ // Rules for classifying accounts as politically
+ // exposed are country-dependent.
+ pep?: boolean;
+
+ // True if this is a sanctioned account.
+ // Rules for classifying accounts as sanctioned
+ // are country-dependent.
+ sanctioned?: boolean;
+
+ // True if this is a high-risk account.
+ // Rules for classifying accounts as at-risk
+ // are exchange operator-dependent.
+ high_risk?: boolean;
+
+ // Business domain of the account owner.
+ // The list of possible business domains is
+ // operator- or country-dependent.
+ business_domain?: string;
+
+ // Is the client's account currently frozen?
+ is_frozen?: boolean;
+
+ // Was the client's account reported to the authorities?
+ was_reported?: boolean;
+
+ }
+
+
+
.. http:get:: /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO
Obtain attributes obtained as part of AML/KYC processes for a
