Create a swap

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/swaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "quoteId": "e5f6a7b8-c9d0-1234-efab-3456789012cd"
}
'

import requests

url = "https://api.sandbox.tracefinance.com/v1/operations/swaps"

payload = {
    "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "quoteId": "e5f6a7b8-c9d0-1234-efab-3456789012cd"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    quoteId: 'e5f6a7b8-c9d0-1234-efab-3456789012cd'
  })
};

fetch('https://api.sandbox.tracefinance.com/v1/operations/swaps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.tracefinance.com/v1/operations/swaps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountId' => 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    'quoteId' => 'e5f6a7b8-c9d0-1234-efab-3456789012cd'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.tracefinance.com/v1/operations/swaps"

	payload := strings.NewReader("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"e5f6a7b8-c9d0-1234-efab-3456789012cd\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.tracefinance.com/v1/operations/swaps")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"e5f6a7b8-c9d0-1234-efab-3456789012cd\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.tracefinance.com/v1/operations/swaps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"e5f6a7b8-c9d0-1234-efab-3456789012cd\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "2a4b9d9e-3f2b-5c4b-ae3f-8d2b5c4bae3f",
  "customer": {
    "id": "11111111-1111-1111-1111-111111111111"
  },
  "account": {
    "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "owner": "Acme Importação Ltda"
  },
  "sourceAmount": {
    "value": "5000.00",
    "asset": "BRL",
    "decimals": 2
  },
  "targetAmount": {
    "value": "1000.000000",
    "asset": "USDT",
    "decimals": 6
  },
  "fees": [],
  "transactions": [],
  "tags": [
    {
      "key": "psp",
      "value": "Amazon"
    },
    {
      "key": "compliance-tier",
      "value": "high"
    }
  ],
  "currentState": {
    "status": "REQUESTED",
    "createdAt": "2026-04-27T14:12:33Z"
  },
  "intent": {
    "type": "SWAP"
  },
  "quote": {
    "id": "e5f6a7b8-c9d0-1234-efab-3456789012cd",
    "effectiveRate": {
      "value": "0.20",
      "base": "BRL",
      "quote": "USDT"
    },
    "expiresAt": "2026-04-27T14:13:03Z"
  },
  "createdAt": "2026-04-27T14:12:33Z",
  "updatedAt": "2026-04-27T14:12:33Z"
}

POST

operations

swaps

Create a swap

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/operations/swaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "quoteId": "e5f6a7b8-c9d0-1234-efab-3456789012cd"
}
'

import requests

url = "https://api.sandbox.tracefinance.com/v1/operations/swaps"

payload = {
    "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "quoteId": "e5f6a7b8-c9d0-1234-efab-3456789012cd"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    quoteId: 'e5f6a7b8-c9d0-1234-efab-3456789012cd'
  })
};

