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.

Auto-convert deposits into your AUD balance

The conversion endpoints on this page act on balance you already hold. If instead you want incoming stablecoin to arrive in your Treasury account already converted to AUD — with no manual quote or accept step — point a direct off-ramp payment route at your own Treasury account:

Get your AUD account details

Provision an AUD funding instrument and note its BSB and account number (or its PayID).

Create an off-ramp route to those details

Create an ordinary off-ramp (stablecoin → AUD) payment route whose AUD payout destination is that Treasury BSB/account (or PayID).

Fund the route

Send stablecoin to the route. Wayex converts at the live rate the instant the funds land (route-funded pricing), pays the AUD to your Treasury account, and credits your Treasury AUD wallet as an ordinary pay-in.

This is a normal off-ramp route pointed at your own account’s details — there is no separate “treasury” route type and nothing extra to configure. Each funding appears as a route conversion, and the resulting AUD lands as a Treasury pay-in you reconcile from Funding and balances.

Before you convert

Confirm the source balance is available in this tenant account.
Read the effective pair, 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, and expiry returned by Wayex.
Converting AUD to a stablecoin, you name the settlement network. See Choosing the settlement network below. Converting a stablecoin to AUD, you do not: that direction routes from the balance you already hold.
Every quote returns the settlementNetwork it was struck on. Store it for reconciliation.

Quote and accept

Creating a quote does not reserve money:

curl -X POST https://api.sandbox.rails.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 and the settlement network the quote was struck on. The console retains the quote ID 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. The reverse direction omits the field — Wayex settles the stablecoin you already hold:

curl -X POST https://api.sandbox.rails.wayex.com/v1/treasury/conversion-quotes \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: conversion-quote-usdc-aud-001" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAsset": "USDC",
    "destinationAsset": "AUD",
    "sourceAmount": "500.00",
    "externalReference": "quote-10028"
  }'

After the user reviews the unexpired quote, accept it:

curl -X POST https://api.sandbox.rails.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.

Choosing the settlement network

Converting AUD to a stablecoin buys coin that has to be delivered onto one specific chain. That chain is the chain your account then holds the balance on, and the chain you can withdraw it on — so you choose it, and settlementNetwork is required on the quote request. There is no default and no fallback. The chains available to your account are the runtimeCapabilities entries on GET /v1/treasury. Pick one your account can actually withdraw on.

Response	Meaning	What to do
`400` `settlement_network_required`	The request converts AUD to a stablecoin and omitted `settlementNetwork`.	Name the chain. Do not retry the same body.
`400` `unsupported_asset_network`	That asset does not settle on that chain, or Wayex cannot receive it there.	Choose a different chain. This is not transient.
`409` `conversion_route_conflict`	Wayex has a settlement route pinned for that asset and you named a different one.	Use the pinned chain. Contact Wayex if you need the route changed.
`422` `asset_network_unavailable`	The pair is supported and wired but not currently enabled for your account.	Contact Wayex to have the pair enabled.

Converting a stablecoin to AUD is unchanged and needs no network: Wayex settles from the chains your account actually holds that stablecoin on. Supplying settlementNetwork in that direction is an optional override and is still checked against any pinned route.

Convert onto a chain you can leave on. A balance settled onto a chain you never fund again can still be converted back to AUD, but a stablecoin withdrawal on a chain your account has no credited deposit or settled conversion for is held for review — see Withdrawals on a network you do not hold.

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` / trading	Source debit is reserved.
Source settling	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 destinations with MFA step-up in the console; deactivating a destination requires an authenticated administrator session. 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.rails.wayex.com/v1/treasury/destinations \
  -H "Authorization: Bearer $WAYEX_SECRET_KEY" \
  -H "Idempotency-Key: destination-usdc-base-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "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.rails.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.rails.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.

Withdrawals on a network you do not hold

A wallet balance is held per asset, but the coin itself sits on a specific chain. Wayex only sends a stablecoin withdrawal out on a network your account demonstrably holds that asset on — a credited deposit on that network, or a settled conversion that delivered onto it. A withdrawal naming any other network is still accepted and its source debit is still reserved, but it is recorded as held with statusReason withdrawal_network_not_held and is never submitted until Wayex releases it. Read it as “this account has no balance evidence on that chain”, not as an outage — retrying the same request will not clear it. Either withdraw on a network you have funded, or convert onto that network first. The withdrawal preview does not test this restriction: a withdrawal on an unheld network previews cleanly with canProceed true and is held on create. Treat the create response as authoritative.

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.

Get started

Treasury guide

Console guide

Conversions and withdrawals

Auto-convert deposits into your AUD balance

Before you convert

Quote and accept

Choosing the settlement network

Physical post-trade rebalancing

Conversion states

Save a withdrawal destination

Preview, review, and submit a withdrawal

Withdrawals on a network you do not hold

Webhooks and safe retries

​Auto-convert deposits into your AUD balance

​Before you convert

​Quote and accept

​Choosing the settlement network

​Physical post-trade rebalancing

​Conversion states

​Save a withdrawal destination

​Preview, review, and submit a withdrawal

​Withdrawals on a network you do not hold

​Webhooks and safe retries

Auto-convert deposits into your AUD balance

Before you convert

Quote and accept

Choosing the settlement network

Physical post-trade rebalancing

Conversion states

Save a withdrawal destination

Preview, review, and submit a withdrawal

Withdrawals on a network you do not hold

Webhooks and safe retries