Nuvanté Technologies logo
Sandbox APIhttps://sandbox-api.nuvante.io

Flow guide

Stable-to-stable swap

Swap a member's stablecoin for one from a different issuer, while the two issuers' reserves settle in RTGS.

Run the request

curl --request POST 'https://sandbox-api.nuvante.io/api/v1/transactions' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: swap-20260730-0001' \
  --data '{
  "paymentReference": "DVP-SWAP-0001",
  "source": {
    "amount": "100000.00",
    "asset": {
      "code": "GBPC",
      "issuer": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUWDA"
    }
  },
  "target": {
    "amount": "100000.00",
    "asset": {
      "code": "GBPX",
      "issuer": "GAS4V4O2B7DW5T7IQRPEEVCRXMDZESKISR7DVIGKZQYYV3OSQ5SH5LVP"
    }
  },
  "useCase": "swap"
}'
Try in sandbox

What happens on the happy path

  1. 1

    Validate both assets

    The source and target both need an issuer, and they must be different code and issuer pairs. The engine looks up both issuers and their RTGS reserve accounts.
  2. 2

    Lock the source funds

    The member’s source stablecoin is locked first. A confirmed AssetLocked event sets the chain status to Locked.
  3. 3

    Earmark the source issuer's reserves

    RTGS earmarks the source issuer’s reserve for the target issuer’s reserve account.
  4. 4

    Instruct and prove the source burn

    The source issuer’s adapter handles the burn. InstructionSubmitted and InstructionAuthorised aren't enough to move on. A verified Burned proof has to come first.
  5. 5

    Settle the issuer reserves

    The RTGS leg goes from the source issuer's reserve to the target issuer's reserve, moving through SettleSubmitted to Settled.
  6. 6

    Instruct and prove the target mint

    The target issuer mints the new asset to the member’s account. A verified Minted proof comes before Completed.

Poll, cancel and recover

curl 'https://sandbox-api.nuvante.io/api/v1/transactions/123e4567-e89b-42d3-a456-426614174000' \
  --header 'Authorization: Bearer <api-key>'
Try in sandboxTry in sandbox

Swap outcomes

ConditionResultNotes
Before the source burnCan be cancelledWhen actions.cancel.allowed is true, the engine can release the earmark and return the locked source asset.
After the source burnRecovered going forwardCancelling is no longer safe, so the public route returns 409. Any fix has to respect the fact that the source tokens are already gone.
Earmark rejectedFailed and unwoundThe locked source funds come back, and no burn, settlement or mint happens.
Issuer rejectionCancelled or parkedA rejection before the burn unwinds automatically. A late rejection that can't be safely reversed parks.
Instruction failureParkedAn unclear failure on the source burn or target mint parks for a person to review.
SilencePolled, then parkedThe engine keeps polling for the length of each issuer leg’s SLA and parks once that runs out.