# Exchange and authorise

## Exchange information and authorise execution

An assessment result of **Allow** is not permission to move funds. Keep your payment
job on hold until its current requirements and the separate execution check pass.
The execution path covers outgoing and incoming institutional transfers. [Self-hosted wallets](https://trust.myaza.co/documentation/travel-rule-self-hosted/markdown) use a separate signed-wallet path.
Below-threshold authorisation requires an explicit qualified policy, not just a low amount.

1. Complete the information review and the independent country reviews for the exact
   active policy version. Review all source, destination and organisation countries.
2. Create or refresh clearance with `POST /transactions/{id}/travel-rule/transfer`.
3. Prepare the message with `POST /transactions/{id}/travel-rule/exchanges`, using
   the current `expectedRevision` and the receiving institution's `travelAddress`.
   Myaza selects the matching existing approved route automatically. `connectionId`
   remains supported and is required if multiple scoped routes match that origin.
   An ordinary wallet address cannot select a route. Use a UUID v4 `Idempotency-Key`.
4. Send once with `POST /transactions/{id}/travel-rule/exchanges/{messageId}/send`.
   Wait for an authenticated acceptance. An uncertain or conflicting reply stays held.
5. From your backend, request and consume an execution authorisation as shown below.

Your original transaction must identify exactly one `recipient` crypto-wallet
instrument, with its real `identifier` and `network`. An opaque wallet reference,
masked address or customer-supplied verified flag is not sufficient. The assessed
address and institution-approved address must both match `recipientAddress` exactly.
The amount, asset and network come from the immutable assessed transaction.

### Request a short-lived authorisation

```http
POST /api/v1/transactions/{id}/travel-rule/execution/authorisations
Authorization: Bearer <secret-api-key>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "expectedRevision": 2,
  "recipientAddress": "<exact-assessed-wallet-address>"
}
```

The response contains `authorisation.id`, `authorisation.token` and
`authorisation.expiresAt`. The signed token expires within 60 seconds. Keep it on
your backend and out of logs, analytics, URLs and browser storage. Do not treat a
valid signature or successful issuance as permission to send funds.

### Consume once, immediately before execution

Your organisation's wallet executes the transfer; Myaza supplies the compliance
authorisation. Integrate this gate into your backend before the wallet sends funds.
You do not need to give Myaza custody of your funds. Your system owns submission,
duplicate prevention, transaction confirmation and reconciliation. A webhook or
an assessment's Allow is not a payment instruction: check current authorisation.

Persist a unique UUID `externalExecutionId` in your own durable payment job before
this request. Use the same secret API key that requested the authorisation.

```http
POST /api/v1/transactions/{id}/travel-rule/execution/consume
Authorization: Bearer <secret-api-key>
Content-Type: application/json

{
  "expectedRevision": 2,
  "recipientAddress": "<exact-assessed-wallet-address>",
  "token": "<authorisation.token>",
  "externalExecutionId": "<durable-payment-job-uuid>"
}
```

Myaza checks the current policy, country reviews, fraud decision, recipient, exchange
evidence, connection, network catalogue and retention approval again. A changed or expired prerequisite
holds the transfer even when the token has not expired.

- `action: "execute_once"`: execute that exact durable job once. Your payment or
  custody integration must enforce the same job identifier against duplicate sends.
- `action: "reconcile_execution"`: this is a replay, not another permission. Look up
  the existing job and reconcile it; never create a new payment.
- Any error, missing response or ambiguous result: keep the job held. Read
  `GET /transactions/{id}/travel-rule/execution` to reconcile the recorded receipt.
  This read remains available after token expiry; it does not grant new permission.

A transfer can have only one consumption receipt, across every token and revision.
The receipt's `settlementStatus: "UNKNOWN"` is intentional: authorisation is not
evidence of a broadcast or settlement. Myaza does not move funds. If the execution
result is lost or uncertain, resolve it with your wallet system before taking any
further action. Do not automatically retry a funds-moving operation with a new ID.