---
swagger: "2.0"
info:
  description: API that allows customers book trades and retrieve trade history
  version: "0.1"
  title: Ebury Trades
produces:
- application/json
paths:
  /trades:
    post:
      tags:
      - Trades
      consumes:
      - application/json
      summary: Create a Trade
      description: |
        Initiate a new trade. You need to have an existing quote_id to do this
      parameters:
      - name: quote_id
        in: query
        description: The identifier of the quote
        required: true
        type: string
      - name: client_id
        in: query
        description: The ID of the client
        required: true
        type: string
      - in: body
        name: requestBody
        description: Request Payload
        required: true
        schema:
          $ref: '#/definitions/NewTrade'
      - name: Authorization
        description: The access token
        in: header
        required: true
        type: string
      - name: X-Contact-ID
        description: The ID of the contact
        in: header
        required: false
        type: string
      responses:
        201:
          description: Trade created
          schema:
            $ref: '#/definitions/ConfirmedTrade'
        400:
          description: Formatting, parameter or schema validation error. See error message for further details
          schema:
            $ref: '#/definitions/ErrorMessage'
        401:
          description: Access denied due to authentication failure
        403:
          description: Could not complete action due to data constraints. Refer to error message for additional details
          schema:
            $ref: '#/definitions/ErrorMessage'
        404:
          description: Client or quote ID not found
        409:
          description: Requested trade causes a conflict that can be corrected, see response body for details
          schema:
            $ref: '#/definitions/ErrorMessage'
        502:
          description: Internal integration error. Contact support
          schema:
            $ref: '#/definitions/ErrorMessage'
      security:
      - api_key: []
      x-tags:
      - tag: Trades
    get:
      tags:
      - Trades
      summary: Get all trades
      description: Get all the trades for a given client ID
      parameters:
      - name: client_id
        in: query
        description: The ID of the client
        required: true
        type: string
      - name: trade_type
        required: false
        in: query
        description: The trade type. The list will be filtered to include only trades with a matching trade type.
        type: array
        items:
          type: string
          enum:
            - spot
            - forward
            - window_forward
            - drawdown
            - ndf
      - name: parent_trade_id
        required: false
        in: query
        description: Parent identifier for drawdown trades
        type: string
      - name: page
        description: The desired page number for pagination. By default is 1.
        in: query
        required: false
        type: integer
        format: int32
      - name: page_size
        description: The number of items per page for pagination. By default is 50.
        in: query
        required: false
        type: integer
        format: int32
      - name: Authorization
        description: The access token
        in: header
        required: true
        type: string
      - name: X-Contact-ID
        description: The ID of the contact
        in: header
        required: false
        type: string
      responses:
        200:
          description: List of trades
          schema:
            type: array
            items:
              $ref: '#/definitions/BookedTrade'
        400:
          description: Formatting, parameter or schema validation error. See error message for further details
          schema:
            $ref: '#/definitions/ErrorMessage'
        401:
          description: Access denied due to authentication failure
        403:
          description: Could not complete action due to data constraints. Refer to error message for additional details
          schema:
            $ref: '#/definitions/ErrorMessage'
        404:
          description: Client or quote ID not found
        502:
          description: Internal integration error. Contact support
          schema:
            $ref: '#/definitions/ErrorMessage'
      security:
      - api_key: []
      x-tags:
      - tag: Trades
  /trades/{trade_id}:
    get:
      tags:
      - Trades
      summary: Get a trade
      description: Get a trade with a specific trade_id, the response type depends on the value of the response_model field.
      parameters:
      - name: trade_id
        in: path
        description: Trade identifier
        required: true
        type: string
      - name: client_id
        in: query
        description: The ID of the client
        required: true
        type: string
      - name: response_model
        in: query
        type: string
        description: The type of the data model returned.
        items:
          type: string
          enum:
            - BookedTrade
            - ExtendedBookedTrade
      - name: Authorization
        description: The access token
        in: header
        required: true
        type: string
      - name: X-Contact-ID
        description: The ID of the contact
        in: header
        required: false
        type: string
      responses:
        200:
          description: Returns a ExtendedBookedTrade model if response_model is ExtendedBookedTrade otherwise a BookedTrade model
          schema:
            $ref: '#/definitions/ExtendedBookedTrade'
        400:
          description: Formatting, parameter or schema validation error. See error message for further details
          schema:
            $ref: '#/definitions/ErrorMessage'
        401:
          description: Access denied due to authentication failure
        403:
          description: Could not complete action due to data constraints. Refer to error message for additional details
          schema:
            $ref: '#/definitions/ErrorMessage'
        404:
          description: Client or trade ID not found
        502:
          description: Internal integration error. Contact support
          schema:
            $ref: '#/definitions/ErrorMessage'
      security:
      - api_key: []
      x-tags:
      - tag: Trades
securityDefinitions:
  api_key:
    type: apiKey
    name: x-api-key
    description: An API Key
    in: header
