Skip to main content
POST
/
api
/
operations
/
transfer
Create a transfer
curl --request POST \
  --url https://api.sandbox.tracefinance.com/api/operations/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "sourceAccountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "targetAccountId": "b2c3d4e5-6f70-8901-bcde-f12345678901",
  "amount": {
    "value": "500.00",
    "asset": "BRL"
  }
}
'
{ "id": "4c6d1f10-5b4d-7e6d-cf5b-ae4d7e6dcf5b", "customerId": "11111111-1111-1111-1111-111111111111", "account": { "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "owner": "Acme Importação Ltda" }, "sourceAmount": { "value": "500.00", "asset": "BRL", "decimals": 2 }, "targetAmount": { "value": "500.00", "asset": "BRL", "decimals": 2 }, "fees": [], "transactions": [], "tags": [ { "key": "psp", "value": "Amazon" }, { "key": "compliance-tier", "value": "high" } ], "currentState": { "status": "REQUESTED", "createdAt": "2026-05-06T16:24:11Z" }, "states": [ { "status": "REQUESTED", "createdAt": "2026-05-06T16:24:11Z" } ], "intent": { "type": "TRANSFER", "targetAccount": { "id": "b2c3d4e5-6f70-8901-bcde-f12345678901", "owner": "Acme Importação Ltda" } }, "quote": { "id": "d4e5f6a7-b8c9-0123-defa-2345678901bc", "effectiveRate": { "value": "1.00", "base": "BRL", "quote": "BRL" }, "expiresAt": "2026-05-06T16:24:41Z", "consumedAt": "2026-05-06T16:24:11Z" }, "createdAt": "2026-05-06T16:24:11Z", "updatedAt": "2026-05-06T16:24:11Z" }

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

Same-asset transfer between two accounts of the same customer. The asset on amount must be enabled on both accounts. No FX is performed — sourceAmount and targetAmount on the response are equal to amount. The system generates a 1:1 quote internally and returns it on quote; callers normally do not provide quoteId.

​
sourceAccountId
string<uuid>
required

Source account that will be debited.

Example:

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

​
targetAccountId
string<uuid>
required

Target account that will be credited. Must belong to the same customer as the source account, must be in ACTIVE status, and must have amount.asset enabled. Cannot equal sourceAccountId.

Example:

"b2c3d4e5-6f70-8901-bcde-f12345678901"

​
amount
object
required

Amount to move. The same value is debited from the source and credited to the target.

​
quoteId
string<uuid>

Optional. ID of a quote returned by POST /api/quotes. Reserved for future use; same-asset transfers do not require one and generate a 1:1 quote internally.

Example:

"d4e5f6a7-b8c9-0123-defa-2345678901bc"

Response

Transfer 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" }
]