openapi: 3.1.0
info:
  title: AbbeyCross API
  description: |
    The AbbeyCross REST API is based on the OpenAPI 3.1.0 specification. AbbeyCross’ suite of emerging markets FX and payment solutions enables banks, payment companies and NGOs to take full control of their emerging markets FX and payments – for themselves, their clients, their donors, and their beneficiaries.

    You can find out more about AbbeyCross at [http://abbeycross.com](http://abbeycross.com).

    Further useful links:
      * [OpenAPI Specification](https://swagger.io/specification/)
      * [The AbbeyCross SDK](https://github.com/AbbeyCross)
      * [Privacy Policy](https://static.abbeycross.com/legal/privacy-policy.pdf)
  contact:
    email: support@abbeycross.com
    name: AbbeyCross Support Team
    url: https://abbeycross.com
  termsOfService: https://static.abbeycross.com/legal/terms-of-use.pdf
  version: 0.1-beta
servers:
- url: https://api.sandbox.abbeycross.com
  description: Sandbox
- url: https://api.abbeycross.com
  description: Production
tags:
- name: Authentication
  description: |
    AbbeyCross leverages the industry-standard OAuth 2.0 protocol for seamless authentication and authorization processes.

    Clients will receive API access credentials tailored for our sandbox environment as part of the initial onboarding process. These credentials, comprising a Client ID and a Client Secret.

    The Client Secret holds significant sensitivity as it possesses the potential to impersonate your institution within the AbbeyCross Platform API. Consequently, it necessitates meticulous handling and storage practices, restricting access to a select few and storing it within a secure secret storage solution. Ideally, it should be segregated from other AbbeyCross data, such as user API access tokens.

    For a comprehensive understanding of the OAuth 2.0 framework, we recommend refreshing your knowledge through [this article](https://auth0.com/docs/protocols/oauth2).
  externalDocs:
    description: Find out more
    url: http://swagger.io
- name: Configuration
  description: |
    The Configuration endpoint serves as a pivotal gateway within our comprehensive FX trading and payments platform, providing seamless access to critical static and reference data. Through this endpoint, users can retrieve essential information such as currency pairs, market data sources, and other configuration parameters.

    By centralising these  elements, our platform empowers users with the necessary insights to navigate the complexities of cross-border payments and FX trading, ensuring transparency, accuracy, and agility in every transaction
- name: Market Data
  description: "Market data derived from aggregating pricing plays a pivotal role\
    \ in informing trading decisions and market analysis. By aggregating pricing data\
    \ from multiple liquidity partners, FX platforms can provide valuable insights\
    \ into market trends, liquidity conditions, and price dynamics. \n\nThis aggregated\
    \ data may include various metrics such as averages, representing the mean or\
    \ weighted average of prices across different liquidity sources. Additionally,\
    \ best prices, often referred to as top-of-book quotes, signify the most competitive\
    \ bid and ask prices available in the market. These prices are crucial for traders\
    \ seeking optimal execution and liquidity. Moreover, unaggregated data from individual\
    \ liquidity partners offers a granular view of specific pricing streams, providing\
    \ additional context and transparency to market participants.\n\nBy leveraging\
    \ aggregated pricing data, traders gain a comprehensive understanding of FX market\
    \ conditions, empowering them to make informed trading decisions and capitalize\
    \ on opportunities in dynamic and fast-paced markets.\n"
  externalDocs:
    description: Find out more
    url: http://swagger.io
- name: Quote
  description: |
    Request for Quote (RFQ) functionality plays a pivotal role in facilitating transparent and efficient trading processes. RFQs allow market participants to solicit quotes from liquidity providers for a specific currency pair.

    When initiating an RFQ, the user submits a request specifying the desired quantity and any other pertinent trading parameters. Subsequently, liquidity providers respond with quotes detailing their offered prices, along with relevant terms and conditions. Upon receiving multiple quotes, the trader evaluates them based on factors such as price competitiveness, execution speed, and counterparty reliability.

    Once satisfied, the trader may proceed to accept the most favorable quote, initiating the trade execution process. Conversely, if none of the received quotes meet the trader's requirements, they have the option to reject all quotes and reassess their trading strategy or parameters.

    This dynamic RFQ process empowers traders with the flexibility to navigate FX markets while ensuring optimal execution outcomes tailored to their specific needs.
  externalDocs:
    description: Find out more about our store
    url: http://swagger.io
- name: Order
  description: |
    Orders are directives issued by investors to buy or sell currency pairs. Market orders and limit orders represent two common types of orders used to execute FX trades.

    A market order instructs the broker to buy or sell a currency pair at the prevailing market price, ensuring immediate execution but offering no control over the exact price at which the trade is executed. On the other hand, a limit order enables investors to specify the maximum price they are willing to pay when buying or the minimum price they are willing to accept when selling a currency pair. This provides greater control over the execution price but may result in the order not being filled if the market does not reach the specified price. Both market and limit orders serve distinct purposes: market orders prioritize speed of execution, while limit orders prioritize price control.

    Traders carefully consider market conditions and their trading objectives to determine the most appropriate order type for their FX trading strategy.
- name: Trade
  description: |
    Trades signify the execution of buy or sell orders for currency pairs. Each trade involves the exchange of currencies at agreed-upon exchange rates between buyers and sellers.

    Trades are integral to price discovery and liquidity provision in FX markets, facilitating efficient capital allocation. Specifically in FX, certain order types, like Fill or Kill (FoK) orders, add further nuance to trading dynamics. FoK orders require immediate execution of the entire order or cancellation ("killing") if immediate execution is not possible. This order type is particularly beneficial for FX traders seeking instant execution without the risk of partial fills.

    Traders employ various order types and strategies tailored to FX markets to navigate market conditions and achieve their trading goals, highlighting the dynamic nature of FX trading activities.
- name: Payment
  description: |
    Once an FX deal corresponding to a cross-border payment has been booked, providing payment instructions becomes essential for facilitating the seamless transfer of funds to the intended beneficiary.

    These payment instructions typically include comprehensive details about the recipient, such as their name, account number, and any relevant identifiers like IBAN or SWIFT/BIC codes. Additionally, instructions may specify the recipient's bank details, including the bank's name, address, and routing information.

    Ensuring accuracy and completeness in these instructions is paramount to guaranteeing the swift and accurate execution of the payment. By providing clear and precise payment instructions, financial institutions and FX service providers streamline the process of cross-border payments, minimizing errors and delays while enhancing transparency and compliance with regulatory requirements.
- name: Report
  description: "Comprehensive access to historical market data, empowering users to\
    \ generate insightful reports tailored to their specific needs.\n\nWith our platform,\
    \ users can effortlessly compute blended averages, enabling them to gain deeper\
    \ insights into market trends and performance over time. Additionally, our API\
    \ supports transaction cost analysis, allowing users to evaluate the efficiency\
    \ and effectiveness of their trading strategies. \n\nBy leveraging our robust\
    \ historical data and intuitive API endpoints, users can derive actionable intelligence\
    \ to optimize their investment decisions and drive better outcomes.\n"
- name: Webhooks
  description: |
    Webhooks provide a powerful mechanism for automating actions such as generating reports and processing order fills in real-time. By integrating webhooks into your application's workflow, you can receive instant notifications and trigger custom actions based on specific events or changes within your system.

    With our API you can define webhook endpoints to receive HTTP callbacks, allowing your application to react dynamically to events such as new orders, completed transactions, or updates to customer data.

    Leveraging the flexibility and scalability of webhooks enables seamless integration with external services and enhances the agility of your application, empowering you to deliver timely and responsive experiences to your users.
- name: Health
  description: |
    Health check endpoints to monitor the status of the AbbeyCross services.

    These endpoints provide information about the operational status of the services, helping maintain visibility and reliability in service consumption.
paths:
  /v1/oauth/token:
    post:
      description: |
        Generating an OAuth 2.0 access token is a fundamental step in securing access to protected resources within financial systems and APIs. Typically, this process involves the client application presenting its credentials, such as a client ID and client secret, to the authorization server.

        Upon successful authentication, the authorization server validates the client's credentials and issues an access token. This token serves as a bearer credential, granting the client application permission to access specified resources on behalf of the user. The access token is accompanied by metadata indicating its scope, expiry time, and potentially other relevant attributes. Once obtained, the client application includes the access token in subsequent requests to the resource server, effectively proving its authorization to access the requested resources.

        This robust OAuth 2.0 access token mechanism ensures secure and controlled access to sensitive financial data and functionalities while maintaining user privacy and security.
      operationId: GetToken
      tags:
      - Authentication
      summary: Generate access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - client_id
              - client_secret
              properties:
                client_id:
                  type: string
                  description: Your client id.
                  examples:
                  - ABC Bank
                client_secret:
                  type: string
                  description: Your client secret.
                  examples:
                  - 789xyz987654
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: Your access token.
                    examples:
                    - eyJz93a...k4laUWw
                  token_type:
                    type: string
                    description: The type of token.
                    examples:
                    - Bearer
                  expires_in:
                    type: integer
                    format: int64
                    example: 3600
                    description: The token expiry time in seconds.
                  scope:
                    type: string
                    description: The scope of the token.
                    example: read write
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/market_data:
    get:
      summary: Retrieve market data
      description: Retrieve market data snapshot using the specified criteria.
      operationId: RetrieveMarketData
      security:
      - bearerAuth: []
      tags:
      - Market Data
      parameters:
      - name: type
        in: query
        required: false
        description: The desired type of market data aggregation. If omitted, non-aggregated
          data will be returned.
        schema:
          type: string
          enum:
          - average
          - best
      - name: quantities
        in: query
        required: false
        description: Quantities to price in base currency. If omitted, standardised
          pricing tiers will be returned instead.
        schema:
          type: array
          items:
            type: integer
            format: int64
      - name: currency_pairs
        in: query
        required: false
        description: The currency pair of interest. If omitted, all currency pairs
          assigned to client will be returned.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CurrencyPair'
        style: form
        explode: true
        example:
        - USDBRL
        - USDCNY
        - USDT/KES
      - name: tenor
        in: query
        required: false
        example: SPOT
        description: The desired tenor for the requested currency pairs. If omitted,
          SPOT tenor will be used by default.
        schema:
          type: string
          enum:
          - SPOT
          - TOD
          - TOM
      - name: sources
        in: query
        required: false
        example:
        - Corpay
        - Wise
        explode: true
        description: Restrict prices to specified sources. If omitted, no source restrictions
          will be applied.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Market data successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/currency_pairs/market-data-pool:
    get:
      tags:
      - Configuration
      summary: Retrieve currency pairs for market data sources
      description: Retrieve your configured currency pairs.
      security:
      - bearerAuth: []
      operationId: GetMarketDataPool
      responses:
        '200':
          description: Your request has been successfully processed.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SourceCurrencyPairs'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/currency_pairs/tradable-pool:
    get:
      tags:
      - Configuration
      summary: Retrieve currency pairs for payment partners
      description: Retrieve your configured currency pairs.
      security:
      - bearerAuth: []
      operationId: GetTradablePool
      responses:
        '200':
          description: Your request has been successfully processed.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SourceCurrencyPairs'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/quotes:
    post:
      summary: Request quotes
      description: Request quotes using specified criteria. Either the buy amount
        or sell amount is required, but not both.
      operationId: RequestQuotes
      security:
      - bearerAuth: []
      tags:
      - Quote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - buy_currency
              - sell_currency
              properties:
                buy_currency:
                  $ref: '#/components/schemas/BuyCurrency'
                sell_currency:
                  $ref: '#/components/schemas/SellCurrency'
                buy_amount:
                  type: number
                  format: double
                  summary: Buy amount
                  description: The amount you want to buy.
                  example: '5000'
                sell_amount:
                  type: number
                  format: double
                  summary: Sell amount
                  description: The amount you want to sell.
                  example: '5000'
                tenor:
                  $ref: '#/components/schemas/TenorREST'
                type:
                  type: string
                  summary: Response type
                  description: Quotes returned in the response.
                  default: all
                  enum:
                  - all
                  - best
                sources:
                  type: array
                  summary: Quote sources restrictions
                  description: Restrict quotes to specified sources.
                  example:
                  - Corpay
                  - CAB
                  items:
                    type: string
                filter:
                  $ref: '#/components/schemas/QuotesFilter'
      responses:
        '200':
          description: Quote successfully requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotesBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/quotes/{batch_id}/reject:
    parameters:
    - name: batch_id
      in: path
      required: true
      schema:
        type: string
        description: Unique identifier for the quote batch.
        examples:
        - AAAA-BBBB-CCCC
    post:
      summary: Reject quotes
      description: Reject all quotes in the specified batch.
      operationId: RejectQuotes
      security:
      - bearerAuth: []
      tags:
      - Quote
      responses:
        '202':
          description: Quotes successfully rejected.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/quotes/{batch_id}:
    get:
      summary: Retrieve quotes batch
      description: Retrieve a quotes batch with specified id.
      operationId: RetrieveQuotes
      security:
      - bearerAuth: []
      tags:
      - Quote
      parameters:
      - name: batch_id
        in: path
        required: true
        schema:
          type: string
          description: Unique identifier for the quote batch.
          examples:
          - AAAA-BBBB-CCCC
      responses:
        '200':
          description: Quotes batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotesBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/quotes/{batch_id}/quote/{quote_id}/accept:
    parameters:
    - name: batch_id
      in: path
      required: true
      schema:
        type: string
        description: Unique identifier for the quote batch.
        examples:
        - AAAA-BBBB-CCCC
    - name: quote_id
      in: path
      required: true
      schema:
        type: string
        description: Unique identifier for the quote.
    post:
      summary: Accept quote
      description: Accept an individual rate quote, within a batch. All other rate
        quotes will automatically be rejected.
      operationId: AcceptQuote
      security:
      - bearerAuth: []
      tags:
      - Quote
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_order_id:
                  type: string
                  summary: Client order Id
                  description: The client's unique identifier for the order.
                order_notes:
                  type: string
                  maxLength: 256
                  summary: Order notes
                  description: Order notes.
                  example: My order notes
      responses:
        '200':
          description: Quote successfully accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  quote:
                    $ref: '#/components/schemas/Quote'
                  trade:
                    $ref: '#/components/schemas/Trade'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/quotes/{batch_id}/quote/{quote_id}/accept:
    parameters:
    - name: batch_id
      in: path
      required: true
      schema:
        type: string
        description: Unique identifier for the quote batch.
        examples:
        - AAAA-BBBB-CCCC
    - name: quote_id
      in: path
      required: true
      schema:
        type: string
        description: Unique identifier for the quote.
    post:
      summary: Accept quote (v2)
      description: |
        Accept an individual rate quote, within a batch. All other rate quotes will automatically be rejected.

        **v2 Changes:** This endpoint returns an enhanced Trade object with improved date semantics:
        - `submitted_datetime`: When the trade was submitted (replaces v1 `trade_date`)
        - `trade_date`: The actual trade execution date
        - `value_date`: The settlement date for the trade
      operationId: AcceptQuoteV2
      security:
      - bearerAuth: []
      tags:
      - Quote
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_order_id:
                  type: string
                  summary: Client order Id
                  description: The client's unique identifier for the order.
                order_notes:
                  type: string
                  maxLength: 256
                  summary: Order notes
                  description: Order notes.
                  example: My order notes
      responses:
        '200':
          description: Quote successfully accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  quote:
                    $ref: '#/components/schemas/Quote'
                  trade:
                    $ref: '#/components/schemas/TradeV2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/orders:
    post:
      tags:
      - Order
      summary: Place order
      description: Place a limit or market order. Either the buy amount or sell amount
        is required, but not both. If the order is not immediately filled or killed,
        but rather it is returned back with 'pending' status, then it may be necessary
        to try to retrieve the order again later for status updates.
      security:
      - bearerAuth: []
      operationId: PlaceOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceOrder'
      responses:
        '200':
          description: Order successfully placed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/orders/batch:
    post:
      tags:
      - Order
      summary: Batch order
      description: This endpoint receives batch of orders up 1000 orders with batchId
      security:
      - bearerAuth: []
      operationId: BatchOrders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - batch_orders
              type: object
              properties:
                batch_orders:
                  uniqueItems: true
                  type: array
                  items:
                    $ref: '#/components/schemas/PlaceOrder'
      responses:
        '200':
          description: Batch Orders successfully placed.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/orders/{id}:
    get:
      tags:
      - Order
      summary: Retrieve order
      description: Retrieves the order for the given id.
      operationId: RetrieveOrder
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: The unique identifier of the order.
      responses:
        '200':
          description: Your request has been successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/trades/{id}:
    get:
      tags:
      - Trade
      summary: Retrieve trade
      description: Retrieves the trade for the given id.
      security:
      - bearerAuth: []
      operationId: limitOrderGetInfo
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: The unique identifier of the trade.
      responses:
        '200':
          description: Your request has been successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trade'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v2/trades/{id}:
    get:
      tags:
      - Trade
      summary: Retrieve trade (v2)
      description: |
        Retrieves the trade for the given id.

        **v2 Changes:** This endpoint returns an enhanced Trade object with improved date semantics:
        - `submitted_datetime`: When the trade was submitted (replaces v1 `trade_date`)
        - `trade_date`: The actual trade execution date
        - `value_date`: The settlement date for the trade
      security:
      - bearerAuth: []
      operationId: limitOrderGetInfoV2
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: The unique identifier of the trade.
      responses:
        '200':
          description: Your request has been successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeV2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/trades/{trade_id}/amendments:
    post:
      summary: Enrich trade with internal reference ID
      operationId: enrichTrade
      description: "Add an internal reference ID to a confirmed trade. \n\n**Does\
        \ NOT modify:**\n- Quantity, price, settlement date\n- Counterparty or any\
        \ trade economics\n\n**Triggers:**\n- Webhook event:  `trade.reference.updated`\n\
        \n**Constraints:**\n- Trade must be in CONFIRMED or SETTLED status\n"
      tags:
      - Trade Enrichment
      parameters:
      - name: trade_id
        in: path
        required: true
        description: Marketplace-assigned trade identifier
        schema:
          type: string
          pattern: ^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$
        example: DDTD-78KL-B4TT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentRequest'
            example:
              amendment_type: enrichment
              fields:
                internal_reference_id: REF-2026-0106-789456
      responses:
        '201':
          description: Enrichment successfully applied
          headers:
            Location:
              description: URI of the enrichment record
              schema:
                type: string
                format: uri
              example: /v1/trades/DDTD-78KL-B4TT/amendments/AMD-001
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentResponse'
              example:
                trade_id: DDTD-78KL-B4TT
                amendment_id: AMD-001
                amendment_type: enrichment
                status: applied
                version: 2
                changes:
                  internal_reference_id:
                    previous: null
                    current: REF-2026-0106-789456
                amended_at: '2026-01-06T23:15:30Z'
                amended_by: farhadj0
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentError'
              example:
                error_code: APPROVAL_REQUIRED
                message: Post-settlement enrichment requires OPS approval
                details:
                  trade_status: SETTLED
                  user_role: TRADER
                  required_role: OPS_TEAM
                timestamp: '2026-01-06T23:15:30Z'
        '404':
          description: Trade not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentError'
              example:
                error_code: TRADE_NOT_FOUND
                message: Trade DDTD-78KL-B4TT not found
                timestamp: '2026-01-06T23:15:30Z'
        '422':
          description: Trade cannot be enriched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentError'
              examples:
                trade_not_confirmed:
                  value:
                    error_code: TRADE_NOT_CONFIRMED
                    message: Cannot amend trade that is not confirmed
                    details:
                      trade_status: PENDING
                    timestamp: '2026-01-06T23:15:30Z'
                trade_cancelled:
                  value:
                    error_code: TRADE_CANCELLED
                    message: Cannot enrich cancelled trade
                    details:
                      trade_status: CANCELLED
                      cancelled_at: '2026-01-06T11:00:00Z'
                    timestamp: '2026-01-06T23:15:30Z'
    get:
      summary: Get trade enrichment history
      operationId: getTradeEnrichments
      description: "Retrieve enrichment history for a specific trade. \n\nReturns\
        \ all amendments applied to the trade, including:\n- Amendment IDs and timestamps\n\
        - Internal reference ID changes\n- User who performed each enrichment\n- Current\
        \ trade version\n"
      tags:
      - Trade Enrichment
      parameters:
      - name: trade_id
        in: path
        required: true
        description: Marketplace-assigned trade identifier
        schema:
          type: string
          pattern: ^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$
        example: DDTD-78KL-B4TT
      responses:
        '200':
          description: Enrichment history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentHistoryResponse'
              example:
                trade_id: DDTD-78KL-B4TT
                current_version: AMD-001
                total_amendments: 1
                amendments:
                - amendment_id: AMD-001
                  amendment_type: enrichment
                  status: applied
                  version: 2
                  changes:
                    internal_reference_id:
                      previous: null
                      current: REF-2026-0106-789456
                  amended_at: '2026-01-06T23:15:30Z'
                  amended_by: REST client
        '404':
          description: Trade not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichmentError'
              example:
                error_code: TRADE_NOT_FOUND
                message: Trade DDTD-78KL-B4TT not found
                timestamp: '2026-01-06T23:15:30Z'
  /v1/payment_instructions:
    post:
      tags:
      - Payment
      security:
      - bearerAuth: []
      operationId: CreatePaymentInstructions
      summary: Accept a PACS 008 payment instructions
      description: Add PACS 008 payment instructions to the trade.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pacs008Request'
      responses:
        '200':
          description: Your request has been successfully processed and the payment
            instructions added to the trade.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInstructions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/payment_instructions/xml:
    post:
      tags:
      - Payment
      security:
      - bearerAuth: []
      operationId: CreatePaymentInstructionsXML
      summary: Accept a PACS 008 MX XML payment instructions
      description: Add PACS 008 MX XML payment instructions to the trade.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Pacs008Document'
      responses:
        '200':
          description: Your request has been successfully processed and the payment
            instructions added to the trade.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/PaymentInstructions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/payment_instructions/{MsgId}/status:
    get:
      tags:
      - Payment
      summary: Retrieve payment instructions
      description: Retrieves the payment instructions for the given MsgId.
      security:
      - bearerAuth: []
      operationId: GetPaymentInstructions
      parameters:
      - name: MsgId
        in: path
        required: true
        schema:
          type: string
          description: The unique identifier of the payment instructions.
      responses:
        '200':
          description: Your request has been successfully processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInstructions'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/reports/trade_analysis_report:
    post:
      tags:
      - Report
      summary: Trade Analysis Report
      description: Generate a trade analysis report comparing execution performance
        against our calculated averages.
      security:
      - bearerAuth: []
      operationId: TradeAnalysisReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - trade_id
                - timestamp
                - buy_currency
                - sell_currency
                - base_amount
                - tenor
                properties:
                  trade_id:
                    type: string
                    description: Trade ID for further trader search within the report.
                    example: ABCD1234
                  timestamp:
                    type: string
                    description: Date and time when this trade took place.
                    format: date-time
                  buy_currency:
                    $ref: '#/components/schemas/BuyCurrency'
                  sell_currency:
                    $ref: '#/components/schemas/SellCurrency'
                  base_amount:
                    type: integer
                    format: int64
                    summary: Amount in base currency
                    description: The amount of base currency bought or sold
                    example: '5000'
                  rate:
                    type: number
                    format: double
                    summary: Trade rate
                    example: '100.00'
                  tenor:
                    $ref: '#/components/schemas/TenorREST'
      responses:
        '200':
          description: Your request has been successfully processed.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    trade_id:
                      type: string
                      description: Trade ID for further trader search within the report.
                      example: ABCD1234
                    timestamp:
                      type: string
                      description: Date and time when this trade took place.
                      format: date-time
                    buy_currency:
                      $ref: '#/components/schemas/BuyCurrency'
                    sell_currency:
                      $ref: '#/components/schemas/SellCurrency'
                    base_amount:
                      type: integer
                      format: int64
                      summary: Amount in base currency
                      description: The amount of base currency bought or sold
                      example: '5000'
                    rate:
                      type: number
                      format: double
                      summary: Trade rate
                      example: '100.00'
                    traded_amount:
                      type: number
                      format: double
                      summary: Trade rate
                      example: '100.00'
                    abx_best_rate:
                      type: number
                      format: double
                      summary: Best rate available on Abbey Cross platform
                      example: '99.00'
                    rate_deviation:
                      type: number
                      format: double
                      summary: Deviation of trader’s rate comparing to the ABX best
                        rate
                      example: '-46.69'
                    potential_savings_base:
                      type: number
                      format: double
                      summary: Absolute value of opportunity - missed value based
                        on comparison of traders vs. ABX best rates
                      example: '8350.00'
                    best_rate_source:
                      type: string
                      summary: Payment provider offering best rate
                      example: CAB
                    all_rates:
                      type: array
                      items:
                        type: object
                        properties:
                          rate:
                            type: number
                            format: double
                            summary: Available rate
                            example: '99.00'
                          source:
                            type: string
                            summary: Payment provider contributing an available rate
                            example: CAB
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/reports/transactions_report:
    post:
      tags:
      - Report
      summary: Transaction report
      description: Returns transaction report using the specified criteria
      security:
      - bearerAuth: []
      operationId: TransactionsReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - date_from
              type: object
              properties:
                date_from:
                  type: string
                  nullable: false
                  format: date
                  description: Requested trade date period start
                date_to:
                  type: string
                  format: date
                  description: "Requested trade date period end If not \nspecified\
                    \ considered as the current date by default\n"
                currency_pairs:
                  type: array
                  description: Filters by an array of currency pairs of requested
                    trades, base currency first
                  example:
                  - USDBRL
                  - USDCNY
                  - USDT/KES
                  items:
                    $ref: '#/components/schemas/CurrencyPair'
      responses:
        '200':
          description: Your request has been successfully processed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/reports/funding_report:
    post:
      tags:
      - Report
      summary: Funding report
      description: Returns funding report using the specified criteria.
      security:
      - bearerAuth: []
      operationId: FundingReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - date_settlement_from
              - date_settlement_to
              type: object
              properties:
                date_settlement_from:
                  type: string
                  nullable: false
                  format: date
                  description: Requested settlement date period start. May be in the
                    future.
                date_settlement_to:
                  type: string
                  format: date
                  description: |
                    Requested settlement date period end. May be in the future.
                    May not be before settlement date period start.
                currencies:
                  type: array
                  description: Filter by funding (sell) currencies. All currencies
                    if not present.
                  example:
                  - USD
                  items:
                    type: string
                    minLength: 3
                    maxLength: 3
                    example: USD
                sources:
                  type: array
                  summary: Quote sources restrictions
                  description: Filter by payment partners that executed the trades.
                    All if not present.
                  example:
                  - Corpay
                  - CAB
                  items:
                    type: string
      responses:
        '200':
          description: Your request has been successfully processed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  date_settlement_to:
                    type: string
                    nullable: false
                    format: date
                    description: Report settlement date period end.
                  effective_date_settlement_from:
                    type: string
                    format: date
                    description: Report settlement date period start. May be after
                      date_settlement_from if the report is incomplete.
                  incomplete:
                    type: boolean
                    description: |
                      Report incomplete flag. Set to true if the range requested was too large, or
                      if some error has occurred during the report generation.
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        date_settlement:
                          type: string
                          description: Date and time when this trade took place.
                          format: date
                        sold_currency:
                          type: string
                          summary: Sell currency
                          description: The funding currency.
                          maxLength: 3
                          minLength: 3
                          example: USD
                        sold_amount:
                          type: number
                          format: double
                          summary: Amount in base currency
                          description: The amount of base currency bought or sold
                          example: '5000'
                        source:
                          type: string
                          summary: Payment provider contributing an available rate
                          example: CAB
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/reports/payments_report:
    post:
      tags:
      - Report
      summary: Payment report
      description: Returns payment report using the specified criteria
      security:
      - bearerAuth: []
      operationId: PaymentReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - date_from
              - currency_pair
              type: object
              properties:
                date_from:
                  type: string
                  nullable: false
                  format: date
                  description: Requested payment date period start
                date_to:
                  type: string
                  format: date
                  description: |
                    Requested payment date period end If not
                    specified considered as the current date by default
                currency_pair:
                  $ref: '#/components/schemas/CurrencyPair'
      responses:
        '200':
          description: Your request has been successfully processed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentInstructions'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/webhooks/register:
    post:
      summary: Register a webhook
      description: Register a new webhook endpoint to receive notifications.
      operationId: RegisterWebHook
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/WebHook'
      responses:
        '201':
          description: Webhook registered successfully.
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/WebHookResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/webhooks/unregister:
    delete:
      summary: Unregister a webhook
      description: Unregister an existing webhook endpoint.
      operationId: UnregisterWebhook
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/WebHook'
      responses:
        '204':
          description: Webhook registered successfully.
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/WebHookResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/healthz:
    get:
      tags:
      - Health
      summary: Health check
      description: Returns service health information.
      operationId: HealthCheck
      responses:
        '200':
          description: Service is healthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
components:
  responses:
    NoContent:
      description: No content
    BadRequest:
      description: One or more parameter values are invalid. Please check and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RestError'
    Unauthorized:
      description: Authentication token is required for this action that was not provided,
        expired or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RestError'
    Forbidden:
      description: Not authorized for the requested action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RestError'
    NotFound:
      description: The requested endpoint or entity does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RestError'
    Conflict:
      description: Action could not be completed because of conflict.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RestError'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RestError'
    ServiceUnavailable:
      description: The server is currently unavailable due to non-working hours. Please
        try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RestError'
  schemas:
    RestError:
      type: object
      description: An error may be received in response to a failed request.
      required:
      - code
      - text
      properties:
        errorId:
          type: string
          summary: Error unique identifier
          description: Links error message to a specific event in the system.
        code:
          type: string
          summary: Error code
          description: The code for the error that has occurred.
          examples:
          - not_authorized
        text:
          type: string
          summary: Error text
          description: The text for the error that has occurred.
          examples:
          - This is an example error text
        parameter_name:
          type: string
          summary: Parameter name
          description: An optional parameter name related to the error. Usually present
            for input validation errors.
          examples:
          - client_order_id
        parameter_value:
          type: object
          summary: Parameter value
          description: An optional parameter value related to the error. Set to input
            value of named parameter.
          examples:
          - ABCD0001
    MarketData:
      type: object
      description: Market data may be received in response to a market data request.
        The market data may be level 1 or level 2. L1 market data is expressed as
        a single price tier, whereas L2 data supports multiple price tiers.
      properties:
        source:
          type: string
          summary: Source
          description: Source of the market data. If aggregated this will be ABX.
          examples:
          - ABX
          - Corpay
          - Wise
        currency_pair:
          $ref: '#/components/schemas/CurrencyPair'
        bid:
          type: array
          summary: Bid
          description: Bid prices and quantities.
          items:
            $ref: '#/components/schemas/PriceTier'
        ask:
          type: array
          summary: Ask
          description: Ask prices and quantities.
          items:
            $ref: '#/components/schemas/PriceTier'
        timestamp:
          type: string
          format: date-time
          description: The timestamp of the event in ISO 8601 format.
        paymentFee:
          type: number
          format: double
          summary: Payment Fee
          description: Absolute fee amount reported or applied by the liquidity provider
            for this quote.
          example: 142.83
        salesMarkup:
          type: number
          format: double
          summary: Sales Markup
          description: Additional markup set by AbbeyCross for the organisation, calculated
            from the fee configuration unless supplied directly by the provider.
          example: 37.5
        feeCurrency:
          type: string
          summary: Fee Currency
          description: ISO 4217 currency code that applies to both paymentFee and
            salesMarkup values.
          example: USD
    PlaceOrder:
      required:
      - order_type
      - buy_currency
      - sell_currency
      - tenor
      type: object
      properties:
        order_type:
          $ref: '#/components/schemas/OrderType'
        client_order_id:
          type: string
          description: Client's unique identifier for the order.
        batch_id:
          type: string
          description: order's batch id
        buy_currency:
          $ref: '#/components/schemas/BuyCurrency'
        sell_currency:
          $ref: '#/components/schemas/SellCurrency'
        buy_amount:
          type: number
          format: double
          summary: Buy amount
          description: The amount that you want to buy.
          example: 1000
        sell_amount:
          type: number
          format: double
          summary: Sell amount
          description: The amount that you want to sell.
          example: 0
        tenor:
          $ref: '#/components/schemas/TenorREST'
        sources:
          uniqueItems: true
          type: array
          summary: Quote sources restriction
          description: Restrict quotes to specified sources.
          example:
          - CAB
          - Corpay
          items:
            type: string
            examples:
            - Corpay
            - Wise
        limit_price:
          type: number
          format: double
          summary: Limit price
          description: Limit price for the order using market conventions. Valid for
            limit orders only.
          example: 3.141592
        currency_pair:
          $ref: '#/components/schemas/CurrencyPair'
        order_notes:
          type: string
          maxLength: 256
          summary: Order notes
          description: Order notes.
          example: My order notes
    Order:
      type: object
      summary: Order
      description: An Order can placed and filled or killed (FoK). A fill may result
        in a Trade. Both limit and market order types are supported.
      required:
      - id
      - order_type
      - order_state
      - client_order_id
      - buy_currency
      - sell_currency
      - tenor
      properties:
        id:
          type: string
          summary: Id for the order
          description: Unique identifier for the order
          examples:
          - 123456789
        order_type:
          $ref: '#/components/schemas/OrderType'
        order_state:
          type: string
          description: Current fulfillment state of the order
          examples:
          - Filled
        client_order_id:
          type: string
          description: Client's unique identifier for the order.
          examples:
          - 123456789
        buy_currency:
          $ref: '#/components/schemas/BuyCurrency'
        sell_currency:
          $ref: '#/components/schemas/SellCurrency'
        buy_amount:
          type: number
          format: double
          summary: Buy amount
          description: The amount that you want to buy.
          examples:
          - 1000
        sell_amount:
          type: number
          format: double
          summary: Sell amount
          description: The amount that you want to sell.
          examples:
          - 1000
        tenor:
          $ref: '#/components/schemas/TenorREST'
        sources:
          uniqueItems: true
          type: array
          summary: Quote sources restriction
          description: Restrict quotes to specified sources.
          examples:
          - - Corpay
            - Wise
          items:
            type: string
            examples:
            - Corpay
            - Wise
        limit_price:
          type: number
          format: double
          summary: Limit price
          description: limit price for the order using market conventions. Valid for
            limit orders only.
          examples:
          - 21.491234
        order_notes:
          type: string
          maxLength: 256
          summary: Order notes
          description: Order notes.
          examples:
          - My order notes
    OrderType:
      type: string
      description: Order type may be either limit order or market order.
      enum:
      - limit
      - market
    OrderStatus:
      type: object
      description: Order status for the specified order id.
      required:
      - id
      - order_id
      - status
      properties:
        status:
          type: string
          description: Order status for given order id.
          enum:
          - pending
          - filled
          - killed
        timestamp:
          type: string
          description: Timestamp of last status update.
          format: date-time
    OrderResult:
      type: object
      required:
      - order
      properties:
        batch_id:
          type: string
        order:
          $ref: '#/components/schemas/Order'
        quote:
          $ref: '#/components/schemas/Quote'
        trade:
          $ref: '#/components/schemas/Trade'
    OrderReport:
      type: object
      required:
      - trade_date
      - trade_id
      - trade_side
      - trade_amount
      - buy_currency
      - sell_currency
      - buy_amount
      - sell_amount
      - rate
      - value_date
      - order_type
      - status
      - vendor
      - order_notes
      - order_id
      - user_id
      - user_email
      - currency_pair
      properties:
        trade_date:
          type: string
          description: Trading operation date/time
          format: date-time
        trade_id:
          type: string
          description: Trade ID provided by the liquidity provider, displayOrderId
          format: ABCD-ABCD-ABCD
        trade_side:
          type: string
          description: Buy/Sell
          default: BUY
          enum:
          - BUY
          - SELL
        trade_amount:
          type: number
          format: double
          description: Trade amount
          examples:
          - 100000
        buy_currency:
          $ref: '#/components/schemas/BuyCurrency'
        sell_currency:
          $ref: '#/components/schemas/SellCurrency'
        buy_amount:
          type: number
          format: double
          description: Currency bought (to buy)
          example: '100000.00'
        sell_amount:
          type: number
          format: double
          summary: Sell amount
          description: Amount sold (to sell)
          example: '100000.00'
        rate:
          type: number
          format: double
          description: Trade rate
          example: '100.00'
        value_date:
          type: string
          description: Trade value date
          format: date-time
        order_type:
          type: string
          description: Type of order (limit_order, market_order, rfq, rfs)
          examples:
          - rfs
          - rfq
          - limit_order
          - market_order
        status:
          type: string
          description: |
            User-friendly representation of the current state of the trade
            View OMS states REST status states for providing the correct status value
          examples:
          - new
          - rfq_rejected
          - quotes_received
        vendor:
          type: string
          description: Liquidity provided that the trade was made with
          examples:
          - DLOC
        order_notes:
          type: string
          description: Comment (order notes) added by user
          examples:
          - lorem ispum...
        order_id:
          type: string
          description: Trade ABX order ID
          examples:
          - order_id
        user_id:
          type: string
          description: Trader’s ID
          examples:
          - 1234567
        user_email:
          type: string
          format: email
          examples:
          - johndoe@abx.com
        currency_pair:
          $ref: '#/components/schemas/CurrencyPair'
    WebHook:
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook endpoint to register.
          examples:
          - https://example.com/webhook
        events:
          type: array
          description: The list of events to subscribe to.
          items:
            type: string
    WebHookResponse:
      type: object
      properties:
        message:
          type: string
          examples:
          - WebHook registered successfully.
        apiSecretKey:
          type: string
          examples:
          - ea799a52-e205-4c8e-acd1-ca6785bde0ff
    TenorREST:
      type: string
      summary: TenorREST value
      description: The tenor value for the quote e.g. SPOT, CASH (T+0), NEXT DAY (T+1)
      enum:
      - SPOT
      - TOD
      - TOM
      example: SPOT
    QuotesFilter:
      type: object
      summary: Quote source filter
      description: Filter quotes to sources supporting required features
      properties:
        transaction_types:
          type: array
          items:
            $ref: '#/components/schemas/TransactionTypeREST'
        payout_rails:
          type: array
          items:
            $ref: '#/components/schemas/PayoutRailREST'
    BuyCurrency:
      type: string
      summary: Buy currency
      description: The currency that you want to buy.
      maxLength: 5
      minLength: 3
      example: BRL
    SellCurrency:
      type: string
      summary: Sell currency
      description: The currency that you want to sell.
      maxLength: 5
      minLength: 3
      example: USD
    CurrencyPair:
      type: string
      description: Financial currency pair composed of two currencies codes. In case
        of currencies with 3 character long ISO codes, the separating '/' can be dropped
      example:
      - USD/BRL
      - USDBRL
    TransactionTypeREST:
      type: string
      enum:
      - B2B
      - B2C
      - C2C
      - C2B
    PayoutRailREST:
      type: string
      enum:
      - BankTransfer
      - LocalBankTransfer
      - Wallet
      - ACH
      - VisaDirect
      - IACH
      - RTP
    Pacs008Request:
      type: object
      properties:
        Document:
          $ref: '#/components/schemas/Pacs008Document'
    Pacs008Document:
      xml:
        name: Document
      type: object
      required:
      - FIToFICstmrCdtTrf
      properties:
        xmlns:
          xml:
            attribute: true
          type: string
          example: urn:iso:std:iso:20022:tech:xsd:pacs.008.001.02
        FIToFICstmrCdtTrf:
          xml:
            name: FIToFICstmrCdtTrf
          type: object
          required:
          - GrpHdr
          - CdtTrfTxInf
          properties:
            GrpHdr:
              $ref: '#/components/schemas/GrpHdr'
            CdtTrfTxInf:
              xml:
                name: CdtTrfTxInf
              type: object
              required:
              - RmtInf
              - Purp
              - PmtId
              - IntrBkSttlmAmt
              - Dbtr
              - DbtrAcct
              - Cdtr
              properties:
                PmtId:
                  xml:
                    name: PmtId
                  type: object
                  required:
                  - EndToEndId
                  properties:
                    EndToEndId:
                      type: string
                      example: Invoice 123456
                IntrBkSttlmAmt:
                  $ref: '#/components/schemas/IntrBkSttlmAmt'
                IntrBkSttlmDt:
                  type: string
                  format: date
                ChrgBr:
                  type: string
                  example: SLEV
                Dbtr:
                  xml:
                    name: Dbtr
                  type: object
                  required:
                  - Nm
                  - PstlAdr
                  properties:
                    Nm:
                      type: string
                      example: Debtor Name
                    PstlAdr:
                      $ref: '#/components/schemas/PstlAdr'
                    Id:
                      xml:
                        name: Id
                      type: object
                      properties:
                        OrgId:
                          xml:
                            name: OrgId
                          type: object
                          properties:
                            Othr:
                              xml:
                                name: Othr
                              type: object
                              properties:
                                Id:
                                  type: string
                                  example: DE987654321
                DbtrAcct:
                  xml:
                    name: DbtrAcct
                  type: object
                  required:
                  - Id
                  properties:
                    Id:
                      xml:
                        name: Id
                      type: object
                      required:
                      - IBAN
                      properties:
                        IBAN:
                          type: string
                          example: DE89370400440532013000
                        Othr:
                          xml:
                            name: Othr
                          type: object
                          properties:
                            Id:
                              type: string
                              example: FR123456789
                DbtrAgt:
                  xml:
                    name: DbtrAgt
                  type: object
                  properties:
                    FinInstnId:
                      xml:
                        name: FinInstnId
                      type: object
                      required:
                      - BICFI
                      properties:
                        BICFI:
                          type: string
                          example: DEUTDEFFXXX
                UltmtDbtr:
                  $ref: '#/components/schemas/UltmtDbtr'
                Cdtr:
                  xml:
                    name: Cdtr
                  type: object
                  required:
                  - Nm
                  - PstlAdr
                  properties:
                    Nm:
                      type: string
                      example: Creditor Name
                    PstlAdr:
                      $ref: '#/components/schemas/PstlAdr'
                    Id:
                      $ref: '#/components/schemas/Id'
                    CtryOfRes:
                      type: string
                    CtctDtls:
                      $ref: '#/components/schemas/CtctDtls'
                CdtrAcct:
                  xml:
                    name: CdtrAcct
                  type: object
                  properties:
                    Id:
                      xml:
                        name: Id
                      type: object
                      required:
                      - IBAN
                      properties:
                        IBAN:
                          type: string
                          example: FR7630006000011234567890189
                        Othr:
                          xml:
                            name: Othr
                          type: object
                          properties:
                            Id:
                              type: string
                              example: FR123456789
                CdtrAgt:
                  xml:
                    name: CdtrAgt
                  type: object
                  properties:
                    FinInstnId:
                      xml:
                        name: FinInstnId
                      type: object
                      required:
                      - BICFI
                      properties:
                        BICFI:
                          type: string
                          example: BNPAFRPPXXX
                CdtrAgtAcct:
                  xml:
                    name: CdtrAgtAcct
                  type: object
                  properties:
                    Id:
                      xml:
                        name: Id
                      type: object
                      properties:
                        Othr:
                          xml:
                            name: Othr
                          type: object
                          properties:
                            Id:
                              type: string
                              example: FR123456789
                IntrmyAgt1:
                  xml:
                    name: IntrmyAgt1
                  type: object
                  properties:
                    FinInstnId:
                      xml:
                        name: FinInstnId
                      type: object
                      properties:
                        BICFI:
                          type: string
                          example: BNPAFRPPXXX
                Purp:
                  xml:
                    name: Purp
                  type: object
                  required:
                  - Cd
                  properties:
                    Cd:
                      type: string
                      example: GDDS
                RmtInf:
                  xml:
                    name: RmtInf
                  type: object
                  required:
                  - Ustrd
                  properties:
                    Ustrd:
                      type: string
                      example: AB12-XP34-5670
                SplmtryData:
                  xml:
                    name: SplmtryData
                  type: object
                  properties:
                    Envlp:
                      xml:
                        name: Envlp
                      type: object
                      properties:
                        Any:
                          xml:
                            name: Any
                          type: object
                          properties:
                            SourceOfFunds:
                              type: string
                              example: Additional information here
                            SubPurpose:
                              type: string
                              example: Additional information here
                            InvoiceNumber:
                              type: string
                              example: Additional information here
    IntrBkSttlmAmt:
      type: object
      required:
      - Ccy
      - value
      properties:
        Ccy:
          type: string
          example: EUR
        value:
          type: number
          format: double
          example: '1000.00'
    Id:
      type: object
      properties:
        OrgId:
          xml:
            name: OrgId
          type: object
          properties:
            Othr:
              xml:
                name: Othr
              type: object
              properties:
                Id:
                  type: string
                SchmeNm:
                  xml:
                    name: SchmeNm
                  type: object
                  properties:
                    Prtry:
                      type: string
                Issr:
                  type: string
        PrvtId:
          xml:
            name: PrvtId
          type: object
          properties:
            DtAndPlcOfBirth:
              xml:
                name: DtAndPlcOfBirth
              properties:
                BirthDt:
                  type: string
                  format: date
                CtryOfBirth:
                  type: string
                CityOfBirth:
                  type: string
                PrvcOfBirth:
                  type: string
            Othr:
              xml:
                name: Othr
              type: object
              properties:
                Id:
                  type: string
                SchmeNm:
                  xml:
                    name: SchmeNm
                  type: object
                  properties:
                    Prtry:
                      type: string
                Issr:
                  type: string
        CtryOfRes:
          type: string
    PstlAdr:
      type: object
      required:
      - Ctry
      - TwnNm
      - AdrLine
      properties:
        Ctry:
          type: string
          example: DE
        TwnNm:
          type: string
          example: Berlin
        PstlCd:
          type: string
          example: SW12N2
        AdrLine:
          type: array
          items:
            type: string
          example: '[ "Address Line 1", "Address Line 2" ]'
    CtctDtls:
      type: object
      properties:
        NmPrfx:
          type: string
        Nm:
          type: string
        PhneNb:
          type: string
        MobNb:
          type: string
        FaxNb:
          type: string
        URLAdr:
          type: string
        EmailAdr:
          type: string
        JobTitl:
          type: string
        Rspnsblty:
          type: string
        Dept:
          type: string
        Othr:
          xml:
            name: Othr
          type: object
          properties:
            ChanlTp:
              type: string
            Id:
              type: string
        PrefrdMtd:
          type: string
          enum:
          - MAIL
          - FAXX
          - LETT
          - CELL
          - ONLI
          - PHON
    GrpHdr:
      xml:
        name: GrpHdr
      type: object
      required:
      - MsgId
      - NbOfTxs
      properties:
        MsgId:
          type: string
          example: '1234567890123456'
        CreDtTm:
          type: string
          example: '2024-07-04T12:34:56'
        NbOfTxs:
          type: string
          example: '1'
        SttlmInf:
          xml:
            name: SttlmInf
          type: object
          required:
          - SttlmMtd
          properties:
            SttlmMtd:
              type: string
              example: CLRG
        InstgAgt:
          xml:
            name: InstgAgt
          type: object
          properties:
            FinInstnId:
              xml:
                name: FinInstnId
              type: object
              required:
              - BICFI
              properties:
                BICFI:
                  type: string
                  example: INSTBICXXXX
        InstdAgt:
          xml:
            name: InstdAgt
          type: object
          required:
          - FinInstnId
          properties:
            Nm:
              xml:
                name: Nm
              type: string
            BranchIdentification:
              xml:
                name: BranchIdentification
              type: object
              required:
              - Id
              properties:
                Id:
                  type: string
            FinInstnId:
              xml:
                name: FinInstnId
              type: object
              required:
              - BICFI
              properties:
                BICFI:
                  type: string
                  example: INSDBICXXXX
    UltmtDbtr:
      type: object
      properties:
        Nm:
          xml:
            name: Nm
          type: string
          example: Ultimate Debtor Name
        PstlAdr:
          $ref: '#/components/schemas/PstlAdr'
        Id:
          $ref: '#/components/schemas/Id'
        CtctDtls:
          $ref: '#/components/schemas/CtctDtls'
    PaymentInstructions:
      type: object
      description: Payment instructions for a trade.
      required:
      - GrpHdr
      - paymentProviderInfo
      - status
      properties:
        GrpHdr:
          $ref: '#/components/schemas/GrpHdr'
        paymentProviderInfo:
          $ref: '#/components/schemas/PaymentProviderInfo'
        status:
          type: string
          summary: Payment status
          description: Latest payment status change.
          default: pending
          enum:
          - pending
          - accepted
          - rejected
        trackingReference:
          type: string
          summary: Tracking reference
          description: Unique identifier used for linking with the payment tracking
            system.
          example: TO-02102025-A4074
        trackingLink:
          type: string
          summary: Tracking link
          description: URL for tracking the payment progress.
          example: https://sandbox.vertofx.com/tracker/TO-02102025-A4074...
        errCode:
          type: string
          summary: Error code
    PaymentProviderInfo:
      type: object
      properties:
        providerName:
          type: string
        providerTransactionId:
          type: string
        providerTransactionStatus:
          type: string
        providerTransactionStatusCode:
          type: string
    PriceTier:
      type: object
      description: Price tier represents a price/quantity combination.
      required:
      - price
      - quantity
      properties:
        price:
          type: number
          format: double
          description: Price for the given quantity.
          examples:
          - 1.124
        quantity:
          type: integer
          format: int64
          description: Price for the given quantity.
          examples:
          - 1000
    Quote:
      type: object
      description: A Quote may result from a successful quotes request.
      required:
      - id
      - source_id
      - client_id
      - rate
      - source
      - expires
      - status
      properties:
        id:
          type: string
          summary: Quote id
          description: The unique identifier for the quote.
          examples:
          - ABCD-ABCD-ABCD
        source_id:
          type: string
          summary: Source id
          description: The source's unique identifier for the quote.
          examples:
          - 123456789
        client_id:
          type: string
          summary: Client id
          description: The unique identifier fo the client.
          examples:
          - ABC Bank
        rate:
          type: number
          format: double
          summary: The rate for the quote
          description: The rate for the quote.
          examples:
          - 5.0001
        source:
          type: string
          summary: Quote source
          description: The source of the quote.
          examples:
          - Corpay
        expires:
          type: integer
          format: int64
          summary: Quote expiry
          description: The quote expiry in milliseconds.
          examples:
          - 5000
        quote_date:
          type: string
          format: date-time
          summary: quote date
          description: Quote date.
        value_date:
          type: string
          format: date-time
          summary: value date
          description: The value date (settlement date) for the quote. This date indicates
            when the trade will settle. For quotes where the value date is not available
            from the source, this field will be null.
        status:
          type: string
          summary: Rejected
          description: Rejection status.
          default: pending
          enum:
          - pending
          - accepted
          - rejected
    QuotesBatch:
      type: object
      properties:
        batch_id:
          type: string
          summary: Batch Id
          description: The batch id for the rate quotes.
          examples:
          - ABCD-ABCD-ABCD
        buy_currency:
          $ref: '#/components/schemas/BuyCurrency'
        sell_currency:
          $ref: '#/components/schemas/SellCurrency'
        buy_amount:
          type: number
          format: double
          summary: Buy amount
          description: The amount you want to buy.
          examples:
          - null
        sell_amount:
          type: number
          format: double
          summary: Sell amount
          description: The amount you want to sell.
          examples:
          - 100
        tenor:
          $ref: '#/components/schemas/TenorREST'
        type:
          type: string
          summary: Response type
          description: Quotes returned in the response.
          default: all
          enum:
          - all
          - best
        sources:
          type: array
          summary: Quote sources restriction
          description: Restrict quotes to specified sources.
          examples:
          - - Corpay
            - Wise
          items:
            type: string
        quotes:
          type: array
          items:
            $ref: '#/components/schemas/Quote'
        filter:
          $ref: '#/components/schemas/QuotesFilter'
        error:
          $ref: '#/components/schemas/RestError'
    Trade:
      type: object
      description: A Trade may result from a successfully executed order.
      required:
      - id
      - source_execution_id
      - source
      - buy_currency
      - sell_currency
      - buy_amount
      - sell_amount
      - price
      - trade_date
      properties:
        id:
          type: string
          description: Id for the trade.
          examples:
          - ABCD-ABCD-ABCD
        source_order_id:
          type: string
          description: Source order id for the trade.
          examples:
          - 123456789
        source_execution_id:
          type: string
          description: Source execution id for the trade.
          examples:
          - 123456789
        source:
          type: string
          description: Source for the expected trade.
          examples:
          - Corpay
        buy_currency:
          $ref: '#/components/schemas/BuyCurrency'
        sell_currency:
          $ref: '#/components/schemas/SellCurrency'
        buy_amount:
          type: number
          format: double
          summary: Buy amount
          description: The amount that you bought.
          examples:
          - 500
        sell_amount:
          type: number
          format: double
          summary: Sell amount
          description: The amount that you sold.
          examples:
          - null
        price:
          type: number
          format: double
          summary: The price
          description: The rate for the trade.
          examples:
          - 5.0001
        trade_date:
          type: string
          format: date-time
          summary: trade date
          description: Trade date.
    TradeV2:
      type: object
      description: A Trade (v2) may result from a successfully executed order.
      required:
      - id
      - source_execution_id
      - source
      - buy_currency
      - sell_currency
      - buy_amount
      - sell_amount
      - price
      - submitted_datetime
      properties:
        id:
          type: string
          description: Id for the trade.
          examples:
          - ABCD-ABCD-ABCD
        source_order_id:
          type: string
          description: Source order id for the trade.
          examples:
          - 123456789
        source_execution_id:
          type: string
          description: Source execution id for the trade.
          examples:
          - 123456789
        source:
          type: string
          description: Source for the expected trade.
          examples:
          - Corpay
        buy_currency:
          $ref: '#/components/schemas/BuyCurrency'
        sell_currency:
          $ref: '#/components/schemas/SellCurrency'
        buy_amount:
          type: number
          format: double
          summary: Buy amount
          description: The amount that you bought.
          examples:
          - 500
        sell_amount:
          type: number
          format: double
          summary: Sell amount
          description: The amount that you sold.
          examples:
          - null
        price:
          type: number
          format: double
          summary: The price
          description: The rate for the trade.
          examples:
          - 5.0001
        submitted_datetime:
          type: string
          format: date-time
          summary: submitted datetime
          description: The datetime when the trade was submitted to the system. This
            represents the submission/event time, not the actual trade execution date.
        trade_date:
          type: string
          format: date
          summary: trade date
          description: The actual trade execution date. If not provided by the liquidity
            provider, this defaults to the current UTC date (truncated to date).
        value_date:
          type: string
          format: date
          summary: value date
          description: The value date (settlement date) for the trade. This date indicates
            when the trade will settle. If not provided by the source, it is derived
            from the trade_date based on tenor using simple business-day logic (skipping
            weekends).
    SourceCurrencyPairs:
      type: object
      description: A market data source or payment partner with available currency
        pairs
      required:
      - source
      - currency_pairs
      properties:
        source:
          type: string
          description: Source name.
          examples:
          - Corpay
          - CAB
        currency_pairs:
          type: array
          description: Represents two currencies, where the first one is being bought
            and the other being sold
          items:
            $ref: '#/components/schemas/CurrencyPair'
          example:
          - USDBRL
          - BRLUSD
    EnrichmentRequest:
      type: object
      required:
      - amendment_type
      - fields
      properties:
        amendment_type:
          $ref: '#/components/schemas/AmendmentType'
        fields:
          type: object
          required:
          - internal_reference_id
          properties:
            internal_reference_id:
              type: string
              maxLength: 64
              minLength: 1
              description: "Internal payment system reference ID. \nMaps to FIX SecondaryTradeReportID\
                \ (Tag 818).\nCan only be set once (immutable).\n\n**Format:** REF-YYYY-MMDD-NNNNNN+\n\
                **Example:** REF-2026-0106-789456\n"
              example: REF-2026-0106-789456
          additionalProperties: false
    EnrichmentResponse:
      type: object
      properties:
        trade_id:
          type: string
          description: Original marketplace-assigned trade ID (immutable)
          example: DDTD-78KL-B4TT
        amendment_id:
          type: string
          description: Sequential enrichment identifier for this trade
          example: AMD-001
        amendment_type:
          $ref: '#/components/schemas/AmendmentType'
        status:
          $ref: '#/components/schemas/AmendmentStatus'
        changes:
          type: object
          description: Fields that were enriched (keyed by field names)
          additionalProperties:
            $ref: '#/components/schemas/Change'
        amended_at:
          type: string
          format: date-time
          description: When enrichment was applied (ISO 8601)
          example: '2026-01-06T23:15:30Z'
        amended_by:
          type: string
          description: User who submitted enrichment
          example: farhadj0
    AmendmentType:
      type: string
      enum:
      - enrichment
      description: Type of amendment (always "enrichment" in v1.0)
      example: enrichment
    AmendmentStatus:
      type: string
      enum:
      - applied
      - failed
      description: Enrichment status
      example: applied
    EnrichmentHistoryResponse:
      type: object
      properties:
        trade_id:
          type: string
          description: Marketplace-assigned trade identifier
          example: DDTD-78KL-B4TT
        current_version:
          type: string
          description: Amendment ID of the amendment currently associated with the
            trade
          example: AMD-001
        total_amendments:
          type: integer
          description: Total number of enrichments applied
          example: 1
          minimum: 0
        amendments:
          type: array
          description: List of all enrichments (newest first)
          items:
            $ref: '#/components/schemas/Amendment'
    Amendment:
      type: object
      properties:
        amendment_id:
          type: string
          description: Sequential enrichment identifier for this trade
          example: AMD-001
        amendment_type:
          $ref: '#/components/schemas/AmendmentType'
        status:
          $ref: '#/components/schemas/AmendmentStatus'
        changes:
          type: object
          description: Fields that were enriched (keyed by field names)
          additionalProperties:
            $ref: '#/components/schemas/Change'
        amended_at:
          type: string
          format: date-time
          description: When enrichment was applied (ISO 8601)
          example: '2026-01-06T23:15:30Z'
        amended_by:
          type: string
          description: User who submitted enrichment
          example: ABX REST Client
    EnrichmentError:
      type: object
      required:
      - error_code
      - message
      - timestamp
      properties:
        error_code:
          type: string
          description: Machine-readable error code
          example: REFERENCE_ID_ALREADY_SET
        message:
          type: string
          description: Human-readable error message
          example: Internal reference ID already set and cannot be modified
        details:
          type: object
          description: Additional error context (optional)
          additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: When error occurred (ISO 8601)
          example: '2026-01-06T23:15:30Z'
    Change:
      type: object
      description: Previous/current value pair for an enriched field
      properties:
        previous:
          type: string
          nullable: true
          description: Previous value (null if first time set)
          example: null
        current:
          type: string
          description: New value
          example: REF-2026-0106-789456
      required:
      - current
    HealthStatus:
      type: object
      description: Simple health indicator.
      properties:
        status:
          type: string
          example: healthy
      required:
      - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
