Add Travel Rule documentation

_entities.md

@@ -260,10 +260,12 @@ network      | The network of the transaction (`uphold` for internal transaction
 normalized   | The transaction details in USD. See [Normalized](#normalized).
 origin       | The sender of the funds. See [Origin](#origin).
 params       | Other parameters of this transaction. See [Parameters](#parameters).
-priority     | The priority of the transaction. Possible values are `normal` and `fast`.
-reference    | A reference code assigned to the transaction. Can be any string, up to 100 characters. This is not exposed to the user; a possible use case is to reference an external ID in another system.
-status       | The current status of the transaction. Possible values are `pending`, `processing`, `cancelled`, `failed` and `completed`.
-type         | The nature of the transaction. Possible values are `deposit`, `transfer` and `withdrawal`.
+priority             | The priority of the transaction. Possible values are `normal` and `fast`.
+reference            | A reference code assigned to the transaction. Can be any string, up to 100 characters. This is not exposed to the user; a possible use case is to reference an external ID in another system.
+requirements         | An array of requirement codes that must be fulfilled before the transaction can be committed. May include `user-subject-to-extended-travel-rule`. Absent when no requirements apply.
+requirementsDetails  | An object with additional details about each requirement. See [Requirements Details](#requirements-details). Absent when no requirements apply.
+status               | The current status of the transaction. Possible values are `pending`, `processing`, `cancelled`, `failed` and `completed`.
+type                 | The nature of the transaction. Possible values are `deposit`, `transfer` and `withdrawal`.
 
 <aside class="notice">
   A transaction can involve 3 different currencies: the currency as <strong>denominated</strong> by the user, the currency at the <strong>origin</strong> card and the currency at the <strong>destination</strong> card. For instance, <i>"transfer 1 BTC from my USD card to my EUR card"</i>. In this case, 1 BTC would be the denominated amount, but the equivalent in USD is debited at the origin, then credited in EUR at the destination.
@@ -369,6 +371,16 @@ node        | The details about the transaction destination node.
 rate        | The rate for conversion between origin and destination, as expressed in the currency at destination (the inverse of `origin.rate`).
 type        | The type of endpoint. Possible values are `email`, `card` and `external`.
 
+### Requirements Details
+
+When a transaction is subject to the Travel Rule, the `requirementsDetails` object contains the following properties:
+
+Property                 | Description
+------------------------ | -----------
+isAddressVerified        | Whether the destination address has already been verified by the Travel Rule service.
+isRequired               | Whether the Travel Rule information is required before the transaction can be committed.
+requestForInformationId  | The ID of the pending travel rule request. Use this value with the [Get Travel Rule Details](#get-travel-rule-details) and [Submit Travel Rule Information](#submit-travel-rule-information) endpoints.
+
 ## User Object
 
 > An example user encoded in JSON looks like this:

_transactions.md

@@ -100,6 +100,21 @@ curl https://api.uphold.com/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions
 }
 ```
 
+> When the Travel Rule applies to the transaction, the response also includes:
+
+```json
+{
+  "requirements": [
+    "user-subject-to-extended-travel-rule"
+  ],
+  "requirementsDetails": {
+    "isAddressVerified": false,
+    "isRequired": true,
+    "requestForInformationId": "dbff3776-7528-450d-bc9f-e78ae3695949"
+  }
+}
+```
+
 > Step 2: Commit the Transaction
 
 ```bash
@@ -164,6 +179,10 @@ Returns a [Transaction Object](#transaction-object).
   If the deposit origin is a <code>CARD</code> account ID and the query string parameter <code>?commit=true</code> is set,
   the transaction's <code>params</code> will include a <code>redirect</code> field with information of a redirect URI to be followed to complete the credit card deposit.
 </aside>
+<aside class="notice">
+  If the withdrawal is subject to the Travel Rule, the response will include a <code>requirements</code> array and a <code>requirementsDetails</code> object containing the <code>requestForInformationId</code>.
+  The travel rule information must be submitted via the <a href="#submit-travel-rule-information">Submit Travel Rule Information</a> endpoint before <a href="#step-2-commit-transaction">committing the transaction</a>.
+</aside>
 
 ### Step 2: Commit Transaction
 

_travelrule.md

@@ -0,0 +1,177 @@
+# Travel Rule
+
+The Travel Rule is a regulatory requirement that mandates Virtual Asset Service Providers (VASPs) to collect and transmit originator and beneficiary information for cryptocurrency transfers above a certain threshold.
+When a deposit or a withdrawal triggers this requirement, Uphold issues a request for information that must be fulfilled before the transfer can proceed.
+
+There are two ways to retrieve the details of a travel rule request, depending on the context:
+
+- **Deposits**: the transaction is already present and may have a pending travel rule request associated with it. Use [Get Travel Rule Details for a Transaction](#get-travel-rule-details-for-a-transaction) with the `transactionId` to retrieve those details.
+- **Withdrawals**: when [creating a quote](#step-1-create-transaction), the transaction response may include a `requirementsDetails.requestForInformationId` if the Travel Rule applies. Use [Get Travel Rule Details](#get-travel-rule-details) with that ID to retrieve the details, then [Submit Travel Rule Information](#submit-travel-rule-information) before [committing the quote](#step-2-commit-transaction).
+
+## Get Travel Rule Details for a Transaction
+
+```bash
+curl https://api.uphold.com/v0/me/travel-rule/transactions/2c326b15-7106-48be-a326-06f19e69746b/request \
+  -H "Authorization: Bearer <token>"
+```
+
+> The above command returns the following JSON:
+
+```json
+{
+  "amount": "1500.00",
+  "currency": "USDT",
+  "formSchema": {
+    "properties": {
+      "beneficiaryAccountNumber": {
+        "title": "Beneficiary account number",
+        "type": "string"
+      },
+      "beneficiaryAddress": {
+        "title": "Beneficiary address",
+        "type": "string"
+      },
+      "beneficiaryCountry": {
+        "title": "Beneficiary country",
+        "type": "string"
+      },
+      "beneficiaryName": {
+        "title": "Beneficiary name",
+        "type": "string"
+      }
+    },
+    "required": [
+      "beneficiaryName",
+      "beneficiaryAddress",
+      "beneficiaryCountry",
+      "beneficiaryAccountNumber"
+    ],
+    "type": "object"
+  },
+  "threshold": "1000.00"
+}
+```
+
+Retrieves the details of the pending travel rule request associated with a deposit transaction, including the transaction amount, the applicable regulatory threshold, and the form schema describing the information that must be submitted.
+
+### Request
+
+`GET https://api.uphold.com/v0/me/travel-rule/transactions/:transactionId/request`
+
+<aside class="notice">
+  Requires the <code>transactions:read</code> scope for Uphold Connect applications. Returns a <a href="#errors">401 HTTP error</a> if the token is missing or invalid, or a <a href="#errors">403 HTTP error</a> if the required scope is not present.
+</aside>
+<aside class="notice">
+  Returns a <a href="#errors">404 HTTP error</a> if no pending travel rule request is associated with the given transaction.
+</aside>
+
+### Response
+
+Returns an object with the following properties:
+
+Property      | Description
+------------- | -----------
+amount        | The transaction amount that triggered the travel rule requirement.
+currency      | The currency of the transaction.
+formSchema    | A JSON Schema object describing the fields the user must provide via the [Submit Travel Rule Information](#submit-travel-rule-information) endpoint.
+threshold     | The regulatory threshold above which the travel rule applies, in the same currency as `amount`.
+
+## Get Travel Rule Details
+
+```bash
+curl https://api.uphold.com/v0/me/travel-rule/requests/a4e5e6f7-1234-5678-abcd-ef0123456789 \
+  -H "Authorization: Bearer <token>"
+```
+
+> The above command returns the following JSON:
+
+```json
+{
+  "amount": "1500.00",
+  "currency": "USDT",
+  "formSchema": {
+    "properties": {
+      "beneficiaryAccountNumber": {
+        "title": "Beneficiary account number",
+        "type": "string"
+      },
+      "beneficiaryAddress": {
+        "title": "Beneficiary address",
+        "type": "string"
+      },
+      "beneficiaryCountry": {
+        "title": "Beneficiary country",
+        "type": "string"
+      },
+      "beneficiaryName": {
+        "title": "Beneficiary name",
+        "type": "string"
+      }
+    },
+    "required": [
+      "beneficiaryName",
+      "beneficiaryAddress",
+      "beneficiaryCountry",
+      "beneficiaryAccountNumber"
+    ],
+    "type": "object"
+  },
+  "threshold": "1000.00"
+}
+```
+
+Retrieves the details of a pending travel rule request for a withdrawal, using the `requestForInformationId` returned as part of the quote response.
+
+### Request
+
+`GET https://api.uphold.com/v0/me/travel-rule/requests/:requestForInformationId`
+
+<aside class="notice">
+  Requires the <code>transactions:read</code> scope for Uphold Connect applications. Returns a <a href="#errors">401 HTTP error</a> if the token is missing or invalid, or a <a href="#errors">403 HTTP error</a> if the required scope is not present.
+</aside>
+<aside class="notice">
+  The <code>:requestForInformationId</code> must be owned by the authenticated user. A <a href="#errors">404 HTTP error</a> is returned otherwise.
+</aside>
+
+### Response
+
+Returns an object with the following properties:
+
+Property      | Description
+------------- | -----------
+amount        | The transaction amount that triggered the travel rule requirement.
+currency      | The currency of the transaction.
+formSchema    | A JSON Schema object describing the fields the user must provide via the [Submit Travel Rule Information](#submit-travel-rule-information) endpoint.
+threshold     | The regulatory threshold above which the travel rule applies, in the same currency as `amount`.
+
+## Submit Travel Rule Information
+
+```bash
+curl https://api.uphold.com/v0/me/travel-rule/requests/a4e5e6f7-1234-5678-abcd-ef0123456789 \
+  -X POST \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{ "beneficiaryAccountNumber": "0x1234abcd", "beneficiaryAddress": "123 Main St", "beneficiaryCountry": "US", "beneficiaryName": "Jane Doe" }'
+```
+
+Submits the originator or beneficiary information required to fulfill a pending travel rule request.
+The fields in the request body must conform to the `formSchema` returned by the [Get Travel Rule Details for a Transaction](#get-travel-rule-details-for-a-transaction) or [Get Travel Rule Details](#get-travel-rule-details) endpoints.
+For withdrawals, this must be submitted before [committing the quote](#step-2-commit-transaction).
+
+### Request
+
+`POST https://api.uphold.com/v0/me/travel-rule/requests/:requestForInformationId`
+
+<aside class="notice">
+  Requires the <code>transactions:write</code> scope for Uphold Connect applications. Returns a <a href="#errors">401 HTTP error</a> if the token is missing or invalid, or a <a href="#errors">403 HTTP error</a> if the required scope is not present.
+</aside>
+<aside class="notice">
+  The <code>:requestForInformationId</code> must be owned by the authenticated user. A <a href="#errors">404 HTTP error</a> is returned otherwise.
+</aside>
+
+The request body must be a valid JSON object whose properties satisfy the `formSchema` associated with the given `requestForInformationId`.
+A <a href="#errors">400 HTTP error</a> is returned if the request body is not a valid JSON object.
+
+### Response
+
+Returns HTTP status code `204` with an empty body upon success.