openapi: 3.2.0
info:
  title: FX Orchestrator Create Fx Quote Endpoint API
  version: 1.FXRFQ
servers:
- url: /9f0a128f-cf1a-4503-b126-09dd2ae1e24f/133535775647469590
tags:
- name: CreateFxQuoteEndpoint
paths:
  /fx/v1/quote:
    post:
      tags:
      - CreateFxQuoteEndpoint
      summary: Requests a quote for a specified FX trade.
      operationId: Order.Create
      parameters:
      - name: Authorization
        in: header
        description: Your API token, obtained from the ClearBank Portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifer for the request; valid for 24 hours, max length 83.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFxQuoteRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFxQuoteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    CreateFxQuoteResponse:
      required:
      - quoteId
      - valueDate
      - currencyPair
      - exchangeRate
      - sellCurrency
      - sellAmount
      - buyCurrency
      - buyAmount
      - createdAt
      - expiresAt
      type: object
      properties:
        quoteRequest:
          $ref: '#/components/schemas/CreateFxQuoteRequest'
          description: Details of the request received from you.
        quoteId:
          type: string
          format: uuid
          description: Unique identifier for the quote provided by ClearBank.
          example: d4f23e64-276c-48b1-9b8c-5c4e1c395a82
        valueDate:
          type: string
          format: date-time
          description: Settlement date for the FX trade in the format yyyy-MM-ddTHH:mm:ssZ.
          example: '2024-08-24T14:15:22Z'
        currencyPair:
          type:
          - string
          - 'null'
          description: Currency pair for the FX trade, composed of three letter ISO 4217 currency codes and a slash for example 'GBP/USD'
          example: EUR/USD
        exchangeRate:
          type: number
          format: double
          description: The exchange rate ClearBank is providing for the quote.
          example: '1.214021494'
        sellCurrency:
          type:
          - string
          - 'null'
          description: Three-letter ISO 4217 currency code for the currency to sell.
          example: EUR
        sellAmount:
          type: number
          format: double
          description: The amount of the sell currency the customer would be charged.
          example: '1000.00'
        buyCurrency:
          type:
          - string
          - 'null'
          description: Three-letter ISO 4217 currency code for the currency to buy.
          example: USD
        buyAmount:
          type: number
          format: double
          description: The amount of the buy currency the customer would receive.
          example: '1214.02'
        createdAt:
          type: string
          format: date-time
          description: Date and time the quote was created in the format yyyy-MM-ddTHH:mm:ssZ.
          example: '2024-08-24T14:15:23Z'
        expiresAt:
          type: string
          format: date-time
          description: Date and time the quote will expire in the format yyyy-MM-ddTHH:mm:ssZ.
          example: '2024-08-24T14:16:08Z'
        marginAmount:
          type: number
          format: double
          description: The amount of the calculated margin.
          example: '12.29'
        marginCurrency:
          type:
          - string
          - 'null'
          description: Three-letter ISO 4217 currency code of the margin.
          example: USD
      additionalProperties: false
    CreateFxQuoteRequest:
      required:
      - valueDate
      - instructedAmount
      - fixedSide
      - sellCurrency
      - buyCurrency
      type: object
      properties:
        valueDate:
          type: string
          description: Settlement date for the proposed FX trade in the format yyyy-MM-ddTHH:mm:ssZ.
          format: date-time
          example: '2024-08-24T14:15:22Z'
        instructedAmount:
          type: number
          description: Amount instructed to buy or sell.
          format: double
          example: '1000.00'
        fixedSide:
          type:
          - string
          - 'null'
          description: The side of the trade to be fixed.
          enum:
          - buy
          - sell
          example: buy
        sellCurrency:
          type:
          - string
          - 'null'
          description: Three-letter ISO 4217 currency code for the currency to sell.
          example: EUR
          minLength: 3
          maxLength: 3
        buyCurrency:
          type:
          - string
          - 'null'
          description: Three-letter ISO 4217 currency code for the currency to buy.
          example: USD
          minLength: 3
          maxLength: 3
        margin:
          type: number
          description: The optional margin (as a percentage) from the trade to be credited to a margin account. Must be below 0.05 (for example, 0.002 = 0.2% margin).
          format: double
          minimum: 0
          maximum: 0.0499
          example: '0.01'
      additionalProperties: false