> ## 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. # Create a swap > Converts funds between assets within a multi-currency account using a locked quote. ## OpenAPI ````yaml apis/fx-payment/openapi.yml POST /v1/operations/swap openapi: 3.1.1 info: title: Trace Finance Payments API version: 1.0.0 description: > API for deposits, withdrawals, swaps, and beneficiary management on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Operations description: >- Create deposits, withdrawals, and swaps. Query operation status and history. - name: Reports description: Generate aggregated views of operations across a time window. - name: Beneficiaries description: >- Manage external beneficiaries and their payment instructions for withdrawals. - name: Payment instructions description: Add or remove payment instructions on an existing beneficiary. paths: /v1/operations/swap: post: tags: - Operations summary: Create a swap description: > Creates a swap that converts funds between assets within the customer's multi-currency account. The referenced quote determines the source and target assets, amounts, and the FX rate. Returns `201` immediately with the operation in `REQUESTED` status; settlement happens asynchronously. operationId: createSwap parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/TraceVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSwapRequest' examples: brlToUsdt: summary: BRL → USDT swap value: accountId: a1b2c3d4-5e6f-7890-abcd-ef1234567890 quoteId: e5f6a7b8-c9d0-1234-efab-3456789012cd responses: '201': description: Swap accepted. The operation is in `REQUESTED` status. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/OperationResponse' examples: brlToUsdtSwap: summary: BRL → USDT swap in REQUESTED state value: 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.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' consumedAt: null createdAt: '2026-04-27T14:12:33Z' updatedAt: '2026-04-27T14:12:33Z' '400': description: 'Validation error: missing or malformed fields.' headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAccountId: $ref: '#/components/examples/MissingAccountId' invalidAccountUuid: summary: accountId is not a UUID value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_UUID message: '''not-a-uuid'' is not a valid UUID' field: body:accountId params: {} missingQuoteId: summary: quoteId is missing value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: REQUIRED message: Parameter 'body:quoteId' not found in request field: body:quoteId params: {} '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Account or quote not found for this customer. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: accountNotFound: $ref: '#/components/examples/AccountNotFound' quoteNotFound: $ref: '#/components/examples/QuoteNotFound' '409': description: Idempotency key was reused with a different request body. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotencyConflict: $ref: '#/components/examples/IdempotencyConflict' '422': description: Business rule violation. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: quoteExpired: $ref: '#/components/examples/QuoteExpired' quoteAlreadyConsumed: $ref: '#/components/examples/QuoteAlreadyConsumed' components: parameters: IdempotencyKey: name: X-Idempotency-Key in: header required: true description: >- Unique key to ensure idempotent request processing. Required on all `POST`, `PUT`, and `PATCH` requests. schema: type: string format: uuid TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' schemas: CreateSwapRequest: type: object description: > 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. properties: accountId: type: string format: uuid description: >- Account that holds the source funds. Must match the account on the referenced quote. example: a1b2c3d4-5e6f-7890-abcd-ef1234567890 quoteId: type: string format: uuid description: > 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 required: - accountId - quoteId OperationResponse: type: object description: > 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. properties: id: type: string format: uuid readOnly: true customerId: type: string format: uuid account: $ref: '#/components/schemas/AccountReference' sourceAmount: $ref: '#/components/schemas/AmountResponse' targetAmount: $ref: '#/components/schemas/AmountResponse' intent: $ref: '#/components/schemas/OperationIntent' quote: $ref: '#/components/schemas/OperationQuoteReference' fees: type: array items: $ref: '#/components/schemas/OperationFee' transactions: type: array items: $ref: '#/components/schemas/OperationTransaction' tags: type: array description: > System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags. items: $ref: '#/components/schemas/TagResponse' example: - key: psp value: Amazon - key: compliance-tier value: high currentState: $ref: '#/components/schemas/OperationState' createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true required: - id - customerId - account - sourceAmount - targetAmount - intent - quote - fees - transactions - currentState - createdAt - updatedAt ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message AccountReference: type: object description: Reference to a customer account, including the registered owner name. properties: id: type: string format: uuid description: Account identifier. example: a1b2c3d4-5e6f-7890-abcd-ef1234567890 owner: type: string description: Registered owner name on the account. example: Acme Importação Ltda required: - id - owner AmountResponse: type: object description: > 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. properties: value: type: string pattern: ^-?\d+(\.\d+)?$ description: Decimal amount in the asset's canonical scale. example: '500.00' asset: $ref: '#/components/schemas/Asset' decimals: type: integer description: Number of decimal places for the asset. example: 2 required: - value - asset - decimals OperationIntent: description: Operation intent. Discriminated by `type`. oneOf: - $ref: '#/components/schemas/OperationWithdrawalIntent' - $ref: '#/components/schemas/OperationSwapIntent' - $ref: '#/components/schemas/OperationDepositIntent' - $ref: '#/components/schemas/OperationTransferIntent' discriminator: propertyName: type mapping: WITHDRAWAL: $ref: '#/components/schemas/OperationWithdrawalIntent' SWAP: $ref: '#/components/schemas/OperationSwapIntent' DEPOSIT: $ref: '#/components/schemas/OperationDepositIntent' TRANSFER: $ref: '#/components/schemas/OperationTransferIntent' OperationQuoteReference: type: object description: Reference to the quote consumed by the operation. properties: id: type: string format: uuid description: Quote identifier. effectiveRate: $ref: '#/components/schemas/Rate' expiresAt: type: string format: date-time description: Time at which the quote was originally set to expire. consumedAt: oneOf: - type: string format: date-time - type: 'null' description: >- Time the quote was consumed by this operation. `null` until the operation reaches a state that locks the rate. required: - id - effectiveRate - expiresAt - consumedAt OperationFee: type: object description: A fee charged on the operation. properties: amount: $ref: '#/components/schemas/AmountResponse' source: type: string enum: - FX_SPREAD - PLATFORM - RAIL - CUSTOMER description: >- Where the fee originates. `PLATFORM` is charged by Trace Finance, `RAIL` by the underlying banking rail (PIX, TED, wire), `CUSTOMER` is a passthrough markup added by the customer. createdAt: type: string format: date-time description: Time the fee was applied. required: - amount - source - createdAt OperationTransaction: type: object description: A rail-level transaction associated with the operation. properties: id: type: string description: Rail-side transaction identifier. direction: type: string enum: - CREDIT - DEBIT description: Whether the rail debited or credited the account. amount: $ref: '#/components/schemas/AmountResponse' status: type: string enum: - PROCESSING - CONFIRMED - FAILED description: >- Rail-level status. Independent of the parent operation's `currentState`. required: - id - direction - amount - status TagResponse: type: object description: > A label attached to a resource. Tags are system-managed — Trace Finance assigns them based on routing, compliance, and operational criteria. Clients cannot create, modify, or remove tags via the API. properties: key: type: - string - 'null' description: > Category for keyed tags (e.g., `psp`, `compliance-tier`). `null` for single-value labels. example: psp value: type: string description: > For keyed tags, the right-hand side of the label. For single-value labels, the entire tag. example: Amazon required: - value OperationState: type: object description: >- The operation's current state. Carries a status, optional reason, and the time the state was entered. properties: status: $ref: '#/components/schemas/OperationStatus' reason: $ref: '#/components/schemas/Reason' description: >- Justification for entering this status. Present for `FAILED`; omitted otherwise. createdAt: type: string format: date-time description: Time the operation entered this status. required: - status - createdAt Asset: type: string enum: - BRL - USDT - USDC description: > ISO 4217 currency code or stablecoin ticker. The maximum decimal scale of an `AmountValue` paired with this asset depends on the asset: | Asset | Decimals | |---|---| | BRL | 2 | | USDT | 6 | | USDC | 6 | example: BRL OperationWithdrawalIntent: title: Withdrawal type: object properties: type: type: string enum: - WITHDRAWAL beneficiary: $ref: '#/components/schemas/OperationBeneficiaryReference' required: - type - beneficiary OperationSwapIntent: title: Swap type: object description: > Intent for a swap. Carries only the type discriminator — source and target assets, amounts, account, and quote all live at the operation root. properties: type: type: string enum: - SWAP required: - type OperationDepositIntent: title: Deposit type: object description: > Intent for a deposit. Carries the funding instruction the customer should use to send money in — currently a PIX dynamic QR code. properties: type: type: string enum: - DEPOSIT fundingInstruction: $ref: '#/components/schemas/DepositOperationFundingInstruction' expiresAt: type: string format: date-time description: > When the deposit expires. After this instant the funding instruction can no longer be paid and the operation will not complete. Mirrors the funding instruction's expiry for `PIX_DYNAMIC_QR_CODE`. example: '2026-04-28T15:08:21Z' required: - type - fundingInstruction - expiresAt OperationTransferIntent: title: Transfer type: object description: > Intent for a transfer. Carries a snapshot of the target account at the time the operation was created. properties: type: type: string enum: - TRANSFER targetAccount: $ref: '#/components/schemas/AccountReference' required: - type - targetAccount Rate: type: object description: Exchange rate between two currencies. properties: value: type: string description: Rate value as a decimal string. example: '5.25' base: type: string description: Base currency. example: USDT quote: type: string description: Quote currency. example: BRL required: - value - base - quote OperationStatus: type: string description: Lifecycle status of an operation. enum: - REQUESTED - PROCESSING - CUSTOMER_ACTION_REQUIRED - COMPLETED - FAILED Reason: type: object description: >- Machine- and human-readable explanation. Returned inside an `OperationState` entry when a status transition requires justification (e.g., `FAILED`). properties: code: type: string description: Machine-readable code. example: INSUFFICIENT_BALANCE message: type: string description: Human-readable description. example: Insufficient balance for the requested operation details: type: object additionalProperties: true description: Free-form context relevant to the reason. required: - code - message - details OperationBeneficiaryReference: type: object description: Snapshot of the beneficiary at the time the operation was created. properties: id: oneOf: - type: string format: uuid - type: 'null' description: ID of the saved beneficiary. entity: $ref: '#/components/schemas/OperationEntityReference' paymentInstruction: $ref: '#/components/schemas/OperationPaymentInstruction' required: - id - entity - paymentInstruction DepositOperationFundingInstruction: description: > Funding instruction the customer uses to send money in. Discriminated by `rail`. Only `PIX_DYNAMIC_QR_CODE` is available for deposits at the moment. oneOf: - $ref: '#/components/schemas/OperationPixDynamicQrCodeFunding' discriminator: propertyName: rail mapping: PIX_DYNAMIC_QR_CODE: $ref: '#/components/schemas/OperationPixDynamicQrCodeFunding' OperationEntityReference: description: Entity snapshot. Discriminated by `type`. oneOf: - $ref: '#/components/schemas/OperationEntityIndividual' - $ref: '#/components/schemas/OperationEntityCompany' discriminator: propertyName: type mapping: INDIVIDUAL: $ref: '#/components/schemas/OperationEntityIndividual' COMPANY: $ref: '#/components/schemas/OperationEntityCompany' OperationPaymentInstruction: description: >- Snapshot of the payment instruction the funds are routed to. Discriminated by `rail`. oneOf: - $ref: '#/components/schemas/OperationPixKeyInstruction' - $ref: '#/components/schemas/OperationPixStaticQrCodeInstruction' - $ref: '#/components/schemas/OperationTedInstruction' - $ref: '#/components/schemas/OperationBoletoInstruction' - $ref: '#/components/schemas/OperationCryptoWalletInstruction' discriminator: propertyName: rail mapping: PIX_KEY: $ref: '#/components/schemas/OperationPixKeyInstruction' PIX_STATIC_QR_CODE: $ref: '#/components/schemas/OperationPixStaticQrCodeInstruction' TED: $ref: '#/components/schemas/OperationTedInstruction' BOLETO: $ref: '#/components/schemas/OperationBoletoInstruction' CRYPTO: $ref: '#/components/schemas/OperationCryptoWalletInstruction' OperationPixDynamicQrCodeFunding: title: PIX dynamic QR code type: object properties: rail: type: string enum: - PIX_DYNAMIC_QR_CODE qrCode: type: string description: >- PIX dynamic QR code payload (EMV-encoded BR Code) for the payer to scan or copy. expiresAt: type: string format: date-time description: >- When the dynamic QR code expires. After this instant the payer can no longer pay it. example: '2026-04-28T15:08:21Z' required: - rail - qrCode - expiresAt OperationEntityIndividual: title: Individual type: object properties: type: type: string enum: - INDIVIDUAL firstName: type: string lastName: type: string taxId: $ref: '#/components/schemas/TaxIdResponse' birthDate: type: string format: date address: $ref: '#/components/schemas/Address' required: - type - firstName - lastName - taxId - birthDate - address OperationEntityCompany: title: Company type: object properties: type: type: string enum: - COMPANY legalName: type: string description: Registered legal name. tradeName: oneOf: - type: string - type: 'null' description: Trade name (DBA). `null` if the company doesn't use one. taxId: $ref: '#/components/schemas/TaxIdResponse' address: $ref: '#/components/schemas/Address' required: - type - legalName - tradeName - taxId - address OperationPixKeyInstruction: title: PIX key type: object properties: id: type: string format: uuid description: Payment instruction identifier. rail: type: string enum: - PIX_KEY keyType: $ref: '#/components/schemas/PixKeyType' key: type: string description: PIX key value, formatted per `keyType`. required: - id - rail - keyType - key OperationPixStaticQrCodeInstruction: title: PIX static QR code type: object properties: id: type: string format: uuid description: Payment instruction identifier. rail: type: string enum: - PIX_STATIC_QR_CODE qrCode: type: string description: PIX QR code payload (EMV-encoded BR Code). required: - id - rail - qrCode OperationTedInstruction: title: TED type: object properties: id: type: string format: uuid description: Payment instruction identifier. rail: type: string enum: - TED bankCode: type: string description: ISPB or COMPE bank code. branch: type: string description: Branch number. accountNumber: type: string description: Account number with check digit. accountType: type: string enum: - CHECKING - SAVINGS required: - id - rail - bankCode - branch - accountNumber - accountType OperationBoletoInstruction: title: Boleto type: object properties: id: type: string format: uuid description: Payment instruction identifier. rail: type: string enum: - BOLETO barcode: type: string description: Boleto barcode (digitable line). dueDate: type: string format: date description: Last day on which the boleto can be paid. required: - id - rail - barcode - dueDate OperationCryptoWalletInstruction: title: Crypto wallet type: object properties: id: type: string format: uuid description: Payment instruction identifier. rail: type: string enum: - CRYPTO network: type: string description: Blockchain network (e.g., `ETHEREUM`, `TRON`, `SOLANA`). walletAddress: type: string description: Wallet address on `network`. required: - id - rail - network - walletAddress TaxIdResponse: type: object description: Tax identifier returned for a beneficiary entity. properties: value: type: string example: '52998224725' type: $ref: '#/components/schemas/TaxIdType' required: - value - type Address: type: object description: Postal address of an entity or beneficiary. properties: addressLine1: type: string description: Primary street line (number + street). addressLine2: oneOf: - type: string - type: 'null' description: >- Secondary line (apartment, suite, building). `null` if not applicable. city: type: string state: oneOf: - type: string - type: 'null' description: >- State, province, or region. `null` for countries without subdivisions in the address. country: $ref: '#/components/schemas/Country' postalCode: type: string description: Postal or ZIP code, formatted per the country's convention. required: - addressLine1 - addressLine2 - city - state - country - postalCode PixKeyType: type: string enum: - CPF - CNPJ - EMAIL - PHONE - EVP description: PIX key category. EVP is a random key issued by the central bank. TaxIdType: type: string description: > Country-specific tax identifier type. The type itself implies the country (`CPF`/`CNPJ` are Brazilian, `CUIT`/`CUIL` are Argentine, `RUT_CL` is Chilean, etc.). enum: - CPF - CNPJ - CUIT - CUIL - RUT_CL - RUT_UY - CI_UY - RUC - DNI_PE - NIT - CC - RFC - RUC_PY - CI_PY - NIPC - NIF_PT - CIF - NIF_ES - NIE - SIREN - SIRET - NIF_FR - PARTITA_IVA - CODICE_FISCALE - UST_IDNR - STEUER_ID - KVK - BSN - BCE - NN_BE - ORGANISATIONSNUMMER - PERSONNUMMER - ORGANISASJONSNUMMER - FODSELSNUMMER - UID_CH - AHV - VAT_GB - NIN - EIN - SSN - ITIN - BN_CA - SIN - ABN - TFN - USCC - CORPORATE_NUMBER_JP - MY_NUMBER - BRN_KR - RRN - GSTIN - PAN - INN_RU - COMPANY_NUMBER_IL - TEUDAT_ZEHUT - TRADE_LICENSE - EMIRATES_ID - CIPC - SA_ID example: CPF Country: type: string description: ISO 3166-1 alpha-2 country code. example: BR enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CD - CG - CK - CR - HR - CU - CW - CY - CZ - CI - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - MK - RO - RU - RW - RE - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - AX headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid examples: MissingAccountId: summary: accountId is missing from the request body value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: REQUIRED message: Parameter 'body:accountId' not found in request field: body:accountId params: {} AccountNotFound: summary: Account does not exist or is not owned by the authenticated customer value: code: RESOURCE_NOT_FOUND message: >- Account with given parameters [id:a1b2c3d4-5e6f-7890-abcd-ef1234567890] not found details: resource: Account parameters: id: a1b2c3d4-5e6f-7890-abcd-ef1234567890 QuoteNotFound: summary: Quote does not exist for this customer value: code: RESOURCE_NOT_FOUND message: >- Quote with given parameters [id:d4e5f6a7-b8c9-0123-defa-2345678901bc] not found details: resource: Quote parameters: id: d4e5f6a7-b8c9-0123-defa-2345678901bc IdempotencyConflict: summary: X-Idempotency-Key was reused with a different request body value: code: IDEMPOTENCY_CONFLICT message: Idempotency key already used with a different request details: {} QuoteExpired: summary: Quote expired before the operation was created value: code: QUOTE_EXPIRED message: Quote has expired and can no longer be consumed details: quoteId: d4e5f6a7-b8c9-0123-defa-2345678901bc expiredAt: '2026-04-25T02:34:17Z' QuoteAlreadyConsumed: summary: Quote was already consumed by another operation (1:1 binding) value: code: QUOTE_ALREADY_CONSUMED message: Quote has already been consumed by another operation details: quoteId: d4e5f6a7-b8c9-0123-defa-2345678901bc consumedByOperationId: 1f3a8c8d-2e1a-4b3a-9d2e-7c1a4b3a9d2e InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````