> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a quote

> Create a currency conversion quote that locks an exchange rate before initiating a withdrawal.

<Warning>
  **Legacy endpoint.** This is part of the legacy withdrawal flow and will be deprecated. An upcoming **Transactions Intent API** will replace it. Avoid building new integrations against this endpoint — contact your Solutions Engineer for migration guidance.
</Warning>


## OpenAPI

````yaml products/retail-va/api-reference/retail-rtd.json POST /v1/users/{userId}/quotes
openapi: 3.1.0
info:
  title: User Interface API
  description: >-
    API endpoints that are secured with JWT for purposes of calling Meridian
    APIs from a custom user interface.
  version: 1.0.0
servers:
  - url: https://remittances.sandbox.api-us.meridianapps.dev:80
    description: sandbox
security: []
tags: []
externalDocs:
  url: /
paths:
  /v1/users/{userId}/quotes:
    post:
      tags:
        - Quotes
      summary: Create a Quote
      description: >-
        Creates a currency conversion quote for a user. The quote locks an
        exchange rate and returns a quote ID that can be used to execute a
        withdrawal before the quote expires.
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user the quote is created for
          schema:
            type: string
        - $ref: '#/components/parameters/MeridianApiKeyHeader'
        - $ref: '#/components/parameters/MeridianTimestampHeader'
        - $ref: '#/components/parameters/MeridianSignatureHeader'
      requestBody:
        description: Details of the quote to be created
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/com.meridianpay.remittances.api.dto.CreateQuoteRequest
        required: true
      responses:
        '201':
          description: Quote created successfully
          headers: {}
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.meridianpay.remittances.api.dto.QuoteResponse
        '400':
          description: The request body or parameters are invalid
          headers: {}
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.meridianpay.core.common.api.MeridianError
        '401':
          description: Invalid authentication token
          headers: {}
        '500':
          description: An internal error occurred
          headers: {}
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/com.meridianpay.core.common.api.MeridianError
      deprecated: true
