Create a transfer

Moves funds between two accounts of the same customer using a locked quote.

POST /api/operations/transfer

Create a transfer

cURL

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"
  }
}
'

201

brlTransfer

{ "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.

Show child attributes

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

201

application/json

Transfer accepted. The operation is in REQUESTED status.

An operation. Withdrawals (POST /api/operations/withdrawal), swaps (POST /api/operations/swap), deposits (POST /api/operations/deposit), and transfers (POST /api/operations/transfer) share this shape, discriminated by intent.type. The quote field is always present; for transfers without an explicit quoteId in the request, the system generates a 1:1 same-asset quote.

id · string<uuid> · required · read-only

customerId · string<uuid> · required

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

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

intent · Withdrawal · object · required

Operation intent. Discriminated by type.

Withdrawal

Swap

Deposit

Transfer

Show child attributes

quote · object · required

Reference to the quote consumed by the operation.

Show child attributes

fees · object[] · required

Show child attributes

transactions · object[] · required

Show child attributes

currentState · object · required

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

Show child attributes

states · object[] · required

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

Show child attributes

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.

Show child attributes

Example:

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