Conversions and withdrawals

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:

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:

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. 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.

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.

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.

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:

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.

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, then implement Operations and reconciliation.

​Before you convert

​Quote and accept

​Physical post-trade rebalancing

​Conversion states

​Save a withdrawal destination

​Preview, review, and submit a withdrawal

​Webhooks and safe retries

Before you convert

Quote and accept

Physical post-trade rebalancing

Conversion states

Save a withdrawal destination

Preview, review, and submit a withdrawal

Webhooks and safe retries