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

# 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 USDC to BRL. Every swap references a quote that locks the FX rate. Once executed, a swap cannot be reversed.

## Prerequisites

* An [active account](/journeys/open-account) with sufficient balance in the quote's source asset.
* Valid [authentication credentials](/guides/authentication).

## Steps

<Steps>
  <Step title="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`).

    ```bash theme={"theme":"tokyo-night"}
    curl --request POST \
      --url https://api.sandbox.tracefinance.com/v1/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.
  </Step>

  <Step title="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.

    ```bash theme={"theme":"tokyo-night"}
    curl --request POST \
      --url https://api.sandbox.tracefinance.com/v1/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.
  </Step>

  <Step title="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 /v1/operations/{operationId}` if you need to surface it in your UI.

    ```bash theme={"theme":"tokyo-night"}
    curl --request GET \
      --url https://api.sandbox.tracefinance.com/v1/operations/<operation-id> \
      --header 'Authorization: Bearer <token>'
    ```
  </Step>
</Steps>

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

## What happens next

* [Make a withdrawal](/journeys/withdrawal) — send the converted funds out of the account.