definitions:
  ErrorMessage:
    description: An error message.
    type: object
    properties:
      code:
        description: The error code.
        type: string
      message:
        description: A short description of the cause of the error.
        type: string
      details:
        description: Error details
        type: string
    required:
    - code
    - message
    - details
  NewTrade:
    type: object
    required:
    - reason
    properties:
      trade_type:
        type: string
        description: Currently ignored (DEPRECATED)
      reason:
        type: string
        description: Reason for trade. The 'not_related_to_goods_or_services' reason is only for spot type.
        enum:
            - charitable_aid
            - payment_for_goods
            - capital_investment
            - payment_for_services
            - repatriation_of_goods
            - repatriation_of_services
            - property_purchase
            - mortage_repayment
            - property_rental_or_maintenance
            - salary_payroll
            - travel_costs
            - living_costs
            - repayment_of_loan
            - balance_hedging
            - repatriation_from_investment
            - portfolio_netting
            - not_related_to_goods_or_services
            - other
      reference:
        type: string
        description: Reference for the trade.
  ConfirmedTrade:
    type: object
    required:
    - trade_id
    - bank_account
    - maturity_date
    properties:
      trade_id:
        type: string
        description: Trade identifier
      bank_account:
        type: object
        description: An existing bank account
        required:
        - account_number
        - iban
        - swift_code
        - bank_identifier
        - bank_identifier_type
        - bank_name
        - bank_address_line_1
        - bank_address_line_2
        - bank_city
        - bank_post_code
        properties:
          account_number:
            type: string
          iban:
            type: string
          swift_code:
            type: string
          bank_identifier:
            type: string
          bank_identifier_type:
            type: string
          bank_name:
            type: string
          bank_address_line_1:
            type: string
          bank_address_line_2:
            type: string
          bank_city:
            type: string
          bank_post_code:
            type: string
      maturity_date:
        type: string
        format: date
        description: Limit date and time (UTC) in which funds must be received by Ebury
      initial_margin_amount:
        type: number
        format: double
        description: Only for forwards. Trade's deposit amount.
      initial_margin_due_date:
        type: string
        format: date
        description: Only for forwards. Date on or before which deposit must be received by Ebury. Date and time are in UTC.

  BookedTrade:
    type: object
    required:
    - beneficiaries
    - buy_amount
    - buy_currency
    - fee_amount
    - fee_currency
    - maturity_date
    - order_date
    - parent_trade_id
    - rate
    - rate_symbol
    - sell_amount
    - sell_currency
    - status
    - trade_id
    - trade_type
    - synthetic
    properties:
      trade_id:
        type: string
        description: Trade identifier
      trade_type:
        type: string
        description: Trade type
      status:
        $ref: '#/definitions/TradeStatus'
      buy_currency:
        type: string
        description: Buy currency code
      buy_amount:
        type: number
        format: float
        description: Buy amount
      sell_currency:
        type: string
        description: Sell currency code
      sell_amount:
        type: number
        format: float
        description: Sell amount
      rate:
        type: number
        format: float
        description: Booked rate
      rate_symbol:
        type: string
        description: The symbol of booked rate
      parent_trade_id:
        type: string
        description: Parent trade ID (not null for drawdown deals)
      order_date:
        type: string
        format: date
        description: Order date
      maturity_date:
        type: string
        format: date
        description: Limit date and time (UTC) in which funds must be received by Ebury
      beneficiaries:
        type: array
        description: Beneficiary names
        items:
          type: string
      fee_currency:
        type: string
        description: Fee currency
      fee_amount:
        type: number
        format: float
        description: Fee amount
      synthetic:
        type: boolean
        format: boolean
        description: Identifies as a synthetic future contracts
      trade_receipt:
        type: string
        format: uri
        description: The URL to get the trade receipt
      reference:
        type: string
        description: 'Additional trade reference. Example: Invoice number.'
  ExtendedBookedTrade:
    allOf:
    - $ref: '#/definitions/BookedTrade'
    - type: object
      properties:
        payments:
          type: array
          description: List of payments made on trade
          items:
            type: object
            properties:
              payment_id:
                type: string
              amount:
                type: number
                format: float
              beneficiary_name:
                type: string
              payment_instruction:
                type: string
                format: uri
              payment_receipt:
                type: string
                format: uri
              status:
                $ref: '#/definitions/PaymentStatus'
              url:
                type: string
                format: uri
  TradeStatus:
    type: string
    description: Status of the trade
    enum:
    - Created
    - Funds In Partially
    - Funds in Full
    - Funds Out Partially Allocated
    - Funds Out Full Allocated
    - Closed
    - Cancelled
  PaymentStatus:
    description: The current status of the payment
    type: string
    enum:
      - Need more beneficiary information
      - Validating beneficiary information
      - Waiting for payment date
      - Payment complete
      - Executing Payment
      - Payment pending of authorization
      - Payment rejected
      - Payment cancelled