components:
  parameters:
    MeridianApiKeyHeader:
      name: X-Meridian-Api-Key
      in: header
      required: true
      description: >-
        API key issued by Meridian during provisioning. See
        [Authentication](/products/retail-va/authentication).
      schema:
        type: string
      example: your-api-key
    MeridianTimestampHeader:
      name: X-Meridian-Timestamp
      in: header
      required: true
      description: >-
        Current time in milliseconds since the Unix epoch. Must be within 60
        seconds of the request. See
        [Authentication](/products/retail-va/authentication).
      schema:
        type: string
      example: '1749566400000'
    MeridianSignatureHeader:
      name: X-Meridian-Signature
      in: header
      required: true
      description: >-
        HMAC SHA-256 signature of the canonical request string, computed per
        request. See [Authentication](/products/retail-va/authentication) for
        how to construct it.
      schema:
        type: string
      example: <hmac-sha256-signature>
  schemas:
    com.meridianpay.remittances.api.dto.CreateQuoteRequest:
      type: object
      properties:
        amount:
          type: number
          description: Amount to convert, expressed in the source currency
          example: 50
          title: BigDecimal
        fromCurrency:
          type: string
          description: ISO 4217 currency code to convert from (for example, USD)
          example: USD
          title: String
        toCurrency:
          type: string
          description: ISO 4217 currency code to convert to (for example, PHP)
          example: PHP
          title: String
      required:
        - amount
        - fromCurrency
        - toCurrency
      title: CreateQuoteRequest
    com.meridianpay.remittances.api.dto.QuoteResponse:
      type: object
      properties:
        quote:
          $ref: '#/components/schemas/com.meridianpay.remittances.api.dto.QuoteDto'
      required:
        - quote
      title: QuoteResponse
    com.meridianpay.core.common.api.MeridianError:
      type: object
      description: >-
        Standard error response returned when a request cannot be completed.
        Includes a human-readable message and, for validation failures, a list
        of field-level errors.
      properties:
        errorCode:
          type:
            - 'null'
            - string
          description: Machine-readable error code identifying the failure, when available
          title: String
        hasValidationErrors:
          type: boolean
          description: Whether the error includes one or more field-level validation errors
          title: Boolean
        message:
          type: string
          description: Human-readable description of the error
          title: String
        validationErrors:
          type: array
          description: >-
            List of field-level validation errors, empty when the failure is not
            validation-related
          items:
            $ref: >-
              #/components/schemas/com.meridianpay.core.common.api.ValidationError
          title: Array_ValidationError
      required:
        - hasValidationErrors
        - message
        - validationErrors
      title: MeridianError
    com.meridianpay.remittances.api.dto.QuoteDto:
      type: object
      properties:
        id:
          type: string
          description: Meridian-generated unique identifier for the quote
          example: quote_01HT2P6W9PC2QV4W0Q63QMFJ44
          title: String
        userId:
          type: string
          description: ID of the user the quote belongs to
          example: usr_01HT2P6W9PC2QV4W0Q63QMFJ44
          title: String
        fromAmount:
          type: number
          description: Amount being converted, expressed in the source currency
          example: 50
          title: BigDecimal
        remainingBalance:
          type: number
          description: >-
            Remaining virtual account balance in the source currency after this
            quote is applied
          example: 150
          title: BigDecimal
        toAmount:
          type: number
          description: Resulting amount in the destination currency
          example: 2800
          title: BigDecimal
        exchangeRate:
          type: number
          description: Exchange rate applied to the conversion
          example: 56
          title: BigDecimal
        fromCurrency:
          $ref: >-
            #/components/schemas/com.meridianpay.core.common.model.MeridianCurrency
          description: ISO 4217 currency code being converted from
          example: USD
        toCurrency:
          $ref: >-
            #/components/schemas/com.meridianpay.core.common.model.MeridianCurrency
          description: ISO 4217 currency code being converted to
          example: PHP
        expiresAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the quote expires and can no longer be used
          example: '2026-06-10T14:30:00Z'
          title: Instant
      required:
        - id
        - userId
        - fromAmount
        - remainingBalance
        - toAmount
        - exchangeRate
        - fromCurrency
        - toCurrency
        - expiresAt
      title: QuoteDto
    com.meridianpay.core.common.api.ValidationError:
      description: >-
        A single validation error describing why a specific field or parameter
        was rejected. Resolves to one of the validation error types below.
      anyOf:
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.InvalidFormat
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.InvalidValue
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingPathParameter
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingQueryParameter
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingRequestBody
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.MissingValue
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.NotFound
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.UnexpectedVerificationError
        - $ref: >-
            #/components/schemas/com.meridianpay.core.common.api.ValidationError.UnprocessableValue
      title: ValidationError
    com.meridianpay.core.common.model.MeridianCurrency:
      type: string
      enum:
        - EUR
        - USD
        - GBP
        - PHP
        - MXN
      title: MeridianCurrency
    com.meridianpay.core.common.api.ValidationError.InvalidFormat:
      type: object
      description: >-
        A field was provided in a format the API could not accept, such as a
        malformed date, identifier, or currency code.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: InvalidFormat
    com.meridianpay.core.common.api.ValidationError.InvalidValue:
      type: object
      description: >-
        A field was well-formed but its value failed validation, such as an
        amount that is not positive or a currency code of the wrong length.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: InvalidValue
    com.meridianpay.core.common.api.ValidationError.MissingPathParameter:
      type: object
      description: >-
        A required path parameter was missing from the request URL, such as the
        user or account identifier.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingPathParameter
    com.meridianpay.core.common.api.ValidationError.MissingQueryParameter:
      type: object
      description: A required query parameter was missing from the request.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingQueryParameter
    com.meridianpay.core.common.api.ValidationError.MissingRequestBody:
      type: object
      description: The request body was required but was not provided.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingRequestBody
    com.meridianpay.core.common.api.ValidationError.MissingValue:
      type: object
      description: A required field was missing from the request body.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: MissingValue
    com.meridianpay.core.common.api.ValidationError.NotFound:
      type: object
      description: >-
        A resource referenced by the request could not be found, such as an
        unknown quote or virtual account.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: NotFound
    com.meridianpay.core.common.api.ValidationError.UnexpectedVerificationError:
      type: object
      description: An unexpected error occurred while verifying the request.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: UnexpectedVerificationError
    com.meridianpay.core.common.api.ValidationError.UnprocessableValue:
      type: object
      description: >-
        A field value was well-formed but could not be processed in the current
        context, such as a quote that has expired.
      properties:
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation
          title: String
      required:
        - fieldRef
        - message
      title: UnprocessableValue

````