Skip to main content
POST
/
api
/
operations
/
swap
Create a swap
curl --request POST \
  --url https://api.sandbox.tracefinance.com/api/operations/swap \
  --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"
}
'
{ "id": "2a4b9d9e-3f2b-5c4b-ae3f-8d2b5c4bae3f", "customerId": "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.00", "asset": "USD", "decimals": 2 }, "fees": [], "transactions": [], "tags": [ { "key": "psp", "value": "Amazon" }, { "key": "compliance-tier", "value": "high" } ], "currentState": { "status": "REQUESTED", "createdAt": "2026-04-27T14:12:33Z" }, "states": [ { "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": "USD" }, "expiresAt": "2026-04-27T14:13:03Z", "consumedAt": null }, "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 /api/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 /api/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. The quote field is always present — transfers take no quoteId and get a 1:1 quote generated internally.

​
id
string<uuid>
required
read-only
​
customerId
string<uuid>
required
​
account
object
required

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

​
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.

​
targetAmount
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.

​
intent
Withdrawal · object
required

Operation intent. Discriminated by type.

​
quote
object
required

Reference to the quote consumed by the operation.

​
fees
object[]
required
​
transactions
object[]
required
​
currentState
object
required

A single entry in an operation's state history. Carries a status, optional reason, and the time the state was entered.

​
states
object[]
required

Full state history of the operation, oldest first. The last entry equals currentState.

​
createdAt
string<date-time>
required
read-only
​
updatedAt
string<date-time>
required
read-only
​
tags
object[]

System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags.

Example:
[
  { "key": "psp", "value": "Amazon" },
  { "key": "compliance-tier", "value": "high" }
]