> ## 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. # List operations > Lists all operations for the authenticated customer. ## OpenAPI ````yaml apis/fx-payment/openapi.yml GET /v1/operations 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: get: tags: - Operations summary: List operations description: > Lists all operations for the authenticated customer. Use the `filters` query parameter to narrow by status, intent type, asset, or other fields — see the [Filtering](/guides/principles/filtering) guide. operationId: listOperations parameters: - $ref: '#/components/parameters/TraceVersion' - $ref: '#/components/parameters/PaginationLimit' - $ref: '#/components/parameters/PaginationCursor' - $ref: '#/components/parameters/PaginationDirection' - $ref: '#/components/parameters/PaginationSortOrder' - $ref: '#/components/parameters/Filters' responses: '200': description: Paginated list of operations. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/OperationList' '401': $ref: '#/components/responses/UnauthorizedError' '422': description: Invalid filter parameter. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidIntentType: summary: intentType filter is not a valid enum value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_ENUM message: '''TRANSFER'' is not a valid enum' field: query:intentType params: {} invalidStatus: summary: status filter is not a valid enum value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_ENUM message: '''DONE'' is not a valid enum' field: query:status params: {} components: parameters: TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' PaginationLimit: name: limit in: query required: false description: Maximum number of items to return. Defaults to 10. schema: type: integer default: 10 minimum: 1 maximum: 100 PaginationCursor: name: cursor in: query required: false description: Opaque cursor for fetching the next or previous page. schema: type: string PaginationDirection: name: direction in: query required: false description: Direction of pagination relative to the cursor. schema: type: string enum: - NEXT - PREVIOUS PaginationSortOrder: name: sortOrder in: query required: false description: Sort order for results. Defaults to DESCENDING. schema: type: string enum: - ASCENDING - DESCENDING default: DESCENDING Filters: name: filters in: query required: false description: > Filter expression using LHS Brackets syntax (`field[operator]=value`). Combine multiple conditions with `and(...)`, `or(...)`, or `;` (implicit AND). See the [Filtering](/guides/principles/filtering) guide for the full operator catalog. schema: type: string example: intent.type[eq]=WITHDRAWAL;currentState.status[eq]=COMPLETED 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 schemas: OperationList: type: object properties: data: type: array items: $ref: '#/components/schemas/OperationResponse' meta: $ref: '#/components/schemas/PageMetadata' required: - data - meta 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 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 PageMetadata: type: object description: Cursor-based pagination metadata. properties: previousCursor: type: - string - 'null' description: Cursor for the previous page. `null` on the first page. nextCursor: type: - string - 'null' description: Cursor for the next page. `null` on the last page. total: type: integer description: Number of items in the current page. required: - previousCursor - nextCursor - total 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 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' examples: 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: {} 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. ````