> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.wayex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversions and withdrawals

> Convert between AUD and stablecoin with physical rebalancing, then withdraw to a saved destination.

Treasury conversions exchange an available wallet balance between AUD and a supported stablecoin.
Stablecoin can remain in the wallet for another operation or be withdrawn to a saved, validated
destination on its exact network.

## Before you convert

* Confirm the source balance is available in this tenant account.
* Read the effective pair, network, limits, fees, and quote lifetime.
* API integrations generate one `externalReference` for the quote and a separate one for acceptance.
  Console users do not enter either reference.
* Display the exact rate, fee, source debit, destination amount, network, and expiry returned by Wayex.

## Quote and accept

Creating a quote does not reserve money:

```bash theme={null}
curl -X POST https://api.sandbox.wayex.com/v1/treasury/conversion-quotes \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: conversion-quote-aud-usdc-001" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAsset": "AUD",
    "destinationAsset": "USDC",
    "settlementNetwork": "base",
    "sourceAmount": "1000.00",
    "externalReference": "quote-10027"
  }'
```

Wayex returns the quote ID. The console retains it and submits it when the user confirms; console
users never type or copy a quote ID. API integrations pass the returned `id` as `quoteId` on the
acceptance request and generate the two external references for their own reconciliation.

After the user reviews the unexpired quote, accept it:

```bash theme={null}
curl -X POST https://api.sandbox.wayex.com/v1/treasury/conversions \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: conversion-accept-aud-usdc-001" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "qte_123",
    "externalReference": "conversion-10027"
  }'
```

An expired quote cannot be altered or revived. Create a fresh quote and ask the user to review the
new outcome.

## Physical post-trade rebalancing

Wayex does not credit an IOU and rebalance later. The source reservation remains in place while the
trade and actual provider fund movements complete.

```mermaid theme={null}
sequenceDiagram
  participant T as Transfer account
  participant W as Wayex wallet
  participant X as FX and settlement
  T->>W: Accept exact quote
  W->>W: Reserve full source debit
  W->>X: Settle source funds
  X->>X: Execute trade
  X->>W: Settle destination funds
  W->>W: Capture source and credit destination
  W-->>T: Conversion settled
```

The destination wallet is credited only after all required physical legs succeed. A timeout or
ambiguous provider result remains held or reconciling; it is not treated as failed and automatically
repeated.

## Conversion states

| State or step                | Wallet effect                                                   |
| ---------------------------- | --------------------------------------------------------------- |
| Quote created                | No reservation or movement.                                     |
| `accepted` / source settling | Source debit is reserved.                                       |
| Trading                      | Source remains reserved; destination is not available.          |
| Destination settling         | Source remains reserved; destination is not available.          |
| `settled`                    | Source is captured and backed destination amount is credited.   |
| Held or unknown              | Funds remain protected while Wayex reconciles the real outcome. |
| Proven pre-execution failure | Reservation is released with an immutable movement.             |

## Save a withdrawal destination

A stablecoin withdrawal uses a saved destination owned by this tenant account. The destination fixes
the asset, network, address, and tag or memo where applicable. Destination changes create a new
version instead of rewriting withdrawal history.

<Warning>
  Validate the beneficiary, asset, network, address, and tag or memo out of band before saving a
  destination. A valid address on the wrong network is still the wrong destination.
</Warning>

Client administrators create and deactivate destinations with MFA step-up in the console. API
integrations should use the saved destination ID returned by the destination resource; arbitrary
inline addresses are not part of the normal workflow.

```bash theme={null}
curl -X POST https://api.sandbox.wayex.com/v1/treasury/destinations \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: destination-usdc-ethereum-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transfer operating wallet",
    "asset": "USDC",
    "network": "base",
    "address": "0x1111111111111111111111111111111111111111",
    "externalReference": "wallet-base-01"
  }'
```

List or get a destination before use. To replace details, create a new validated destination and
deactivate the old one with `POST /v1/treasury/destinations/{id}/deactivate`; do not overwrite history.

## Preview, review, and submit a withdrawal

Preview the exact saved-destination withdrawal before asking the user to confirm it:

```bash theme={null}
curl -X POST https://api.sandbox.wayex.com/v1/treasury/withdrawals/preview \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: withdrawal-review-usdc-001" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC",
    "network": "base",
    "amount": "100.00",
    "destinationId": "tdst_123",
    "externalReference": "withdrawal-7781"
  }'
```

Show the returned `principal`, `fee`, `sourceDebit`, `asset`, `network`, `canProceed`, and any
`holdReason`. Previewing does not reserve or send stablecoin. A later create rechecks the balance,
destination, limits, screening, and provider capacity.

After confirmation, submit the same intent with a different stable idempotency key. The accepted
operation response records the authoritative fee and total source debit, which Wayex reserves.
Submission to the blockchain is still asynchronous.

```bash theme={null}
curl -X POST https://api.sandbox.wayex.com/v1/treasury/withdrawals \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: withdrawal-submit-usdc-001" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC",
    "network": "base",
    "amount": "100.00",
    "destinationId": "tdst_123",
    "externalReference": "withdrawal-7781"
  }'
```

Follow `accepted`, `held`, `submitted`, confirmations/finality, `settled`, and `failed` without
collapsing them. A blockchain transaction hash is evidence of submission, not finality.

## Webhooks and safe retries

Subscribe to `treasury.conversion.updated`, `treasury.withdrawal.updated`, and
`treasury.wallet.updated`. Deduplicate by `eventId`, then fetch the current resource.

For quote creation, acceptance, destination creation, and withdrawal submission, keep one
`Idempotency-Key` per logical action and reuse it with an identical payload after a lost response. If
the provider outcome is unknown, do not create a replacement operation. Read and reconcile the
original first.

Browse the generated schemas in the [API reference](/api-reference/overview), then implement
[Operations and reconciliation](/treasury/operations-and-reconciliation).