> ## 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 quote > Locks an FX rate for a short window. Required by every operation creation endpoint. ## OpenAPI ````yaml apis/fx-payment/openapi.yml POST /v1/quotes 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/quotes: post: tags: - Operations summary: Create a quote description: > Creates a quote that locks an FX rate for a short window. The withdrawal, swap, and deposit operation endpoints require a `quoteId` — see the request body of `POST /v1/operations/withdrawal`, `POST /v1/operations/swap`, or `POST /v1/operations/deposit`. Same-asset quotes (`sourceAsset == targetAsset`) are valid and return a 1:1 spot with zero spread, so callers can use the same flow for fiat and FX. A quote is bound 1:1 to an operation: once consumed, it cannot be reused. Quotes also expire after a short window (see `expiresAt` in the response). operationId: createQuote parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/TraceVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateQuoteRequest' examples: fixedSourceCrossAsset: summary: BRL → USDT, fixing the source amount value: accountId: a1b2c3d4-5e6f-7890-abcd-ef1234567890 sourceAsset: BRL targetAsset: USDT sourceAmount: '500.00' fixedTargetCrossAsset: summary: BRL → USDT, fixing the target amount value: accountId: a1b2c3d4-5e6f-7890-abcd-ef1234567890 sourceAsset: BRL targetAsset: USDT targetAmount: '100.000000' sameAssetBrl: summary: BRL → BRL (1:1, no spread) value: accountId: a1b2c3d4-5e6f-7890-abcd-ef1234567890 sourceAsset: BRL targetAsset: BRL sourceAmount: '500.00' responses: '201': description: Quote created. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/QuoteResponse' examples: crossAsset: summary: BRL → USDT cross-asset quote value: id: d4e5f6a7-b8c9-0123-defa-2345678901bc 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: '100.000000' asset: USDT decimals: 6 effectiveRate: value: '0.20' base: BRL quote: USDT expiresAt: '2026-04-25T02:39:47Z' sameAsset: summary: BRL → BRL same-asset quote (1:1, no spread) value: id: e5f6a7b8-c9d0-1234-efab-3456789012cd 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 effectiveRate: value: '1.00' base: BRL quote: BRL expiresAt: '2026-04-25T02:39:47Z' '400': description: Validation error. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAssets: summary: sourceAsset and targetAsset are required value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: REQUIRED message: Parameter 'body:sourceAsset' not found in request field: body:sourceAsset params: {} missingAmount: summary: Neither sourceAmount nor targetAmount provided value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: MISSING_AMOUNT message: Provide exactly one of sourceAmount or targetAmount field: body params: {} mutuallyExclusiveAmounts: summary: Both sourceAmount and targetAmount were provided value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: MUTUALLY_EXCLUSIVE_AMOUNTS message: >- Provide exactly one of sourceAmount or targetAmount, not both field: body params: {} amountMustBePositive: summary: Amount must be greater than zero value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: AMOUNT_MUST_BE_POSITIVE message: sourceAmount must be greater than zero field: body:sourceAmount params: {} invalidAmountPrecision: summary: Decimal scale exceeds the asset's allowed precision value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_AMOUNT_PRECISION message: BRL allows at most 2 decimal places, got 4 field: body:sourceAmount params: asset: BRL allowed: 2 received: 4 '401': $ref: '#/components/responses/UnauthorizedError' '422': description: >- Quote could not be created (no rate available, asset pair unsupported, etc.). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: quoteCreationFailed: summary: No rate available for the requested asset pair value: code: QUOTE_CREATION_FAILED message: Failed to create quote details: sourceAsset: BRL targetAsset: USDT reason: No rate available for the requested currency pair 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: CreateQuoteRequest: type: object description: > Quotes lock an FX rate (or a 1:1 spot for same-asset) for a short window and are required by every operation creation endpoint. A quote is bound to a specific account and can be consumed by exactly one operation on that account. Provide exactly one of `sourceAmount` or `targetAmount`: - `sourceAmount` — fix the amount you'll spend; the target side is computed. - `targetAmount` — fix the amount the beneficiary receives; the source side is computed. Same-asset quotes (`sourceAsset == targetAsset`) are valid and return a 1:1 spot with zero spread. properties: accountId: type: string format: uuid description: >- Account the quote is bound to. The consuming operation must reference the same account. example: a1b2c3d4-5e6f-7890-abcd-ef1234567890 sourceAsset: $ref: '#/components/schemas/Asset' targetAsset: $ref: '#/components/schemas/Asset' sourceAmount: $ref: '#/components/schemas/AmountValue' targetAmount: $ref: '#/components/schemas/AmountValue' required: - accountId - sourceAsset - targetAsset QuoteResponse: type: object description: >- A quote that can be consumed by an operation. Expires after a short window. 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' effectiveRate: $ref: '#/components/schemas/Rate' expiresAt: type: string format: date-time description: >- Time at which the quote expires. Operations referencing the quote after this fail with `QUOTE_EXPIRED`. required: - id - customerId - account - sourceAmount - targetAmount - effectiveRate - expiresAt 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 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 AmountValue: type: string pattern: ^-?\d+(\.\d+)?$ description: > Decimal monetary amount in the associated asset. The number of fractional digits must not exceed the asset's precision — see `Asset` for the per-asset table. Exceeding the precision fails with `INVALID_AMOUNT_PRECISION`. example: '500.00' 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 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 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 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. ````