Swap

Step-by-step guide to converting funds between assets within an account.

Overview

Swaps convert funds between assets within the same account — for example, BRL to USDT or USD to BRL. Every swap references a quote that locks the FX rate. Once executed, a swap cannot be reversed.

Prerequisites

• An active account with sufficient balance in the quote’s source asset.
• Valid authentication credentials.

Steps

1. Create a quote

   Specify the source asset, target asset, and either the amount you want to spend (sourceAmount) or the amount you want to receive (targetAmount).

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/quotes \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>' \
     --header 'Content-Type: application/json' \
     --data '{
       "accountId": "<account-id>",
       "sourceAsset": "BRL",
       "targetAsset": "USDT",
       "sourceAmount": "500.00"
     }'
   

   The response returns the quote id, the locked effectiveRate, the computed targetAmount, and expiresAt. The quote is bound to the account and can be consumed by exactly one operation before it expires.

2. Create the swap

   Reference the account and the quote. No other inputs are needed — source and target assets and amounts are derived from the quote.

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/operations/swap \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>' \
     --header 'Content-Type: application/json' \
     --data '{
       "accountId": "<account-id>",
       "quoteId": "<quote-id>"
     }'
   

   Returns 201 immediately with the operation in REQUESTED status. Settlement happens asynchronously.

3. Track the swap

   Subscribe to OPERATION_COMPLETED and OPERATION_FAILED to receive the terminal outcome — both deliver the same payload as OPERATION_REQUESTED, with currentState.status set to the new status (and currentState.reason populated on failure). The intermediate PROCESSING status is not published as a webhook; poll GET /api/operations/{operationId} if you need to surface it in your UI.

   curl --request GET \
     --url https://api.sandbox.tracefinance.com/api/operations/<operation-id> \
     --header 'Authorization: Bearer <token>'
   

Swaps are forward-only. Once executed at the quoted rate, they cannot be reversed. Verify the effectiveRate on the quote before creating the swap.

What happens next

• Make a withdrawal — send the converted funds out of the account.