fetch('https://api.sandbox.tracefinance.com/v1/operations/swaps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.tracefinance.com/v1/operations/swaps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountId' => 'a1b2c3d4-5e6f-7890-abcd-ef1234567890',
    'quoteId' => 'e5f6a7b8-c9d0-1234-efab-3456789012cd'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.tracefinance.com/v1/operations/swaps"

	payload := strings.NewReader("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"e5f6a7b8-c9d0-1234-efab-3456789012cd\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.tracefinance.com/v1/operations/swaps")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"e5f6a7b8-c9d0-1234-efab-3456789012cd\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.tracefinance.com/v1/operations/swaps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountId\": \"a1b2c3d4-5e6f-7890-abcd-ef1234567890\",\n  \"quoteId\": \"e5f6a7b8-c9d0-1234-efab-3456789012cd\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "2a4b9d9e-3f2b-5c4b-ae3f-8d2b5c4bae3f",
  "customer": {
    "id": "11111111-1111-1111-1111-111111111111"
  },
  "account": {
    "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "owner": "Acme Importação Ltda"
  },
  "sourceAmount": {
    "value": "5000.00",
    "asset": "BRL",
    "decimals": 2
  },
  "targetAmount": {
    "value": "1000.000000",
    "asset": "USDT",
    "decimals": 6
  },
  "fees": [],
  "transactions": [],
  "tags": [
    {
      "key": "psp",
      "value": "Amazon"
    },
    {
      "key": "compliance-tier",
      "value": "high"
    }
  ],
  "currentState": {
    "status": "REQUESTED",
    "createdAt": "2026-04-27T14:12:33Z"
  },
  "intent": {
    "type": "SWAP"
  },
  "quote": {
    "id": "e5f6a7b8-c9d0-1234-efab-3456789012cd",
    "effectiveRate": {
      "value": "0.20",
      "base": "BRL",
      "quote": "USDT"
    },
    "expiresAt": "2026-04-27T14:13:03Z"
  },
  "createdAt": "2026-04-27T14:12:33Z",
  "updatedAt": "2026-04-27T14:12:33Z"
}

Authorizations

Authorization

string

header

required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Headers

X-Idempotency-Key

string<uuid>

required

Unique key to ensure idempotent request processing. Required on all POST, PUT, and PATCH requests.

X-Trace-Version

string

API version. Omit to use the default version.

Example:

"1"

Body

application/json

Every swap references a quote previously obtained from POST /v1/quotes. The quote determines sourceAmount and targetAmount (including their assets) and locks the FX rate. A quote can be consumed by at most one operation.

accountId

string<uuid>

required

Account that holds the source funds. Must match the account on the referenced quote.

Example:

"a1b2c3d4-5e6f-7890-abcd-ef1234567890"

quoteId

string<uuid>

required

ID of a quote returned by POST /v1/quotes. Must belong to the same customer, must not have expired, and must not have been consumed by another operation.

Example:

"e5f6a7b8-c9d0-1234-efab-3456789012cd"

Response

Swap accepted. The operation is in REQUESTED status.

A created operation. Withdrawals, swaps, deposits, and transfers share this shape; intent.type identifies which. quote is present for withdrawals, swaps, and transfers (transfers take no quoteId and get a 1:1 quote generated internally); it is null for deposits created without a prior quote.

string<uuid>

required

read-only

customer

object

required

Reference to the customer that owns the operation.

Show child attributes

account

object

required

Reference to a customer account, including the registered owner name.

Show child attributes

sourceAmount

object

required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (BigDecimal, Decimal) for arithmetic — never JavaScript Number. Request bodies use the scalar AmountValue instead.

Show child attributes

targetAmount

object

required

Show child attributes

intent

Withdrawal · object

required

Operation intent. Discriminated by type.

Withdrawal
Swap
Deposit
Transfer

Show child attributes

quote

object | null

required

Consumed quote. null for deposits created without a prior quote; present for all other operations.

Show child attributes

fees

object[]

required

Show child attributes

transactions

object[]

required

Rail-level transactions for the operation. Only confirmed transactions are included; pending or failed rail movements are omitted.

Show child attributes

requirements

object

required

What compliance is waiting on for this operation, read live at request time. All four groups are empty for an operation that never went through a compliance review. An operation in ACTION_REQUIRED is waiting on whatever is in currentlyDue and errors.

Show child attributes

Example:

{
  "currentlyDue": [
    {
      "type": "BENEFICIARY_DOCUMENT",
      "documentType": "CUSTODY_ATTESTATION",
      "anyOf": ["CUSTODY_ATTESTATION"]
    }
  ],
  "pendingVerification": [],
  "errors": [],
  "satisfied": []
}

currentState

object

required

The operation's current state. Carries a status, optional reason, and the time the state was entered.

Show child attributes

createdAt

string<date-time>

required

read-only

updatedAt

string<date-time>

required

read-only

Accounts

Operations

Reports

Quotes

Beneficiaries

Webhooks

Create a swap

Authorizations

Headers

Body

Response