components:
  examples: {}
  headers: {}
  parameters: {}
  requestBodies: {}
  responses: {}
  schemas:
    UUID:
      type: string
      format: uuid
      description: |-
        Stringified UUIDv4.
        See [RFC 4112](https://tools.ietf.org/html/rfc4122)
      pattern: "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}"
    ConversionProposalResponseBody:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the conversion proposal within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        fromCurrency:
          type: string
          description: >-
            The original currency that will be converted into a different currency. This is the currency the user wants
            to exchange or convert in the transaction.
          example: MXN
        toCurrency:
          type: string
          description: >-
            The target currency that the original currency (fromCurrency) will be converted into. This is the desired
            currency after the conversion process is complete.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the toCurrency
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the fromCurrency
          example: 32161.8
        quote:
          type: number
          format: double
          description: The rate locked by this conversion.
          example: 20.6165
        validUntilTs:
          type: number
          format: double
          description: The unix timestamp until which the conversion offer is valid.
          example: 1659625098
      required:
        - id
        - fromCurrency
        - toCurrency
        - quote
        - validUntilTs
      type: object
      additionalProperties: false
    ErrorResponse:
      description: An API Error
      properties:
        message:
          type: string
          description: A short explanation of the error.
          example: Can't perform this action
        reason:
          type: string
          description: A detailed description of the reason for the failure.
          example: Supplied object is in *Cancelled* state, which prevents performing this action
      required:
        - message
      type: object
      additionalProperties: false
    RejectedByIPError:
      properties:
        message:
          type: string
          description: A short explanation of the error.
          example: Could not parse IP address (v4 or v6) for ip
      required:
        - message
      type: object
      additionalProperties: false
    ConversionQuoteRequestBody:
      description: Information required by Grain in order to generate a conversion quote proposal.
      properties:
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: >-
            The amount of `toCurrency` to convert, using this amount and the conversion rate will determine the
            `fromCurrency` amount.
          example: 1560
      required:
        - fromCurrency
        - toCurrency
      type: object
      additionalProperties: false
    CustomerIP:
      type: string
      format: IPv4
      description: |-
        The IPv4 address of the browser from which the customer contacts your platform. <br />
        _example_: `192.158.1.38`
      pattern: ((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}
    ConversionActionResponseBody:
      description: The response of a conversion action. Includes the reference to the relevant objects.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the created conversion
          example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
      required:
        - id
      type: object
      additionalProperties: false
    ExtraFieldsParam:
      properties: {}
      additionalProperties:
        anyOf:
          - type: string
          - type: number
            format: double
          - type: boolean
      type: object
      example:
        field_a: value_a
        field_b: value_b
      description: |-
        Additional fields that provide further details about the transaction.
        These fields should be specified as a valid JSON object.
    AcceptConversionProposalRequestBody:
      properties:
        conversionProposalId:
          type: string
          description: The id of the conversion proposal to accept.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        toCurrencyAmount:
          type: number
          format: double
          description: >-
            the amount to transfer in the toCurrency. If amount was not specified on quote, it should be specified on
            Accept.
          example: 1560
        extraFields:
          $ref: "#/components/schemas/ExtraFieldsParam"
      required:
        - conversionProposalId
      type: object
      additionalProperties: false
    GrainDateFormat:
      type: string
      example: "2023-04-15"
      format: YYYY-MM-DD
      description: The date format accepted by Grain's API. We accept dash separated ISO-8601 date-only strings.
      pattern: \d{4}-\d{2}-\d{2}
    OrganizationConversion:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the conversion within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        organizationId:
          $ref: "#/components/schemas/UUID"
          description: The id of the organization that perform the conversion within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the toCurrency
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the fromCurrency
          example: 32161.8
        quote:
          type: number
          format: double
          description: The rate locked by this conversion.
          example: 20.6165
        acceptedAtTs:
          type: number
          format: double
          description: The unix timestamp in which the conversion offer was accepted (if it was).
          example: 1659625088
        issuedAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the conversion was issued, denoted in `YYYY-MM-DD` format.
          example: "2023-01-18"
        completedAt:
          description: The date in which the conversion was completed, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
      required:
        - id
        - organizationId
        - fromCurrency
        - toCurrency
        - toCurrencyAmount
        - fromCurrencyAmount
        - quote
        - acceptedAtTs
        - issuedAt
        - completedAt
      type: object
      additionalProperties: false
    Page:
      type: number
      format: double
      description: The page indicating which set of items are returned
      minimum: 1
    PerPage:
      type: number
      format: double
      description: number of items in a page
      minimum: 1
      maximum: 100
    PaginationResponse:
      description: Pagination parameters of the returned results.
      properties:
        page:
          $ref: "#/components/schemas/Page"
        perPage:
          $ref: "#/components/schemas/PerPage"
        totalResults:
          type: number
          format: double
          description: The total amount of results available
      required:
        - page
        - perPage
        - totalResults
      type: object
      additionalProperties: false
    ListConversionsResponseBody:
      properties:
        conversions:
          items:
            $ref: "#/components/schemas/OrganizationConversion"
          type: array
          description: A list of conversions matching the search criteria.
        pagination:
          $ref: "#/components/schemas/PaginationResponse"
      required:
        - conversions
        - pagination
      type: object
      additionalProperties: false
    CreateObjectResponseBody:
      description: A response containing the ID of the created object.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the created object.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
      required:
        - id
      type: object
      additionalProperties: false
    ContactEmail:
      type: string
      example: garrick@ollivanders.co.uk
      description: The email address of the company's primary contact
    CountryCode:
      type: string
      example: GB
      description: The alpha-2 ISO 3166 country code of the entity's country.
      pattern: ^[A-Za-z]{2}$
    CustomersExtraFieldsParam:
      properties: {}
      additionalProperties:
        anyOf:
          - type: string
          - type: number
            format: double
          - type: boolean
      type: object
      example:
        field_a: value_a
        field_b: value_b
      description: |-
        Additional fields that provide further details about the company.
        These fields should be specified as a valid JSON object.
    Pick_Customer.-or-contactEmail-or-contactFullName-or-contactPhoneNumber-or-companyName-or-companyAddress-or-companyCity-or-companyState-or-companyCountry-or-companyTaxId-or-externalCustomerId-or-extraFields_:
      properties:
        contactEmail:
          $ref: "#/components/schemas/ContactEmail"
          description: The email for the company's primary contact
          example: customer@company.com
        contactFullName:
          type: string
          description: The name of the company's primary contact
          example: Garrick Ollivander
        contactPhoneNumber:
          type: string
          description: The phone number of the company's primary contact
          example: "+12125551234"
        companyName:
          type: string
          description: The legal name of the customer's company
          example: Ollivander's Wand Shop
        companyAddress:
          type: string
          description: The address of the company
          example: 12 Diagon Alley
        companyCity:
          type: string
          description: The city of the company
          example: London
        companyState:
          type: string
          description: The state the company is in (US based)
          example: London
        companyCountry:
          $ref: "#/components/schemas/CountryCode"
        companyTaxId:
          type: string
          description: The tax identification or registration number of the company
          example: 123-45-6789
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        extraFields:
          $ref: "#/components/schemas/CustomersExtraFieldsParam"
          description: |-
            Additional fields that provide further details about the customer.
            These fields should be specified as a valid JSON object.
          example:
            field_a: value_a
            field_b: value_b
      required:
        - companyName
        - companyCountry
        - externalCustomerId
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    CreateUpdateCustomerRequestBody:
      $ref: >-
        #/components/schemas/Pick_Customer.-or-contactEmail-or-contactFullName-or-contactPhoneNumber-or-companyName-or-companyAddress-or-companyCity-or-companyState-or-companyCountry-or-companyTaxId-or-externalCustomerId-or-extraFields_
    Partial_CreateUpdateCustomerRequestBody_:
      properties:
        contactEmail:
          $ref: "#/components/schemas/ContactEmail"
          description: The email for the company's primary contact
          example: customer@company.com
        contactFullName:
          type: string
          description: The name of the company's primary contact
          example: Garrick Ollivander
        contactPhoneNumber:
          type: string
          description: The phone number of the company's primary contact
          example: "+12125551234"
        companyName:
          type: string
          description: The legal name of the customer's company
          example: Ollivander's Wand Shop
        companyAddress:
          type: string
          description: The address of the company
          example: 12 Diagon Alley
        companyCity:
          type: string
          description: The city of the company
          example: London
        companyState:
          type: string
          description: The state the company is in (US based)
          example: London
        companyCountry:
          $ref: "#/components/schemas/CountryCode"
        companyTaxId:
          type: string
          description: The tax identification or registration number of the company
          example: 123-45-6789
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        extraFields:
          $ref: "#/components/schemas/CustomersExtraFieldsParam"
          description: |-
            Additional fields that provide further details about the customer.
            These fields should be specified as a valid JSON object.
          example:
            field_a: value_a
            field_b: value_b
      type: object
      description: Make all properties in T optional
    CustomerStatus:
      description: The eligibility of the customer to receive quotes
      enum:
        - Pending
        - Approved
        - Rejected
      type: string
    Customer:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the customer within the Grain platform.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        companyName:
          type: string
          description: The legal name of the customer's company
          example: Ollivander's Wand Shop
        companyAddress:
          type: string
          description: The address of the company
          example: 12 Diagon Alley
        companyCity:
          type: string
          description: The city of the company
          example: London
        companyState:
          type: string
          description: The state the company is in (US based)
          example: London
        companyCountry:
          $ref: "#/components/schemas/CountryCode"
        contactEmail:
          $ref: "#/components/schemas/ContactEmail"
          description: The email for the company's primary contact
          example: customer@company.com
        contactFullName:
          type: string
          description: The name of the company's primary contact
          example: Garrick Ollivander
        contactPhoneNumber:
          type: string
          description: The phone number of the company's primary contact
          example: "+12125551234"
        companyTaxId:
          type: string
          description: The tax identification or registration number of the company
          example: 123-45-6789
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        status:
          $ref: "#/components/schemas/CustomerStatus"
        extraFields:
          $ref: "#/components/schemas/CustomersExtraFieldsParam"
          description: |-
            Additional fields that provide further details about the customer.
            These fields should be specified as a valid JSON object.
          example:
            field_a: value_a
            field_b: value_b
      required:
        - id
        - companyName
        - companyCountry
        - externalCustomerId
        - status
      type: object
      additionalProperties: false
    ListCustomersResponseBody:
      description: A response containing a list of customers matching the search criteria.
      properties:
        customers:
          items:
            $ref: "#/components/schemas/Customer"
          type: array
          description: A list of customers matching the search criteria.
        pagination:
          $ref: "#/components/schemas/PaginationResponse"
      required:
        - customers
        - pagination
      type: object
      additionalProperties: false
    AcceptOfflineDualHedgeResponseBody:
      description: The response of accepting an offline rate for a dual hedge.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the dual hedge within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        transactionId:
          $ref: "#/components/schemas/UUID"
          description: The id of the transaction within the Grain platform.
          example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
        hedgeIds:
          items:
            $ref: "#/components/schemas/UUID"
          type: array
          description: The ids of the individual hedges created as part of this dual hedge.
          example:
            - 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
            - 5e89bd76-3d4f-58e3-9cf4-4g87235e0e38
      required:
        - id
        - hedgeIds
      type: object
      additionalProperties: false
    AcceptOfflineHedgeRevisionExpiredErrorResponse:
      description: An API Error
      properties:
        message:
          type: string
          description: A short code of the error.
          example: REVISION_EXPIRED
        reason:
          type: string
          description: A detailed description of the reason for the failure.
          example: The revision number has expired. Please fetch a new rate table using the /offline-rates endpoint.
      required:
        - message
      type: object
      additionalProperties: false
    AcceptOfflineHedgeBadParamsErrorResponse:
      description: An API Error
      properties:
        message:
          type: string
          description: A short code of the error.
          example: REVISION_INVALID
        reason:
          type: string
          description: A detailed description of the reason for the failure.
          example: >-
            The revision number is not valid or does not exist. Please fetch a new rate table using the /offline-rates
            endpoint and pass a valid revision.
      required:
        - message
      type: object
      additionalProperties: false
    AcceptOfflineDualHedgeProposalRequestBody:
      properties:
        revision:
          type: number
          format: double
          description: The id of the revision that defines the accepted rate for the currency-pair and tenor.
          example: 156
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency you want to buy.
          example: USD
        customerToCurrencyAmount:
          type: number
          format: double
          description: The amount to hedge in the toCurrency for the customer.
          example: 100000
        vendorToCurrencyAmount:
          type: number
          format: double
          description: The amount to hedge in the toCurrency for the vendor.
          example: 100000
        customerEndAt:
          type: string
          description: The date in which the customer hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2024-02-23"
        vendorEndAt:
          type: string
          description: The date in which the vendor hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2024-02-23"
        rate:
          type: number
          format: double
          description: >-
            Represents the offline hedge rate determined by a two-dimensional lookup based on the vendor and customer
            tenors.


            **Calculating Tenors:**


            Tenors are calculated from the calendar-day difference between the tenorCalculationDate and the
            vendor/customer end dates, then mapped into the nearest supported tenor bucket:


            -

            - > 0 and ≤ 7 calendar days → 7-day tenor

            - > 7 and ≤ 14 calendar days → 14-day tenor

            - > 14 and ≤ 30 calendar days → 30-day tenor

            - > 30 and ≤ 60 calendar days → 60-day tenor

            - > 60 and ≤ 90 calendar days → 90-day tenor

            - … continues in similar ranges up to 720 days


            **Note:** All calendar days count — weekends and holidays included.


            **Rate Lookup Example:**


            The rate is retrieved from a two-dimensional map using both tenors:

            ```

            "USDMXN": {
              "7": { "7": 1.1 },
              "14": { "7": 1.2, "14": 1.3 },
              "30": { "7": 1.1, "14": 1.1, "30": 1.1 },
              // ... and so on
            }

            ```


            In this example, if the vendor tenor is 14 days and the customer tenor is 7 days, the rate would be 1.2.


            To calculate the difference in calendar days accurately, we recommend using a date manipulation library,
            such as date-fns and its `differenceInCalendarDays` function, or a similar feature provided by other date
            libraries.
          example: 20.616512
        externalTransactionId:
          type: string
          description: The transaction id, as identified within your system.
          example: 780231b3ae0d7e9e5097nd89
        extraFields:
          $ref: "#/components/schemas/ExtraFieldsParam"
      required:
        - revision
        - fromCurrency
        - toCurrency
        - customerToCurrencyAmount
        - vendorToCurrencyAmount
        - customerEndAt
        - vendorEndAt
        - rate
        - externalTransactionId
      type: object
      additionalProperties: false
    DisplaySettlementType.Full:
      enum:
        - full
      type: string
    HedgeStatus:
      enum:
        - Active
        - Cancelled
        - Completed
        - InProcess
        - Overdue
      type: string
    DisplayFixedSide:
      description: |-
        The fixed side as displayed in external APIs (camelCase format).
        Indicates which currency amount was specified when creating the hedge.
      enum:
        - toCurrencyAmount
        - fromCurrencyAmount
      type: string
    DisplaySettlementType:
      description: |-
        The settlement type as displayed in the Partners API.
        Maps internal settlement types to simplified external values.
      enum:
        - full
        - offset
        - manual
      type: string
    CollectionHedge:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the hedge within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        customerId:
          $ref: "#/components/schemas/UUID"
          description: The id of the customer within the Grain platform.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        status:
          $ref: "#/components/schemas/HedgeStatus"
          description: The Status of the Hedge
          example: Active
        transactionId:
          $ref: "#/components/schemas/UUID"
          description: The id of the transaction within the Grain platform.
          example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
        externalTransactionId:
          type: string
          description: The transaction id as identified within your system.
          example: 780231b3ae0d7e9e5097nd89
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        toCurrencyAmount:
          type: number
          format: double
          description: |-
            The amount to hedge in the toCurrency.
            If fromCurrencyAmount is provided, then toCurrencyAmount calculated as:
            `toCurrencyAmount = fromCurrencyAmount / quote`
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: |-
            The amount to hedge in the fromCurrency.
            If toCurrencyAmount is provided, then fromCurrencyAmount calculated as:
            `fromCurrencyAmount = toCurrencyAmount * quote`
          example: 32161.8
        fixedSide:
          $ref: "#/components/schemas/DisplayFixedSide"
          description: >-
            Indicates which currency amount was fixed (specified) when creating the hedge.

            When `fixedSide` is `toCurrencyAmount`, the `toCurrencyAmount` was specified and `fromCurrencyAmount` was
            calculated.

            When `fixedSide` is `fromCurrencyAmount`, the `fromCurrencyAmount` was specified and `toCurrencyAmount` was
            calculated.
          example: toCurrencyAmount
        initialCollateralAmount:
          type: number
          format: double
          description: |-
            The initial collateral amount required for this hedge in the fromCurrency.
            Calculated as fromCurrencyAmount * initialCollateralPercentage.
          example: 1608.09
        quote:
          type: number
          format: double
          description: The rate locked by this hedge.
          example: 20.6165
        externalMarkupPct:
          type:
            - number
            - "null"
          format: double
          description: |-
            The external markup percentage that should be added to this quote on top of Grain’s internal pricing.
            For example, a value of 1.0 represents a 1.0% additional markup.
          example: 1
        acceptedAtTs:
          type: number
          format: double
          description: The unix timestamp in which the hedge offer was accepted (if it was).
          example: 1659625088
        issuedAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge was issued, denoted in `YYYY-MM-DD` format.
          example: "2023-01-18"
        endAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        updatedAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge was last modified, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        cancelledAt:
          description: The date in which the hedge was cancelled, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        initialCollateralReceivedAt:
          description: |-
            The date in which the initial collateral was received, denoted in `YYYY-MM-DD` format.
            Null if not yet received.
          example: "2023-01-20"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        fundsReceivedAt:
          description: >-
            The date in which the funds of the hedge arrived, afterwards the settlement occurs denoted in `YYYY-MM-DD`
            format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        completedAt:
          description: The date in which the hedge was completed, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        completedAtTs:
          type:
            - number
            - "null"
          format: double
          description: The unix timestamp in which the hedge was completed.
          example: 1659625090
        overdueAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will become overdue, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        settlementAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge begins settlement, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        settlementType:
          $ref: "#/components/schemas/DisplaySettlementType.Full"
          description: |-
            The method in which the hedge is being settled.
            If 'full' type is set, the total hedge amount should be sent to Grain prior to settlement
        adjustedMtmChangePct:
          type:
            - number
            - "null"
          format: double
          description: >-
            The percentage change in the adjusted mark-to-market value since the previous valuation.

            A value of 1.0 represents a 1.0% change. A negative value indicates a potential margin call if the threshold
            has been exceeded.
          example: 1.25
        adjustedMtmChangeTs:
          type:
            - number
            - "null"
          format: double
          description: The timestamp at which the latest adjusted mark-to-market change was calculated.
          example: 1674057600
      required:
        - id
        - customerId
        - status
        - transactionId
        - externalTransactionId
        - fromCurrency
        - toCurrency
        - externalCustomerId
        - toCurrencyAmount
        - fromCurrencyAmount
        - fixedSide
        - initialCollateralAmount
        - quote
        - externalMarkupPct
        - acceptedAtTs
        - issuedAt
        - endAt
        - updatedAt
        - cancelledAt
        - initialCollateralReceivedAt
        - fundsReceivedAt
        - completedAt
        - completedAtTs
        - overdueAt
        - settlementAt
        - settlementType
        - adjustedMtmChangePct
        - adjustedMtmChangeTs
      type: object
      additionalProperties: false
    DisplaySettlementType.Offset:
      enum:
        - offset
      type: string
    OffsetHedge:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the hedge within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        customerId:
          $ref: "#/components/schemas/UUID"
          description: The id of the customer within the Grain platform.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        status:
          $ref: "#/components/schemas/HedgeStatus"
          description: The Status of the Hedge
          example: Active
        transactionId:
          $ref: "#/components/schemas/UUID"
          description: The id of the transaction within the Grain platform.
          example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
        externalTransactionId:
          type: string
          description: The transaction id as identified within your system.
          example: 780231b3ae0d7e9e5097nd89
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        externalCustomerId:
          type: string
          description: The id used to identify the customer within your platform
          example: 630231b3ae0d7e9e5097ad35
        toCurrencyAmount:
          type: number
          format: double
          description: |-
            The amount to hedge in the toCurrency.
            If fromCurrencyAmount is provided, then toCurrencyAmount calculated as:
            `toCurrencyAmount = fromCurrencyAmount / quote`
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: |-
            The amount to hedge in the fromCurrency.
            If toCurrencyAmount is provided, then fromCurrencyAmount calculated as:
            `fromCurrencyAmount = toCurrencyAmount * quote`
          example: 32161.8
        fixedSide:
          $ref: "#/components/schemas/DisplayFixedSide"
          description: >-
            Indicates which currency amount was fixed (specified) when creating the hedge.

            When `fixedSide` is `toCurrencyAmount`, the `toCurrencyAmount` was specified and `fromCurrencyAmount` was
            calculated.

            When `fixedSide` is `fromCurrencyAmount`, the `fromCurrencyAmount` was specified and `toCurrencyAmount` was
            calculated.
          example: toCurrencyAmount
        initialCollateralAmount:
          type: number
          format: double
          description: |-
            The initial collateral amount required for this hedge in the fromCurrency.
            Calculated as fromCurrencyAmount * initialCollateralPercentage.
          example: 1608.09
        quote:
          type: number
          format: double
          description: The rate locked by this hedge.
          example: 20.6165
        externalMarkupPct:
          type:
            - number
            - "null"
          format: double
          description: |-
            The external markup percentage that should be added to this quote on top of Grain’s internal pricing.
            For example, a value of 1.0 represents a 1.0% additional markup.
          example: 1
        acceptedAtTs:
          type: number
          format: double
          description: The unix timestamp in which the hedge offer was accepted (if it was).
          example: 1659625088
        issuedAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge was issued, denoted in `YYYY-MM-DD` format.
          example: "2023-01-18"
        endAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        updatedAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge was last modified, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        cancelledAt:
          description: The date in which the hedge was cancelled, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        initialCollateralReceivedAt:
          description: |-
            The date in which the initial collateral was received, denoted in `YYYY-MM-DD` format.
            Null if not yet received.
          example: "2023-01-20"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        fundsReceivedAt:
          description: >-
            The date in which the funds of the hedge arrived, afterwards the settlement occurs denoted in `YYYY-MM-DD`
            format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        completedAt:
          description: The date in which the hedge was completed, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
        completedAtTs:
          type:
            - number
            - "null"
          format: double
          description: The unix timestamp in which the hedge was completed.
          example: 1659625090
        overdueAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will become overdue, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        settlementAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge begins settlement, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        settlementType:
          $ref: "#/components/schemas/DisplaySettlementType.Offset"
          description: |-
            The method in which the hedge is being settled.
            If 'offset' type is set, only the difference between the locked rate and settlement rate is exchanged
        adjustedMtmChangePct:
          type:
            - number
            - "null"
          format: double
          description: >-
            The percentage change in the adjusted mark-to-market value since the previous valuation.

            A value of 1.0 represents a 1.0% change. A negative value indicates a potential margin call if the threshold
            has been exceeded.
          example: 1.25
        adjustedMtmChangeTs:
          type:
            - number
            - "null"
          format: double
          description: The timestamp at which the latest adjusted mark-to-market change was calculated.
          example: 1674057600
        settlementAmount:
          type: number
          format: double
          description: The total amount settled for the hedge. The amount can be positive or negative
          example: 10.99
        settlementCurrency:
          type: string
          description: The currency in which the settlement was processed
          example: USD
        endDateQuote:
          type: number
          format: double
          description: The rate used to calculate the hedge settlement amount
          example: 20.9236
      required:
        - id
        - customerId
        - status
        - transactionId
        - externalTransactionId
        - fromCurrency
        - toCurrency
        - externalCustomerId
        - toCurrencyAmount
        - fromCurrencyAmount
        - fixedSide
        - initialCollateralAmount
        - quote
        - externalMarkupPct
        - acceptedAtTs
        - issuedAt
        - endAt
        - updatedAt
        - cancelledAt
        - initialCollateralReceivedAt
        - fundsReceivedAt
        - completedAt
        - completedAtTs
        - overdueAt
        - settlementAt
        - settlementType
        - adjustedMtmChangePct
        - adjustedMtmChangeTs
      type: object
      additionalProperties: false
    CustomerHedge:
      anyOf:
        - $ref: "#/components/schemas/CollectionHedge"
        - $ref: "#/components/schemas/OffsetHedge"
      description: Hedge objects represent transactions which are currently hedged.
    DualHedgeCustomerHedge:
      allOf:
        - $ref: "#/components/schemas/CustomerHedge"
        - properties:
            spotRate:
              type: number
              format: double
          required:
            - spotRate
          type: object
      description: Hedge objects represent transactions which are currently hedged.
    GetDualHedgeResponseBody:
      description: The response for retrieving a dual hedge.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the dual hedge within the Grain platform.
          example: bf77890b-17e2-48a1-9198-707df23eb127
        issuedAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge was issued, denoted in `YYYY-MM-DD` format.
          example: "2023-01-18"
        customerId:
          $ref: "#/components/schemas/UUID"
          description: The id of the customer within the Grain platform.
          example: 87d8e330-2878-4742-a86f-dbbb3bf522ac
        functionalCurrency:
          type: string
          description: The functional currency of the customer.
          example: EUR
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency you want to buy.
          example: USD
        rate:
          type: number
          format: double
          description: >-
            Represents the offline hedge rate determined by a two-dimensional lookup based on the vendor and customer
            tenors.
          example: 20.616512
        hedges:
          items:
            $ref: "#/components/schemas/DualHedgeCustomerHedge"
          type: array
          description: The individual hedges that make up this dual hedge.
          example:
            - id: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
              customerId: 87d8e330-2878-4742-a86f-dbbb3bf522ac
              status: Active
              transactionId: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
              externalTransactionId: 780231b3ae0d7e9e5097nd89
              fromCurrency: MXN
              toCurrency: EUR
              externalCustomerId: 630231b3ae0d7e9e5097ad35
              toCurrencyAmount: 1000
              fromCurrencyAmount: 22850
              fixedSide: fromCurrencyAmount
              initialCollateralAmount: 1142.5
              quote: 22.85
              externalMarkupPct: null
              acceptedAtTs: 1659625088
              issuedAt: "2023-01-18"
              endAt: "2023-02-20"
              updatedAt: "2023-02-20"
              cancelledAt: null
              initialCollateralReceivedAt: "2023-01-20"
              fundsReceivedAt: null
              completedAt: null
              completedAtTs: null
              overdueAt: "2023-02-20"
              settlementAt: "2023-02-20"
              settlementType: full
              adjustedMtmChangePct: 1.25
              adjustedMtmChangeTs: 1674057600
              spotRate: 22.71
            - id: 5e89bd76-3d4f-58e3-9cf4-4f87235e0e38
              customerId: 87d8e330-2878-4742-a86f-dbbb3bf522ac
              status: Active
              transactionId: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
              externalTransactionId: 780231b3ae0d7e9e5097nd89
              fromCurrency: EUR
              toCurrency: USD
              externalCustomerId: 630231b3ae0d7e9e5097ad35
              toCurrencyAmount: 1108.27
              fromCurrencyAmount: 1000
              fixedSide: toCurrencyAmount
              initialCollateralAmount: 50
              quote: 0.9024
              externalMarkupPct: null
              acceptedAtTs: 1659625088
              issuedAt: "2023-01-18"
              endAt: "2023-02-23"
              updatedAt: "2023-02-23"
              cancelledAt: null
              initialCollateralReceivedAt: "2023-01-20"
              fundsReceivedAt: null
              completedAt: null
              completedAtTs: null
              overdueAt: "2023-02-23"
              settlementAt: "2023-02-23"
              settlementType: full
              adjustedMtmChangePct: 0.85
              adjustedMtmChangeTs: 1674057600
              spotRate: 0.9091
      required:
        - id
        - issuedAt
        - customerId
        - functionalCurrency
        - fromCurrency
        - toCurrency
        - rate
        - hedges
      type: object
      additionalProperties: false
    CancelDualHedgeResponseBody:
      description: The response of cancelling a dual hedge.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the dual hedge within the Grain platform.
          example: bf77890b-17e2-48a1-9198-707df23eb127
        transactionId:
          $ref: "#/components/schemas/UUID"
          description: The id of the transaction within the Grain platform.
          example: bf77890b-17e2-48a1-2013-707df23eb111
        hedgeIds:
          items:
            $ref: "#/components/schemas/UUID"
          type: array
          description: The ids of the individual hedges that were cancelled as part of this dual hedge.
          example:
            - bf77890b-17e2-48a1-2013-707df23eb222
            - bf77890b-17e2-48a1-2013-707df23eb333
      required:
        - id
        - transactionId
        - hedgeIds
      type: object
      additionalProperties: false
    CancelDualHedgeRequestBody:
      description: The request body for cancelling a dual hedge.
      properties:
        reason:
          type: string
          description: The reason for cancelling the dual hedge.
          example: Customer requested cancellation
      type: object
      additionalProperties: false
    ListDualHedgesResponseBody:
      properties:
        dualHedges:
          items:
            $ref: "#/components/schemas/GetDualHedgeResponseBody"
          type: array
          description: A list of hedges matching the search criteria.
        pagination:
          $ref: "#/components/schemas/PaginationResponse"
      required:
        - dualHedges
        - pagination
      type: object
      additionalProperties: false
    CreatedCustomerHedgeProposalResponseBody:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the hedge proposal within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        quote:
          type: number
          format: double
          description: The rate locked by this hedge.
          example: 20.6165
        validUntilTs:
          type: number
          format: double
          description: The unix timestamp until which the hedge offer is valid.
          example: 1659625098
        endAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        initialCollateralPercentage:
          type: number
          format: double
          description: The percentage from the overall amount of collateral required to perform this hedge at inception.
          example: 5
        toCurrencyAmount:
          type: number
          format: double
          description: |-
            The amount to hedge in the toCurrency.
            If fromCurrencyAmount is provided, then toCurrencyAmount calculated as:
            `toCurrencyAmount = fromCurrencyAmount / quote`
            Only present if an amount was provided at quote time.
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: |-
            The amount to hedge in the fromCurrency.
            If toCurrencyAmount is provided, then fromCurrencyAmount calculated as:
            `fromCurrencyAmount = toCurrencyAmount * quote`
            Only present if an amount was provided at quote time.
          example: 32161.8
        fixedSide:
          $ref: "#/components/schemas/DisplayFixedSide"
          description: >-
            Indicates which currency amount was fixed (specified) when creating the quote.

            When `fixedSide` is `toCurrencyAmount`, the `toCurrencyAmount` was specified and `fromCurrencyAmount` was
            calculated.

            When `fixedSide` is `fromCurrencyAmount`, the `fromCurrencyAmount` was specified and `toCurrencyAmount` was
            calculated.

            Only present if an amount was provided at quote time.
          example: toCurrencyAmount
        externalMarkupPct:
          type:
            - number
            - "null"
          format: double
          description: |-
            The external markup percentage that should be added to this quote on top of Grain's internal pricing.
            For example, a value of 1.0 represents a 1.0% additional markup.
          example: 1
      required:
        - id
        - fromCurrency
        - toCurrency
        - quote
        - validUntilTs
        - endAt
        - initialCollateralPercentage
        - externalMarkupPct
      type: object
      additionalProperties: false
    HedgeQuoteRequestBody:
      description: Information required by Grain in order to generate a hedge proposal.
      properties:
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: |-
            Specifies the amount to hedge in the toCurrency.
            When provided, this sets fixedSide to toCurrencyAmount, and the fromCurrencyAmount is derived as:
            fromCurrencyAmount = toCurrencyAmount × quote.
            Exactly one of toCurrencyAmount or fromCurrencyAmount may be provided.
            Alternatively, neither may be provided to defer amount specification to the Accept call.
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: |-
            Specifies the amount to hedge in the fromCurrency.
            When provided, this sets fixedSide to fromCurrencyAmount, and the toCurrencyAmount is derived as:
            toCurrencyAmount = fromCurrencyAmount / quote.
            Exactly one of toCurrencyAmount or fromCurrencyAmount may be provided.
            Alternatively, neither may be provided to defer amount specification to the Accept call.
        externalMarkupPct:
          type: number
          format: double
          description: |-
            The external markup percentage that should be added to this quote on top of Grain’s internal pricing.
            For example, a value of 1.0 represents a 1.0% additional markup.
          example: 1
        endAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
      required:
        - fromCurrency
        - toCurrency
        - endAt
      type: object
      additionalProperties: false
    AcceptHedgeProposalRequestBody:
      description: Additional metadata when accepting a hedge
      properties:
        hedgeProposalId:
          type: string
          description: The id of the hedge proposal to accept.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        endAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
        toCurrencyAmount:
          type: number
          format: double
          description: |-
            Specifies the amount to hedge in the toCurrency.
            This field may be provided on Accept only if the amount was not specified on the Quote call.
            When provided, this sets fixedSide to toCurrencyAmount, and the fromCurrencyAmount is calculated as:
            fromCurrencyAmount = toCurrencyAmount × quote.
            Only one of toCurrencyAmount or fromCurrencyAmount should be provided.
        fromCurrencyAmount:
          type: number
          format: double
          description: |-
            Specifies the amount to hedge in the fromCurrency.
            This field may be provided on Accept only if the amount was not specified on the Quote call.
            When provided, this sets fixedSide to fromCurrencyAmount, and the toCurrencyAmount is calculated as:
            toCurrencyAmount = fromCurrencyAmount / quote.
            Only one of toCurrencyAmount or fromCurrencyAmount should be provided.
        externalTransactionId:
          type: string
          description: The transaction id, as identified within your system - required when creating a new hedge.
          example: 780231b3ae0d7e9e5097nd89
        extraFields:
          $ref: "#/components/schemas/ExtraFieldsParam"
      required:
        - hedgeProposalId
        - externalTransactionId
      type: object
      additionalProperties: false
      example:
        hedgeProposalId: 497f6eca-6276-4993-bfeb-53cbbbba6f08
        externalTransactionId: 780231b3ae0d7e9e5097nd89
        extraFields:
          field_a: value_a
          field_b: value_b
    AcceptOfflineHedgeResponseBody:
      description: The response of accepting an offline rate for a hedge.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the created object.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        transactionId:
          $ref: "#/components/schemas/UUID"
          description: The id of the transaction within the Grain platform.
          example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
      required:
        - id
      type: object
      additionalProperties: false
    AcceptOfflineHedgeProposalRequestBody:
      description: The required parameters when accepting an offline hedge
      properties:
        revision:
          type: number
          format: double
          description: The id of the revision that defines the accepted rate for the currency-pair and tenor.
          example: 156
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: the currency you want to buy.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: The amount to hedge in the toCurrency.
          example: 100000
        endAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the hedge will be settled, denoted in `YYYY-MM-DD` format.
          example: "2024-02-23"
        rate:
          type: number
          format: double
          description: >-
            Represents the exchange rate according to the offline map of currency pairs to tenor object.


            The calculation of the tenor is based on the difference in calendar days between the 'tenorCalculationDate'
            and the 'endAt' date:


            - If the number of calendar days from 'tenorCalculationDate' to `endAt` is less than or equal to 7, the
            tenor is 7 days.

            - If the number of calendar days from 'tenorCalculationDate' to `endAt` is greater than 7 and less than or
            equal to 14, the tenor is 14 days.

            - If the number of calendar days from 'tenorCalculationDate' to `endAt` is greater than 14 and less than or
            equal to 30, the tenor is 30 days.

            - If the number of calendar days from 'tenorCalculationDate' to `endAt` is greater than 30 and less than or
            equal to 60, the tenor is 60 days.

            - ...

            - If the number of calendar days from 'tenorCalculationDate' to `endAt` is greater than 330 and less than or
            equal to 360, the tenor is 360 days.


            When counting the difference in calendar days, every day is counted as one regardless of the duration of the
            day. This means that the calculation includes all days: weekends, holidays, and weekdays alike.


            For example, if the 'endAt' date is 2023-12-16 and the 'tenorCalculationDate' is 2024-12-15, the result is 1
            calendar day.


            To calculate the difference in calendar days accurately, we recommend using a date manipulation library,
            such as date-fns and its `differenceInCalendarDays` function, or a similar feature provided by other date
            libraries.
          example: 20.616512
        externalTransactionId:
          type: string
          description: Optional The transaction id, as identified within your system.
          example: 780231b3ae0d7e9e5097nd89
        extraFields:
          $ref: "#/components/schemas/ExtraFieldsParam"
      required:
        - revision
        - fromCurrency
        - toCurrency
        - toCurrencyAmount
        - endAt
        - rate
      type: object
      additionalProperties: false
    HedgeActionResponseBody:
      description: The response of a hedge action. Includes the reference to the relevant objects.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the created object.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        transactionId:
          $ref: "#/components/schemas/UUID"
          description: The id of the transaction within the Grain platform.
          example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
      required:
        - id
      type: object
      additionalProperties: false
    CancelHedgeRequestBody:
      properties:
        reason:
          type: string
          description: Description of the reason the hedge was canceled.
          example: Transaction cancelled by customer
      type: object
      additionalProperties: false
    EarlySettlementQuoteResponse:
      description: The response when requesting an early settlement quote for a hedge.
      properties:
        id:
          type: string
          description: The unique identifier of the early settlement proposal.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        hedgeId:
          type: string
          description: The unique identifier of the hedge associated with this proposal.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        toCurrencyAmount:
          type: number
          format: double
          description: The amount in the target currency (toCurrency).
          example: 10000
        fromCurrencyAmount:
          type: number
          format: double
          description: The amount in the source currency (fromCurrency).
          example: 10825
        quote:
          type: number
          format: double
          description: The exchange rate quote for the early settlement.
          example: 1.0825
        validUntilTs:
          type: number
          format: double
          description: The unix timestamp until which the early settlement proposal is valid.
          example: 1710510600
      required:
        - id
        - hedgeId
        - toCurrencyAmount
        - fromCurrencyAmount
        - quote
        - validUntilTs
      type: object
      additionalProperties: false
    AcceptEarlySettlementRequestBody:
      properties:
        earlySettlementProposalId:
          type: string
          description: The unique identifier of the early settlement proposal to accept.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      required:
        - earlySettlementProposalId
      type: object
      additionalProperties: false
    ListHedgesResponseBody:
      description: A response containing a list of hedges matching the search criteria.
      properties:
        hedges:
          items:
            $ref: "#/components/schemas/CustomerHedge"
          type: array
          description: A list of hedges matching the search criteria.
        pagination:
          $ref: "#/components/schemas/PaginationResponse"
      required:
        - hedges
        - pagination
      type: object
      additionalProperties: false
    SpotProposalResponseBody:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the spot proposal within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        fromCurrency:
          type: string
          description: >-
            The original currency that will be converted into a different currency. This is the currency the user wants
            to exchange or convert in the transaction.
          example: MXN
        toCurrency:
          type: string
          description: >-
            The target currency that the original currency (fromCurrency) will be converted into. This is the desired
            currency after the conversion process is complete.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the toCurrency
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the fromCurrency
          example: 32161.8
        quote:
          type: number
          format: double
          description: The rate locked by this spot.
          example: 20.6165
        validUntilTs:
          type: number
          format: double
          description: The unix timestamp until which the spot offer is valid.
          example: 1659625098
      required:
        - id
        - fromCurrency
        - toCurrency
        - quote
        - validUntilTs
      type: object
      additionalProperties: false
    SpotQuoteRequestBody:
      description: Information required by Grain in order to generate a spot quote proposal.
      properties:
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: >-
            The amount of `toCurrency` to convert, using this amount and the spot rate will determine the `fromCurrency`
            amount.
          example: 1560
      required:
        - fromCurrency
        - toCurrency
      type: object
      additionalProperties: false
    SpotActionResponseBody:
      description: The response of a spot action. Includes the reference to the relevant objects.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the created spot
          example: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
      required:
        - id
      type: object
      additionalProperties: false
    AcceptSpotProposalRequestBody:
      properties:
        spotProposalId:
          type: string
          description: The id of the spot proposal to accept.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        toCurrencyAmount:
          type: number
          format: double
          description: >-
            the amount to transfer in the toCurrency. If amount was not specified on quote, it should be specified on
            Accept.
          example: 1560
        extraFields:
          $ref: "#/components/schemas/ExtraFieldsParam"
      required:
        - spotProposalId
      type: object
      additionalProperties: false
    OrganizationSpot:
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the spot within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        organizationId:
          $ref: "#/components/schemas/UUID"
          description: The id of the organization that perform the spot within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        fromCurrency:
          type: string
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          type: string
          description: The currency in which the inventory item is listed at on your platform.
          example: USD
        toCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the toCurrency
          example: 1560
        fromCurrencyAmount:
          type: number
          format: double
          description: The amount to transfer in the fromCurrency
          example: 32161.8
        quote:
          type: number
          format: double
          description: The rate locked by this spot.
          example: 20.6165
        acceptedAtTs:
          type: number
          format: double
          description: The unix timestamp in which the spot offer was accepted (if it was).
          example: 1659625088
        issuedAt:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date in which the spot was issued, denoted in `YYYY-MM-DD` format.
          example: "2023-01-18"
        completedAt:
          description: The date in which the spot was completed, denoted in `YYYY-MM-DD` format.
          example: "2023-02-23"
          oneOf:
            - $ref: "#/components/schemas/GrainDateFormat"
            - type: "null"
      required:
        - id
        - organizationId
        - fromCurrency
        - toCurrency
        - toCurrencyAmount
        - fromCurrencyAmount
        - quote
        - acceptedAtTs
        - issuedAt
        - completedAt
      type: object
      additionalProperties: false
    ListSpotsResponseBody:
      properties:
        spots:
          items:
            $ref: "#/components/schemas/OrganizationSpot"
          type: array
          description: A list of spots matching the search criteria.
        pagination:
          $ref: "#/components/schemas/PaginationResponse"
      required:
        - spots
        - pagination
      type: object
      additionalProperties: false
    InnerDualRateByTenor:
      properties:
        "7":
          type: number
          format: double
        "14":
          type: number
          format: double
        "30":
          type: number
          format: double
        "60":
          type: number
          format: double
        "90":
          type: number
          format: double
        "120":
          type: number
          format: double
        "150":
          type: number
          format: double
        "180":
          type: number
          format: double
        "210":
          type: number
          format: double
        "240":
          type: number
          format: double
        "270":
          type: number
          format: double
        "300":
          type: number
          format: double
        "330":
          type: number
          format: double
        "360":
          type: number
          format: double
      required:
        - "7"
      type: object
    IPartnerDualRatesByTenorResponse:
      properties: {}
      additionalProperties:
        properties:
          "7":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "14":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "30":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "60":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "90":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "120":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "150":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "180":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "210":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "240":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "270":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "300":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "330":
            $ref: "#/components/schemas/InnerDualRateByTenor"
          "360":
            $ref: "#/components/schemas/InnerDualRateByTenor"
        required:
          - "360"
          - "330"
          - "300"
          - "270"
          - "240"
          - "210"
          - "180"
          - "150"
          - "120"
          - "90"
          - "60"
          - "30"
          - "14"
          - "7"
        type: object
      type: object
      example:
        USDMXN:
          "7":
            "7": 20.417557
          "14":
            "7": 20.4176
            "14": 20.43836
          "30":
            "7": 20.41811
            "14": 20.43955
            "30": 20.48901
          "60":
            "7": 20.419121
            "14": 20.44655
            "30": 20.49801
            "60": 20.57601
          "90":
            "7": 20.431121
            "14": 20.469955
            "30": 20.49901
            "60": 20.588101
            "90": 20.655895
          "120":
            "7": 20.445421
            "14": 20.488955
            "30": 20.52212
            "60": 20.588101
            "90": 20.675295
            "120": 20.736896
          "150":
            "7": 20.467231
            "14": 20.491052
            "30": 20.58913
            "60": 20.628103
            "90": 20.696212
            "120": 20.756834
            "150": 20.820784
          "180":
            "7": 20.485262
            "14": 20.511089
            "30": 20.599162
            "60": 20.658111
            "90": 20.7262189
            "120": 20.776855
            "150": 20.850123
            "180": 20.895173
          "210":
            "7": 20.495427
            "14": 20.531376
            "30": 20.61911
            "60": 20.673787
            "90": 20.746512
            "120": 20.79001
            "150": 20.868908
            "180": 20.9017322
            "210": 20.982573
          "240":
            "7": 20.501275
            "14": 20.568922
            "30": 20.638009
            "60": 20.689201
            "90": 20.7589105
            "120": 20.815097
            "150": 20.88991
            "180": 20.9416654
            "210": 20.999219
            "240": 21.064359
          "270":
            "7": 20.533312
            "14": 20.5701129
            "30": 20.645689
            "60": 20.70933
            "90": 20.7820018
            "120": 20.845088
            "150": 20.91334
            "180": 20.97550416
            "210": 21.027219
            "240": 21.087219
            "270": 21.127955
          "300":
            "7": 20.56772
            "14": 20.5998477
            "30": 20.66901
            "60": 20.72901
            "90": 20.8001
            "120": 20.86501
            "150": 20.92501
            "180": 20.98501
            "210": 21.04501
            "240": 21.10501
            "270": 21.16501
            "300": 21.208609
          "330":
            "7": 20.59811
            "14": 20.612275
            "30": 20.67901
            "60": 20.73901
            "90": 20.8101
            "120": 20.87501
            "150": 20.935056
            "180": 20.9950551
            "210": 21.0450199
            "240": 21.1050123
            "270": 21.1650154
            "300": 21.225019
            "330": 21.268019
          "360":
            "7": 20.62459
            "14": 20.629922
            "30": 20.68901
            "60": 20.74901
            "90": 20.8201
            "120": 20.887716
            "150": 20.94701
            "180": 21.00701
            "210": 21.06701
            "240": 21.12701
            "270": 21.18701
            "300": 21.24701
            "360": 21.28701
      description: >-
        Dual rates information organized by currency pairs and tenors.

        The structure includes currency pairs as keys, each associated with a nested object containing tenors and
        corresponding rate.
    GetOfflineDualRatesResponse:
      properties:
        functionalCurrency:
          type: string
          description: Represent the functional currency of the partner.
          example: EUR
        tenorCalculationDate:
          type: string
          description: >-
            Date in ISO 8601 format yyyy-MM-dd.

            This is the date that will be used to calculate the difference in days between the offline revision creation
            date and the hedge future endAt date.

            The difference in days will be used to find the right tenor in the offline table.
          example: "2023-12-21"
        validUntilTs:
          type: number
          format: double
          description: |-
            Unix timestamp of expiration for the specific revision.
            Indicates the maximum duration during which this revision is valid for accepting hedge requests.
          example: 1703770471
        rates:
          $ref: "#/components/schemas/IPartnerDualRatesByTenorResponse"
        revision:
          type: number
          format: double
          description: Unique identifier for the offline rates revision. This id is used later to accept an offline rate.
          example: 156
      required:
        - functionalCurrency
        - tenorCalculationDate
        - validUntilTs
        - rates
        - revision
      type: object
      description: >-
        Represents the response of an offline dual rates request, including a revision snapshot with a time-to-live
        (TTL) indicating validity.

        Rates are organized by currency pair, with each pair associated with rates for various tenors.
    OfflineRatesInvalidRequestError:
      description: An API Error
      properties:
        message:
          type: string
          description: A short code of the error.
          example: CURRENCY_PAIRS_INVALID
        reason:
          type: string
          description: A detailed description of the reason for the failure.
          example: >-
            Invalid format for the 'pairs' parameter. Each pair must include two currencies concatenated, and multiple
            pairs should be comma-separated. eg: EURUSD,GBPUSD
      required:
        - message
      type: object
      additionalProperties: false
    IPartnerRatesByTenorResponse:
      properties: {}
      additionalProperties:
        properties:
          "7":
            type: number
            format: double
          "14":
            type: number
            format: double
          "30":
            type: number
            format: double
          "60":
            type: number
            format: double
          "90":
            type: number
            format: double
          "120":
            type: number
            format: double
          "150":
            type: number
            format: double
          "180":
            type: number
            format: double
          "210":
            type: number
            format: double
          "240":
            type: number
            format: double
          "270":
            type: number
            format: double
          "300":
            type: number
            format: double
          "330":
            type: number
            format: double
          "360":
            type: number
            format: double
        required:
          - "360"
          - "330"
          - "300"
          - "270"
          - "240"
          - "210"
          - "180"
          - "150"
          - "120"
          - "90"
          - "60"
          - "30"
          - "14"
          - "7"
        type: object
      type: object
      example:
        USDEUR:
          "7": 1.11293728
          "14": 1.12093476
          "30": 1.10384729
          "60": 1.09723456
          "90": 1.08576234
          "120": 1.07456321
          "150": 1.06781234
          "180": 1.05678901
          "210": 1.0456789
          "240": 1.03456789
          "270": 1.02345678
          "300": 1.01234567
          "330": 1.00987654
          "360": 0.99876543
        USDGBP:
          "7": 1.27987654
          "14": 1.26876543
          "30": 1.28123456
          "60": 1.29345678
          "90": 1.30098765
          "120": 1.31456789
          "150": 1.32456789
          "180": 1.33678901
          "210": 1.34789012
          "240": 1.35890123
          "270": 1.36901234
          "300": 1.37123456
          "330": 1.38234567
          "360": 1.39456789
      description: >-
        Rates information organized by currency pairs and tenors.

        The structure includes currency pairs as keys, each associated with a nested object containing tenors and
        corresponding rate.
    GetOfflineRatesResponse:
      properties:
        tenorCalculationDate:
          type: string
          description: >-
            Date in ISO 8601 format yyyy-MM-dd.

            This is the date that will be used to calculate the difference in days between the offline revision creation
            date and the hedge future endAt date.

            The difference in days will be used to find the right tenor in the offline table.
          example: "2023-12-21"
        validUntilTs:
          type: number
          format: double
          description: |-
            Unix timestamp of expiration for the specific revision.
            Indicates the maximum duration during which this revision is valid for accepting hedge requests.
          example: 1703770471
        rates:
          $ref: "#/components/schemas/IPartnerRatesByTenorResponse"
        revision:
          type: number
          format: double
          description: Unique identifier for the offline rates revision. This id is used later to accept an offline rate.
          example: 156
      required:
        - tenorCalculationDate
        - validUntilTs
        - rates
        - revision
      type: object
      description: >-
        Represents the response of an offline rates request, including a revision snapshot with a time-to-live (TTL)
        indicating validity.

        Rates are organized by currency pair, with each pair associated with rates for various tenors.
    ExternalPayoutId:
      type: string
      example: inv_2026_001
      description: Partner's own reference number for this payout.
      pattern: ^[A-Za-z0-9_.\-]{1,64}$
    CurrencyCode:
      type: string
      example: EUR
      description: The alpha-3 ISO 4217 currency code of the related entity.
      pattern: ^[A-Za-z]{3}$
    ComplianceReasonCode:
      description: |-
        The compliance reason categorising a payout, as a numeric code:

        1 - Intercompany Payment
        2 - Purchase of Good(s)
        3 - Purchase of Service(s)
        4 - Transferring to Own Accounts
        5 - Valid Vendor Purchases
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
      type: number
    DisplayPaymentMethod:
      enum:
        - SWIFT
        - SEPA
        - WIRE
        - ACH
        - FPS
        - EFT
        - NPP
        - IBG
        - BECS
        - CCASS
        - SPEI
      type: string
    ExternalVendorId:
      type: string
      example: vendor_001
      description: Partner's own reference ID for the vendor.
      pattern: ^[A-Za-z0-9_.\-]{1,64}$
    VendorBankDetails:
      description: Bank account details of a vendor receiving a payout.
      properties:
        accountHolderName:
          type: string
          description: The full legal name of the account holder.
          example: Acme Payments Ltd
        accountNumber:
          type: string
          description: The account number.
          example: "8290041523"
        bankName:
          type: string
          description: The name of the bank holding the account.
          example: JPMorgan Chase Bank, N.A.
        bankAddress:
          type: string
          description: The full address of the bank.
          example: 383 Madison Avenue, New York, NY 10017
        bankCountry:
          type: string
          description: The alpha-2 ISO 3166 country code of the bank.
          example: US
          pattern: ^[A-Za-z]{2}$
        bankState:
          type: string
          description: The state/region of the bank's location, when applicable.
          example: NY
        iban:
          type: string
          description: The IBAN of the account, when applicable.
          pattern: ^[A-Z0-9]{15,34}$
        bicSwift:
          type: string
          description: The SWIFT/BIC code of the bank, when applicable.
          example: CHASUS33XXX
          pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
        routingCode:
          type: string
          description: |-
            Country-specific routing code (e.g. IFSC for India, CLABE for Mexico, Canadian transit), when applicable.
            For US ACH and wire, see `achRoutingCode` / `wireRoutingCode` on wallet responses.
        bankCode:
          type: string
          description: Country-specific bank code, when applicable.
        branchCode:
          type: string
          description: Country-specific branch code, when applicable.
        sortCode:
          type: string
          description: UK sort code, when applicable. Six digits, no hyphens.
          example: "560036"
          pattern: ^\d{6}$
        bsbCode:
          type: string
          description: Australian BSB code, when applicable. Six digits, no hyphens.
          example: "082902"
          pattern: ^\d{6}$
      required:
        - accountHolderName
        - accountNumber
        - bankName
        - bankAddress
        - bankCountry
      type: object
      additionalProperties: false
    PayoutVendorDetails:
      description: The vendor receiving the payout, including their bank account details.
      properties:
        vendorId:
          $ref: "#/components/schemas/UUID"
          description: The id of the vendor within the Grain platform.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        vendorName:
          type: string
          description: The name of the vendor.
          example: Acme Supplies Ltd
        externalVendorId:
          $ref: "#/components/schemas/ExternalVendorId"
          description: The vendor id, as identified within your system.
        bankDetails:
          $ref: "#/components/schemas/VendorBankDetails"
          description: Bank account details to which the payout will be sent.
      required:
        - vendorId
        - vendorName
        - externalVendorId
        - bankDetails
      type: object
      additionalProperties: false
    PayoutProposalResponse:
      description: |-
        A pending payout proposal, returned by `POST /v1/payouts` (review). Submit it via
        `POST /v1/payouts/{id}/submit` to execute the payout.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the payout proposal within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        externalPayoutId:
          $ref: "#/components/schemas/ExternalPayoutId"
          description: The payout id, as identified within your system.
        currency:
          $ref: "#/components/schemas/CurrencyCode"
          description: The alpha-3 ISO 4217 currency code of the payout.
          example: USD
        amount:
          type: number
          format: double
          description: The payout amount, denoted in `currency`.
          example: 5000
        fee:
          type: number
          format: double
          description: The fee applied to this payout, denoted in `currency`.
          example: 1.5
        totalAmount:
          type: number
          format: double
          description: Total amount that will leave the wallet (`amount + fee`), denoted in `currency`.
          example: 5001.5
        reason:
          $ref: "#/components/schemas/ComplianceReasonCode"
          description: |-
            The compliance reason categorising this payout, as a numeric code:

            1 - Intercompany Payment
            2 - Purchase of Good(s)
            3 - Purchase of Service(s)
            4 - Transferring to Own Accounts
            5 - Valid Vendor Purchases
          example: 2
        description:
          type:
            - string
            - "null"
          description: Free-form description supplied when initiating the payout.
        validUntilTs:
          type: number
          format: double
          description: When the proposal expires if not submitted, as a Unix timestamp in seconds.
          example: 1779805920
        payoutMethod:
          $ref: "#/components/schemas/DisplayPaymentMethod"
          description: The payment method that will be used to send the payout.
          example: SEPA
        vendorDetails:
          $ref: "#/components/schemas/PayoutVendorDetails"
          description: The vendor receiving the payout, including their bank account details.
      required:
        - id
        - externalPayoutId
        - currency
        - amount
        - fee
        - totalAmount
        - reason
        - description
        - validUntilTs
        - payoutMethod
        - vendorDetails
      type: object
      additionalProperties: false
    InitiatePayoutRequest:
      description: |-
        Request body for `POST /v1/payouts` (review). Creates a pending, time-limited payout proposal
        that must be submitted via `POST /v1/payouts/{id}/submit` before it expires.
      properties:
        externalVendorId:
          $ref: "#/components/schemas/ExternalVendorId"
          description: Your own reference id for the vendor receiving the payout.
        externalPayoutId:
          $ref: "#/components/schemas/ExternalPayoutId"
          description: Your own reference number for this payout.
        currency:
          $ref: "#/components/schemas/CurrencyCode"
          description: The alpha-3 ISO 4217 currency code of the payout.
          example: USD
        amount:
          type: number
          format: double
          description: The payout amount, denoted in `currency`.
          example: 5000
        reason:
          $ref: "#/components/schemas/ComplianceReasonCode"
          description: |-
            The compliance reason categorising this payout, as a numeric code:

            1 - Intercompany Payment
            2 - Purchase of Good(s)
            3 - Purchase of Service(s)
            4 - Transferring to Own Accounts
            5 - Valid Vendor Purchases
          example: 2
        description:
          type: string
          description: Optional free-form description for the payout.
          example: Payment for services
      required:
        - externalVendorId
        - externalPayoutId
        - currency
        - amount
        - reason
      type: object
      additionalProperties: false
    DisplayPayoutStatus:
      enum:
        - in_process
        - sent
        - paid
        - failed
        - rejected
      type: string
    PayoutResponse:
      description: |-
        A Payout represents an executed payment to a vendor. Returned by `GET /v1/payouts/{id}`,
        `GET /v1/payouts`, and `POST /v1/payouts/{id}/submit`.
      properties:
        id:
          $ref: "#/components/schemas/UUID"
          description: The id of the payout within the Grain platform.
          example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
        status:
          $ref: "#/components/schemas/DisplayPayoutStatus"
          description: The current status of the payout.
          example: in_process
        externalPayoutId:
          $ref: "#/components/schemas/ExternalPayoutId"
          description: The payout id, as identified within your system.
        currency:
          $ref: "#/components/schemas/CurrencyCode"
          description: The alpha-3 ISO 4217 currency code of the payout.
          example: USD
        amount:
          type: number
          format: double
          description: The payout amount, denoted in `currency`.
          example: 5000
        fee:
          type: number
          format: double
          description: The fee applied to this payout, denoted in `currency`.
          example: 1.5
        totalAmount:
          type: number
          format: double
          description: Total amount that will leave the wallet (`amount + fee`), denoted in `currency`.
          example: 5001.5
        reason:
          $ref: "#/components/schemas/ComplianceReasonCode"
          description: |-
            The compliance reason categorising this payout, as a numeric code:

            1 - Intercompany Payment
            2 - Purchase of Good(s)
            3 - Purchase of Service(s)
            4 - Transferring to Own Accounts
            5 - Valid Vendor Purchases
          example: 2
        description:
          type:
            - string
            - "null"
          description: Free-form description supplied when initiating the payout.
        payoutDate:
          $ref: "#/components/schemas/GrainDateFormat"
          description: The date the payout was sent to the bank, in `YYYY-MM-DD` format.
          example: "2026-05-15"
        payoutMethod:
          $ref: "#/components/schemas/DisplayPaymentMethod"
          description: The payment method that will be used to send the payout.
          example: SEPA
        vendorDetails:
          $ref: "#/components/schemas/PayoutVendorDetails"
          description: The vendor receiving the payout, including their bank account details.
      required:
        - id
        - status
        - externalPayoutId
        - currency
        - amount
        - fee
        - totalAmount
        - reason
        - description
        - payoutDate
        - payoutMethod
        - vendorDetails
      type: object
      additionalProperties: false
    PayoutListResponse:
      description: A paginated list of payouts.
      properties:
        payouts:
          items:
            $ref: "#/components/schemas/PayoutResponse"
          type: array
          description: A list of payouts matching the search criteria.
        pagination:
          $ref: "#/components/schemas/PaginationResponse"
      required:
        - payouts
        - pagination
      type: object
      additionalProperties: false
    SpotRates:
      properties: {}
      type: object
      additionalProperties:
        properties: {}
        additionalProperties:
          type: number
          format: double
        type: object
    SpotRatesResponseBody:
      properties:
        rates:
          $ref: "#/components/schemas/SpotRates"
      type: object
      additionalProperties: false
    ApiKeysResponse:
      properties:
        clientId:
          type: string
          description: The Client ID of the API Key
        secretKey:
          type: string
          description: The SecretKey of the API Key
      required:
        - clientId
        - secretKey
      type: object
      additionalProperties: false
    CreatePartnerResponse:
      properties:
        id:
          type: string
          description: The UUID of the created Partner.
        sandboxApiKey:
          $ref: "#/components/schemas/ApiKeysResponse"
          description: The ApiKey details for the Partners' Sandbox environment
      required:
        - id
        - sandboxApiKey
      type: object
      additionalProperties: false
    CreatePartnerRequestBody:
      properties:
        partnerName:
          type: string
          description: The display name of the Partner.
          example: Partner Inc.
        contactEmail:
          type: string
          description: The Email of Partner contact user which will be created as part of Partner Creation.
          example: yourname@company.com
        contactFirstName:
          type: string
          description: The first name of the Partner contact user.
          example: John
        contactLastName:
          type: string
          description: The last name of the Partner contact user.
          example: Doe
        contactCountry:
          type: string
          description: The ISO 2-letter country code for the contact.
          example: US
        contactCity:
          type: string
          description: The city for the contact.
          example: New York
        contactStreetName:
          type: string
          description: The street name for the contact address.
          example: 123 Main Street
        contactBuildingName:
          type: string
          description: The building name or apartment number.
          example: Suite 100
        contactPostalCode:
          type: string
          description: The postal code for the contact address.
          example: "10001"
        contactState:
          type: string
          description: The state or province (optional, ISO code when applicable).
          example: NY
        contactPhoneNumber:
          type: string
          description: The phone number for the contact (optional).
          example: "+1234567890"
        contactTaxId:
          type: string
          description: The tax ID for the contact (optional).
          example: 12-3456789
        contactWebsite:
          type: string
          description: The website URL for the contact (optional).
          example: https://example.com
      required:
        - partnerName
        - contactEmail
        - contactFirstName
        - contactLastName
        - contactCountry
        - contactCity
        - contactStreetName
        - contactBuildingName
        - contactPostalCode
      type: object
      additionalProperties: false
    OwnedPartnerConfig:
      description: Partner specific configurations
      properties:
        maxHedgeAmount:
          type: number
          format: double
          description: The maximum amount for a single hedge (in USD)
        maxExposureAmount:
          type: number
          format: double
          description: The maximum amount of all active hedges for the partner (in USD)
      required:
        - maxHedgeAmount
        - maxExposureAmount
      type: object
      additionalProperties: false
    OwnedPartner:
      properties:
        id:
          type: string
          description: The ID of the Partner in Grain's system.
        name:
          type: string
          description: The name of the Partner
        isLiveEnabled:
          type: boolean
          description: >-
            Indicates if this Partner has been fully onboarded and approved, and can perform actions in the Live
            Environment
        config:
          $ref: "#/components/schemas/OwnedPartnerConfig"
        sandboxApiKey:
          $ref: "#/components/schemas/ApiKeysResponse"
          description: The ApiKey details for the Partner's Sandbox environment
        liveApiKey:
          $ref: "#/components/schemas/ApiKeysResponse"
          description: The ApiKey details for the Partner's Live environment
      required:
        - id
        - name
        - isLiveEnabled
        - config
        - sandboxApiKey
      type: object
      additionalProperties: false
    ListOwnedPartnerResponseBody:
      description: A response containing a list of partners matching the search criteria.
      properties:
        partners:
          items:
            $ref: "#/components/schemas/OwnedPartner"
          type: array
          description: A list of partners matching the search criteria.
        pagination:
          $ref: "#/components/schemas/PaginationResponse"
      required:
        - partners
        - pagination
      type: object
      additionalProperties: false
    PartnerWalletDepositDetails:
      description: |-
        Bank account details used to deposit funds into a wallet.
        Extends the common base with wallet-specific routing codes (ACH and wire are
        returned separately for USD wallets, since the same account is reachable via both
        methods with different routing codes).
      properties:
        accountHolderName:
          type: string
          description: The full legal name of the account holder.
          example: Acme Payments Ltd
        accountNumber:
          type: string
          description: The account number.
          example: "8290041523"
        bankName:
          type: string
          description: The name of the bank holding the account.
          example: JPMorgan Chase Bank, N.A.
        bankAddress:
          type: string
          description: The full address of the bank.
          example: 383 Madison Avenue, New York, NY 10017
        bankCountry:
          type: string
          description: The alpha-2 ISO 3166 country code of the bank.
          example: US
          pattern: ^[A-Za-z]{2}$
        bankState:
          type: string
          description: The state/region of the bank's location, when applicable.
          example: NY
        iban:
          type: string
          description: The IBAN of the account, when applicable.
          pattern: ^[A-Z0-9]{15,34}$
        bicSwift:
          type: string
          description: The SWIFT/BIC code of the bank, when applicable.
          example: CHASUS33XXX
          pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$
        routingCode:
          type: string
          description: |-
            Country-specific routing code (e.g. IFSC for India, CLABE for Mexico, Canadian transit), when applicable.
            For US ACH and wire, see `achRoutingCode` / `wireRoutingCode` on wallet responses.
        bankCode:
          type: string
          description: Country-specific bank code, when applicable.
        branchCode:
          type: string
          description: Country-specific branch code, when applicable.
        sortCode:
          type: string
          description: UK sort code, when applicable. Six digits, no hyphens.
          example: "560036"
          pattern: ^\d{6}$
        bsbCode:
          type: string
          description: Australian BSB code, when applicable. Six digits, no hyphens.
          example: "082902"
          pattern: ^\d{6}$
        specialInstructions:
          type: string
          description: Free-form special instructions associated with this routing, when applicable.
        achRoutingCode:
          type: string
          description: The ACH routing code of the receiving bank, when applicable.
          example: "486478148"
          pattern: ^\d{9}$
        wireRoutingCode:
          type: string
          description: The wire routing code of the receiving bank, when applicable.
          example: "419568613"
          pattern: ^\d{9}$
      required:
        - accountHolderName
        - accountNumber
        - bankName
        - bankAddress
        - bankCountry
      type: object
      additionalProperties: false
    PartnerWallet:
      properties:
        id:
          type: string
          description: The UUID of the Wallet in Grain's system.
          example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
        totalBalance:
          type: number
          format: double
          description: The current balance, in the wallet currency.
          example: 10525
        availableBalance:
          type: number
          format: double
          description: The available balance (total minus reserved/pending amounts), in the wallet currency.
          example: 8500
        collateralAmount:
          type:
            - number
            - "null"
          format: double
          description: The collateral amount held against open hedges, in the wallet currency.
          example: 2025
        currency:
          type: string
          description: The wallet currency (ISO 4217)
          example: EUR
        depositDetails:
          $ref: "#/components/schemas/PartnerWalletDepositDetails"
          description: Account details for depositing funds to this wallet
      required:
        - id
        - totalBalance
        - availableBalance
        - collateralAmount
        - currency
        - depositDetails
      type: object
      additionalProperties: false
    WalletsResponse:
      properties:
        wallets:
          items:
            $ref: "#/components/schemas/PartnerWallet"
          type: array
          description: List of the Partner's Wallets
      required:
        - wallets
      type: object
      additionalProperties: false
    WithdrawRequestBody:
      description: Withdraw the given amount from your Grain Account to the preconfigured Payment Beneficiary
      properties:
        amount:
          type: number
          format: double
          description: The amount of the funds requested to be withdrawn.
          example: 10000
      required:
        - amount
      type: object
      additionalProperties: false
  securitySchemes:
    api-key:
      type: http
      scheme: basic
      description: Basic authentication using the partner API keys from https://console.grainfinance.co/keys
info:
  title: Grain API
  version: 1.0.0
  description: >-
    Grain's API provides a comprehensive set of endpoints for managing hedging, spot transactions, pricing, and fund
    movements - enabling seamless integration of FX workflows into your platform. Each API call follows REST
    conventions, uses secure authentication, and returns standardized responses for consistency across environments.
  license:
    name: Creative Commons Attribution 3.0
  contact:
    name: Grain Finance
    url: https://docs.grainfinance.co
    email: support@grainfinance.co
  termsOfService: https://grainfinance.co/terms-of-service/
  x-apiClientRegistration:
    url: https://grainfinance.co/partners
openapi: 3.1.0
paths:
  /customers/{customerId}/hedges/quote:
    post:
      operationId: Real-time Quote
      responses:
        "201":
          description: Hedge Proposal Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedCustomerHedgeProposalResponseBody"
              examples:
                toCurrencyAmount:
                  value:
                    id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                    fromCurrency: MXN
                    toCurrency: USD
                    quote: 20.6165
                    validUntilTs: 1659625098
                    endAt: "2023-04-15"
                    initialCollateralPercentage: 5
                    toCurrencyAmount: 1560
                    fromCurrencyAmount: 32161.8
                    fixedSide: toCurrencyAmount
                    externalMarkupPct: 1
                fromCurrencyAmount:
                  value:
                    id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                    fromCurrency: MXN
                    toCurrency: USD
                    quote: 20.6165
                    validUntilTs: 1659625098
                    endAt: "2023-04-15"
                    initialCollateralPercentage: 5
                    toCurrencyAmount: 1560
                    fromCurrencyAmount: 32161.8
                    fixedSide: fromCurrencyAmount
                    externalMarkupPct: 1
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: >-
        Generates a real-time rate proposal for a new hedge associated with the specified customer. Once accepted, this
        proposal becomes a confirmed hedge.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required in order to ask for a hedge quote
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HedgeQuoteRequestBody"
              description: The payload required in order to ask for a hedge quote
            examples:
              toCurrencyAmount:
                value:
                  fromCurrency: MXN
                  toCurrency: USD
                  toCurrencyAmount: 1560
                  externalMarkupPct: 1
                  endAt: "2023-02-23"
              fromCurrencyAmount:
                value:
                  fromCurrency: MXN
                  toCurrency: USD
                  fromCurrencyAmount: 25000
                  externalMarkupPct: 1
                  endAt: "2023-02-23"
  /customers/{customerId}/hedges/accept-quote:
    post:
      operationId: Real-time Accept
      responses:
        "200":
          description: Hedge Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerHedge"
              examples:
                CollectionHedge:
                  value:
                    id: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
                    customerId: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
                    status: Active
                    transactionId: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
                    externalTransactionId: 780231b3ae0d7e9e5097nd89
                    fromCurrency: MXN
                    toCurrency: USD
                    externalCustomerId: 630231b3ae0d7e9e5097ad35
                    toCurrencyAmount: 1560
                    fromCurrencyAmount: 32161.8
                    fixedSide: toCurrencyAmount
                    initialCollateralAmount: 1608.09
                    quote: 20.6165
                    externalMarkupPct: 1
                    acceptedAtTs: 1674057600
                    issuedAt: "2023-01-18"
                    endAt: "2023-02-23"
                    updatedAt: "2023-01-18"
                    cancelledAt: null
                    initialCollateralReceivedAt: null
                    fundsReceivedAt: null
                    completedAt: null
                    completedAtTs: null
                    overdueAt: "2023-02-28"
                    settlementAt: "2023-02-23"
                    settlementType: full
                    adjustedMtmChangePct: 1.25
                    adjustedMtmChangeTs: 1674144000
                OffsetHedge:
                  value:
                    id: 9284c0b8-ff72-524f-c0f4-8d15c3b178d6
                    customerId: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
                    status: Active
                    transactionId: 5e89bd76-3d4g-58f3-9cg4-4g87235f0e38
                    externalTransactionId: 891342c4bf1e8f0f6198oe90
                    fromCurrency: EUR
                    toCurrency: USD
                    externalCustomerId: 630231b3ae0d7e9e5097ad35
                    toCurrencyAmount: 5000
                    fromCurrencyAmount: 4650.5
                    fixedSide: toCurrencyAmount
                    initialCollateralAmount: 232.53
                    quote: 1.0751
                    externalMarkupPct: 1
                    acceptedAtTs: 1674057600
                    issuedAt: "2023-01-18"
                    endAt: "2023-02-23"
                    updatedAt: "2023-01-18"
                    cancelledAt: null
                    initialCollateralReceivedAt: null
                    fundsReceivedAt: null
                    completedAt: null
                    completedAtTs: null
                    overdueAt: "2023-02-28"
                    settlementAt: "2023-02-23"
                    settlementType: offset
                    adjustedMtmChangePct: -0.89
                    adjustedMtmChangeTs: 1674144000
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "428":
          description: The request failed because a required precondition was not provided.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Accepts a previously generated real-time rate proposal and creates the hedge transaction.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required in order to accept a hedge
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AcceptHedgeProposalRequestBody"
              description: The payload required in order to accept a hedge
            example:
              hedgeProposalId: 497f6eca-6276-4993-bfeb-53cbbbba6f08
              externalTransactionId: 780231b3ae0d7e9e5097nd89
              extraFields:
                field_a: value_a
                field_b: value_b
  /offline-rates:
    get:
      operationId: Offline Quotes
      responses:
        "200":
          description: Offline Rates Retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetOfflineRatesResponse"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfflineRatesInvalidRequestError"
        "500":
          description: The request failed because an internal server error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: >-
        Retrieves offline hedge quote proposals for selected currency pairs. Partners can use these pre-fetched
        proposals - avoiding the need for a real-time quote per transaction.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: |-
            Optional query parameter specifying currency pairs.
            Multiple pairs can be provided as a comma-separated list.
            Please encode the query param beforehand.
            For example, ?pairs=EURUSD%2CGBPEUR represents ?pairs=EURUSD,GBPEUR
          in: query
          name: pairs
          required: false
          schema:
            type: string
  /customers/{customerId}/hedges/accept-offline-quote:
    post:
      operationId: Offline Accept
      responses:
        "200":
          description: Hedge Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptOfflineHedgeResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptOfflineHedgeBadParamsErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptOfflineHedgeRevisionExpiredErrorResponse"
        "428":
          description: The request failed because a required precondition was not provided.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Accepts a previously retrieved offline rate proposal and books the hedge accordingly.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required in order to accept an offline quote hedge
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AcceptOfflineHedgeProposalRequestBody"
              description: The payload required in order to accept an offline quote hedge
  /customers/{customerId}/hedges/{hedgeId}:
    get:
      operationId: Get
      responses:
        "200":
          description: Hedge Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerHedge"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves detailed information for a specific hedge.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: The id of the hedge within the Grain platform.
          in: path
          name: hedgeId
          required: true
          schema:
            type: string
  /customers/{customerId}/hedges/{hedgeId}/cancel:
    post:
      operationId: Cancel
      responses:
        "200":
          description: Hedge Cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HedgeActionResponseBody"
        "401":
          description: Authentication failed due to missing authorization header, or invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Cancels an existing hedge.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: The id of the hedge within the Grain platform.
          in: path
          name: hedgeId
          required: true
          schema:
            type: string
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CancelHedgeRequestBody"
  /customers/{customerId}/hedges:
    get:
      operationId: List
      responses:
        "200":
          description: Hedges List for Customer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListHedgesResponseBody"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves all hedges associated with the given customer.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: page number indicating which set of items to return
          in: query
          name: page
          required: false
          schema:
            $ref: "#/components/schemas/Page"
        - description: The number of items in a page
          in: query
          name: per_page
          required: false
          schema:
            $ref: "#/components/schemas/PerPage"
  /dual-hedge-offline-rates:
    get:
      operationId: Offline Quotes
      responses:
        "200":
          description: Offline Dual Rates Retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetOfflineDualRatesResponse"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Authentication failed due to missing authorization header, or invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfflineRatesInvalidRequestError"
        "500":
          description: The request failed because an internal server error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: >-
        Returns a full table of dual hedge rate proposals for all configured currency pairs. Each rate represents a pair
        of customer and supplier leg proposals routed through the functional currency. Partners can pre-fetch and cache
        these rates for both legs.
      tags:
        - Dual Hedges
      security:
        - api-key: []
      parameters:
        - description: |-
            Optional query parameter specifying currency pairs.
            Multiple pairs can be provided as a comma-separated list.
            Please encode the query param beforehand.
            For example, ?pairs=EURUSD%2CGBPEUR represents ?pairs=EURUSD,GBPEUR
          in: query
          name: pairs
          required: false
          schema:
            type: string
  /customers/{customerId}/dual-hedges/accept-offline-quote:
    post:
      operationId: Offline Accept
      responses:
        "200":
          description: Dual Hedge Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptOfflineDualHedgeResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptOfflineHedgeBadParamsErrorResponse"
        "401":
          description: Authentication failed due to missing authorization header, or invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptOfflineHedgeRevisionExpiredErrorResponse"
        "428":
          description: The request failed because a required precondition was not provided.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: >-
        Accepts a dual hedge rate proposal and books both customer and supplier hedge legs at their proposed rates and
        tenors.
      tags:
        - Dual Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required to accept an offline quote for a dual hedge
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AcceptOfflineDualHedgeProposalRequestBody"
              description: The payload required to accept an offline quote for a dual hedge
  /customers/{customerId}/dual-hedges/{dualHedgeId}:
    get:
      operationId: Get
      responses:
        "200":
          description: Dual Hedge Retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetDualHedgeResponseBody"
        "401":
          description: Authentication failed due to missing authorization header, or invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves details of a specific dual hedge, including both underlying legs and their respective proposals.
      tags:
        - Dual Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: The id of the dual hedge within the Grain platform.
          in: path
          name: dualHedgeId
          required: true
          schema:
            type: string
  /customers/{customerId}/dual-hedges/{dualHedgeId}/cancel:
    post:
      operationId: Cancel
      responses:
        "200":
          description: Dual Hedge Cancelled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelDualHedgeResponseBody"
        "401":
          description: Authentication failed due to missing authorization header, or invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Cancels a dual hedge and its underlying customer and supplier legs.
      tags:
        - Dual Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: The id of the dual hedge within the Grain platform.
          in: path
          name: dualHedgeId
          required: true
          schema:
            type: string
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CancelDualHedgeRequestBody"
  /customers/{customerId}/dual-hedges:
    get:
      operationId: List
      responses:
        "200":
          description: Dual Hedges List for Customer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDualHedgesResponseBody"
        "401":
          description: Authentication failed due to missing authorization header, or invalid authentication credentials.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: >-
        Lists all dual hedge transactions for the partner, including both hedge legs. Supports filtering by creation or
        update date.
      tags:
        - Dual Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: Page number indicating which set of items to return
          in: query
          name: page
          required: false
          schema:
            $ref: "#/components/schemas/Page"
        - description: The number of items in a page
          in: query
          name: per_page
          required: false
          schema:
            $ref: "#/components/schemas/PerPage"
        - description: "Creation date filter - only dual hedges created on this date will be returned. Format: YYYY-MM-DD"
          in: query
          name: issued_at
          required: false
          schema:
            type: string
        - description: "Update date filter - only dual hedges updated on this date will be returned. Format: YYYY-MM-DD"
          in: query
          name: updated_at
          required: false
          schema:
            type: string
  /customers:
    post:
      operationId: Create
      responses:
        "200":
          description: Customer Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateObjectResponseBody"
        "201":
          description: Customer Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateObjectResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: >-
        Creates a new customer. If a customer with the same external ID already exists, the record is updated
        automatically.
      tags:
        - Customers
      security:
        - api-key: []
      parameters: []
      requestBody:
        description: The payload required in order to create a customer
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateCustomerRequestBody"
              description: The payload required in order to create a customer
    get:
      operationId: List
      responses:
        "200":
          description: Customer Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListCustomersResponseBody"
      description: Retrieves a list of all existing customers.
      tags:
        - Customers
      security:
        - api-key: []
      parameters:
        - description: external_customer_id is the customer id, as identified within your system
          in: query
          name: external_customer_id
          required: false
          schema:
            type: string
        - description: page number indicating which set of items to return
          in: query
          name: page
          required: false
          schema:
            $ref: "#/components/schemas/Page"
        - description: The number of items in a page
          in: query
          name: per_page
          required: false
          schema:
            $ref: "#/components/schemas/PerPage"
  /customers/{customerId}:
    get:
      operationId: Get
      responses:
        "200":
          description: Customer Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves a specific customer by its Grain customer ID.
      tags:
        - Customers
      security:
        - api-key: []
      parameters:
        - description: The UUID of the customer
          in: path
          name: customerId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
    delete:
      operationId: Delete
      responses:
        "204":
          description: Customer has been Deleted
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Removes a customer by ID.
      tags:
        - Customers
      security:
        - api-key: []
      parameters:
        - description: The UUID of the customer
          in: path
          name: customerId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
  /customers/{customerId}/update:
    post:
      operationId: Update
      responses:
        "204":
          description: Customer has been Updated
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Updates an existing customer's information.
      tags:
        - Customers
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
      requestBody:
        description: The payload required in order to update a customer
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Partial_CreateUpdateCustomerRequestBody_"
              description: The payload required in order to update a customer
  /rates/currency-pairs-exchange-rate:
    get:
      operationId: Rate
      responses:
        "200":
          description: Currency Pairs Exchange Rate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpotRatesResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptOfflineHedgeBadParamsErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: The request failed because an internal server error occurred.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: >-
        Retrieves the current FX spot rate for supported currency pairs. Use this endpoint for real-time reference rates
        or live rate display.
      tags:
        - Pricing
      security:
        - api-key: []
      parameters:
        - description: (Optional) A query parameter specifying a comma-separated list of 3-letter ISO currency codes.
          in: query
          name: currencies
          required: false
          schema:
            type: string
  /spots/quote:
    post:
      operationId: Quote
      responses:
        "201":
          description: Spot Proposal Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpotProposalResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Generates a spot rate proposal for a new currency conversion.
      tags:
        - Spots
      security:
        - api-key: []
      parameters:
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required in order to ask for a spot quote
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpotQuoteRequestBody"
              description: The payload required in order to ask for a spot quote
  /spots/accept-quote:
    post:
      operationId: Accept
      responses:
        "200":
          description: Spot Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpotActionResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Accepts a previously generated spot rate proposal and executes the conversion.
      tags:
        - Spots
      security:
        - api-key: []
      parameters:
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required in order to accept a spot
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AcceptSpotProposalRequestBody"
              description: The payload required in order to accept a spot
  /spots/{spotId}:
    get:
      operationId: Get
      responses:
        "200":
          description: Spot Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationSpot"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves details of a specific spot transaction.
      tags:
        - Spots
      security:
        - api-key: []
      parameters:
        - description: The id of the spot within the Grain platform.
          in: path
          name: spotId
          required: true
          schema:
            type: string
  /spots:
    get:
      operationId: List
      responses:
        "200":
          description: Spot List for Organization
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListSpotsResponseBody"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves all spot transactions for the given organization.
      tags:
        - Spots
      security:
        - api-key: []
      parameters:
        - description: page number indicating which set of items to return
          in: query
          name: page
          required: false
          schema:
            $ref: "#/components/schemas/Page"
        - description: The number of items in a page
          in: query
          name: per_page
          required: false
          schema:
            $ref: "#/components/schemas/PerPage"
  /conversions/quote:
    post:
      operationId: Quote
      responses:
        "201":
          description: Conversion Proposal Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversionProposalResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Generates a conversion rate proposal for a new currency conversion.
      tags:
        - Conversions
      security:
        - api-key: []
      parameters:
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required in order to ask for a conversion quote
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConversionQuoteRequestBody"
              description: The payload required in order to ask for a conversion quote
  /conversions/accept-quote:
    post:
      operationId: Accept
      responses:
        "200":
          description: Conversion Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversionActionResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "451":
          description: The request failed due to legal restrictions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectedByIPError"
      description: Accepts a previously generated conversion rate proposal and executes the conversion.
      tags:
        - Conversions
      security:
        - api-key: []
      parameters:
        - in: header
          name: X-Customer-IP
          required: true
          schema:
            $ref: "#/components/schemas/CustomerIP"
      requestBody:
        description: The payload required in order to accept a conversion
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AcceptConversionProposalRequestBody"
              description: The payload required in order to accept a conversion
  /conversions/{conversionId}:
    get:
      operationId: Get
      responses:
        "200":
          description: Conversion Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationConversion"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves details of a specific conversion transaction.
      tags:
        - Conversions
      security:
        - api-key: []
      parameters:
        - description: The id of the conversion within the Grain platform.
          in: path
          name: conversionId
          required: true
          schema:
            type: string
  /conversions:
    get:
      operationId: List
      responses:
        "200":
          description: Conversion List for Organization
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListConversionsResponseBody"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves all conversion transactions for the given organization.
      tags:
        - Conversions
      security:
        - api-key: []
      parameters:
        - description: page number indicating which set of items to return
          in: query
          name: page
          required: false
          schema:
            $ref: "#/components/schemas/Page"
        - description: The number of items in a page
          in: query
          name: per_page
          required: false
          schema:
            $ref: "#/components/schemas/PerPage"
  /customers/{customerId}/hedges/{hedgeId}/early-settlement/quote:
    post:
      operationId: Early Settlement Quote
      responses:
        "201":
          description: Early Settlement Proposal Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EarlySettlementQuoteResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Request an early settlement quote for an existing hedge.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: The id of the hedge within the Grain platform.
          in: path
          name: hedgeId
          required: true
          schema:
            type: string
  /customers/{customerId}/hedges/{hedgeId}/early-settlement/accept:
    post:
      operationId: Early Settlement Accept
      responses:
        "200":
          description: Early Settlement Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerHedge"
              examples:
                CollectionHedge:
                  value:
                    id: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5
                    customerId: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
                    status: Active
                    transactionId: 4d78ac65-2c3f-47e2-8bf3-3f76124e9d27
                    externalTransactionId: 780231b3ae0d7e9e5097nd89
                    fromCurrency: MXN
                    toCurrency: USD
                    externalCustomerId: 630231b3ae0d7e9e5097ad35
                    toCurrencyAmount: 1560
                    fromCurrencyAmount: 32161.8
                    fixedSide: toCurrencyAmount
                    initialCollateralAmount: 1608.09
                    quote: 20.6165
                    externalMarkupPct: 1
                    acceptedAtTs: 1674057600
                    issuedAt: "2023-01-18"
                    endAt: "2023-02-23"
                    updatedAt: "2023-01-18"
                    cancelledAt: null
                    initialCollateralReceivedAt: null
                    fundsReceivedAt: null
                    completedAt: null
                    completedAtTs: null
                    overdueAt: "2023-02-28"
                    settlementAt: "2023-02-23"
                    settlementType: full
                    adjustedMtmChangePct: 1.25
                    adjustedMtmChangeTs: 1674144000
                OffsetHedge:
                  value:
                    id: 9284c0b8-ff72-524f-c0f4-8d15c3b178d6
                    customerId: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
                    status: Active
                    transactionId: 5e89bd76-3d4g-58f3-9cg4-4g87235f0e38
                    externalTransactionId: 891342c4bf1e8f0f6198oe90
                    fromCurrency: EUR
                    toCurrency: USD
                    externalCustomerId: 630231b3ae0d7e9e5097ad35
                    toCurrencyAmount: 5000
                    fromCurrencyAmount: 4650.5
                    fixedSide: toCurrencyAmount
                    initialCollateralAmount: 232.53
                    quote: 1.0751
                    externalMarkupPct: 1
                    acceptedAtTs: 1674057600
                    issuedAt: "2023-01-18"
                    endAt: "2023-02-23"
                    updatedAt: "2023-01-18"
                    cancelledAt: null
                    initialCollateralReceivedAt: null
                    fundsReceivedAt: null
                    completedAt: null
                    completedAtTs: null
                    overdueAt: "2023-02-28"
                    settlementAt: "2023-02-23"
                    settlementType: offset
                    adjustedMtmChangePct: -0.89
                    adjustedMtmChangeTs: 1674144000
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: The request failed because one or more preconditions were not met.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Accepts a previously generated early settlement quote and performs the early settlement.
      tags:
        - Hedges
      security:
        - api-key: []
      parameters:
        - description: The id of the customer within the Grain platform.
          in: path
          name: customerId
          required: true
          schema:
            type: string
        - description: The id of the hedge within the Grain platform.
          in: path
          name: hedgeId
          required: true
          schema:
            type: string
      requestBody:
        description: The payload required to accept an early settlement proposal
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AcceptEarlySettlementRequestBody"
              description: The payload required to accept an early settlement proposal
  /payouts:
    post:
      operationId: Review
      responses:
        "201":
          description: Payout created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutProposalResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: |-
        Reviews a payout by creating a pending, time-limited proposal. The proposal must be submitted
        via `POST /v1/payouts/{id}/submit` to execute the payment. No funds are moved
        at this step.
      tags:
        - Payouts
      security:
        - api-key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InitiatePayoutRequest"
    get:
      operationId: List
      responses:
        "200":
          description: Payouts found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutListResponse"
      description: |-
        Lists payouts for the partner, most recent first. Supports filtering by status, currency, vendor,
        payout reference, and payout-date range.
      tags:
        - Payouts
      security:
        - api-key: []
      parameters:
        - description: Filter by payout status.
          in: query
          name: status
          required: false
          schema:
            $ref: "#/components/schemas/DisplayPayoutStatus"
        - description: Filter by the alpha-3 ISO 4217 currency code of the payout.
          in: query
          name: currency
          required: false
          schema:
            $ref: "#/components/schemas/CurrencyCode"
        - description: Filter by your own reference number for the payout.
          in: query
          name: external_payout_id
          required: false
          schema:
            $ref: "#/components/schemas/ExternalPayoutId"
        - description: Filter by your own reference id for the vendor.
          in: query
          name: external_vendor_id
          required: false
          schema:
            $ref: "#/components/schemas/ExternalVendorId"
        - description: Earliest payout date to include, in `YYYY-MM-DD` format.
          in: query
          name: from_date
          required: false
          schema:
            type: string
        - description: Latest payout date to include, in `YYYY-MM-DD` format.
          in: query
          name: to_date
          required: false
          schema:
            type: string
        - description: Page number indicating which set of items to return.
          in: query
          name: page
          required: false
          schema:
            $ref: "#/components/schemas/Page"
        - description: The number of items in a page.
          in: query
          name: per_page
          required: false
          schema:
            $ref: "#/components/schemas/PerPage"
  /payouts/{proposalId}/submit:
    post:
      operationId: Submit
      responses:
        "200":
          description: Payout submitted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "410":
          description: The request failed because the payout proposal has expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: |-
        Submits a previously reviewed payout, executing the payment. The `proposalId` is the id returned
        by `POST /v1/payouts`. Must be called before the proposal's `validUntilTs`, otherwise it is rejected
        as expired.
      tags:
        - Payouts
      security:
        - api-key: []
      parameters:
        - description: The id of the payout proposal, as returned by `POST /v1/payouts`.
          in: path
          name: proposalId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
  /payouts/{payoutId}:
    get:
      operationId: Get
      responses:
        "200":
          description: Payout found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves a single payout by its payout id, including its current status and vendor bank details.
      tags:
        - Payouts
      security:
        - api-key: []
      parameters:
        - description: The id of the payout within the Grain platform.
          in: path
          name: payoutId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
  /wallets:
    get:
      operationId: List
      responses:
        "200":
          description: Wallets Retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletsResponse"
      description: Retrieves all wallets and their balances, per currency.
      tags:
        - Wallets
      security:
        - api-key: []
      parameters: []
  /wallets/{walletId}:
    get:
      operationId: Get
      responses:
        "200":
          description: Wallet Retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PartnerWallet"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      description: Retrieves a specific wallet by its Grain wallet ID.
      tags:
        - Wallets
      security:
        - api-key: []
      parameters:
        - description: The id of the wallet within the Grain platform.
          in: path
          name: walletId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
  /wallets/{walletId}/withdraw:
    post:
      operationId: Withdraw
      responses:
        "200":
          description: Withdraw completed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateObjectResponseBody"
        "400":
          description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Example 1:
                  value:
                    message: The request failed because the resource does not exist.
        "409":
          description: The request failed because a business rule constraint was violated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Example 1:
                  value:
                    message: The request failed because a business rule constraint was violated.
        "422":
          description: The request failed because it is either semantically incorrect or has failed business validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Example 1:
                  value:
                    message: The request failed because it is either semantically incorrect or has failed business validation.
      description: >-
        Withdraws funds from a wallet to a configured beneficiary. Returns the ID of the created withdrawal fund
        transfer.
      tags:
        - Wallets
      security:
        - api-key: []
      parameters:
        - description: The id of the wallet within the Grain platform.
          in: path
          name: walletId
          required: true
          schema:
            $ref: "#/components/schemas/UUID"
      requestBody:
        description: The payload required in order to withdraw fund transfers
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WithdrawRequestBody"
              description: The payload required in order to withdraw fund transfers
servers:
  - url: https://api.grainfinance.co/v1
    description: Grain API
tags:
  - name: Hedges
    description: >-
      Hedge objects represent transactions that lock exchange rates for future dates. A single hedge locks an exchange
      rate for a future transaction between two currencies.
  - name: Dual Hedges
    description: >-
      A dual hedge mitigates FX risk by automatically generating two linked hedge legs - a customer leg and a supplier
      leg - both routed through the customer's functional currency. This structure reduces exposure to currency
      fluctuations for both cash flow and accounting purposes, while allowing independent tracking and reporting of each
      hedge leg.
  - name: Customers
    description: >-
      Customer objects represent your end customers on the Grain platform. A customer must be created before a hedge or
      spot transaction can be initiated.
  - name: Pricing
    description: >-
      Pricing endpoints provide access to FX rates for currency pairs that are not being hedged. These endpoints can be
      used for live rate display or bulk retrieval to support high-volume quoting workflows.
  - name: Spots
    description: Spot objects represent currency conversions executed for immediate or near-term settlement.
  - name: Conversions
    description: Conversion objects represent currency conversions executed for immediate or near-term settlement.
  - name: Wallets
    description: Endpoints to view balances, manage funding, and perform transfers.
webhooks:
  hedge.cancelled:
    post:
      operationId: webhook.hedge.cancelled
      summary: Hedge has been canceled.
      description: Sent when a hedge is canceled by the customer or by the system.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId:
                  type: string
                  description: Deterministic unique UUID. Use for idempotency and deduplication.
                environment:
                  type: string
                  enum:
                    - Live
                    - Sandbox
                    - Demo
                  description: "\"Live\" or \"Sandbox\"."
                createdAtTs:
                  type: number
                  description: Unix timestamp (ms) indicating when the event was created.
                version:
                  type: string
                  description: Payload schema version. Currently "1.0".
                organizationId:
                  type: string
                  format: uuid
                  description: UUID of the organization the event belongs to.
                type:
                  type: string
                  enum:
                    - hedge.cancelled
                data:
                  type: object
                  properties:
                    hedgeId:
                      type: string
                      format: uuid
                      description: Unique identifier of the hedge.
                    fromCurrency:
                      type: string
                      description: Source currency code (e.g., "USD").
                    fromCurrencyAmount:
                      type: number
                      description: Amount in the source currency.
                    toCurrency:
                      type: string
                      description: Target currency code (e.g., "EUR").
                    toCurrencyAmount:
                      type: number
                      description: Amount in the target currency.
                    settlementType:
                      type: string
                      enum:
                        - full
                        - offset
                        - manual
                      description: "\"full\", \"offset\", or \"manual\"."
                    externalTransactionId:
                      type: string
                      description: External transaction identifier.
                    cancelledAt:
                      type:
                        - string
                        - "null"
                      description: Date the hedge was canceled (YYYY-MM-DD).
                    cancelReason:
                      type: string
                      description: Reason for cancellation.
                  required:
                    - hedgeId
                    - fromCurrency
                    - fromCurrencyAmount
                    - toCurrency
                    - toCurrencyAmount
                    - settlementType
                    - externalTransactionId
                    - cancelledAt
                    - cancelReason
              required:
                - eventId
                - environment
                - createdAtTs
                - version
                - organizationId
                - type
                - data
              example:
                environment: Live
                version: "1.0"
                organizationId: 98f7e6d5-c4b3-2a10-9876-543210fedcba
                eventId: hedge-cancelled_c3d4e5f6-a7b8-9012-cdef-123456789012
                createdAtTs: 1710932100000
                type: hedge.cancelled
                data:
                  hedgeId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  fromCurrency: USD
                  fromCurrencyAmount: 100000
                  toCurrency: EUR
                  toCurrencyAmount: 91250
                  settlementType: full
                  externalTransactionId: ext_tx_001
                  cancelledAt: 2026-03-20T00:00:00.000Z
                  cancelReason: Requested by customer
      responses:
        "200":
          description: Return 2xx within 10s to acknowledge delivery.
  hedge.completed:
    post:
      operationId: webhook.hedge.completed
      summary: Hedge has been fully settled.
      description: Sent when a hedge is fully settled on its settlement date.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId:
                  type: string
                  description: Deterministic unique UUID. Use for idempotency and deduplication.
                environment:
                  type: string
                  enum:
                    - Live
                    - Sandbox
                    - Demo
                  description: "\"Live\" or \"Sandbox\"."
                createdAtTs:
                  type: number
                  description: Unix timestamp (ms) indicating when the event was created.
                version:
                  type: string
                  description: Payload schema version. Currently "1.0".
                organizationId:
                  type: string
                  format: uuid
                  description: UUID of the organization the event belongs to.
                type:
                  type: string
                  enum:
                    - hedge.completed
                data:
                  type: object
                  properties:
                    hedgeId:
                      type: string
                      format: uuid
                      description: Unique identifier of the hedge.
                    fromCurrency:
                      type: string
                      description: Source currency code (e.g., "USD").
                    fromCurrencyAmount:
                      type: number
                      description: Amount in the source currency.
                    toCurrency:
                      type: string
                      description: Target currency code (e.g., "EUR").
                    toCurrencyAmount:
                      type: number
                      description: Amount in the target currency.
                    settlementType:
                      type: string
                      enum:
                        - full
                        - offset
                        - manual
                      description: "\"full\", \"offset\", or \"manual\"."
                    externalTransactionId:
                      type: string
                      description: External transaction identifier.
                    completedAt:
                      type:
                        - string
                        - "null"
                      description: Date the hedge was settled (YYYY-MM-DD).
                  required:
                    - hedgeId
                    - fromCurrency
                    - fromCurrencyAmount
                    - toCurrency
                    - toCurrencyAmount
                    - settlementType
                    - externalTransactionId
                    - completedAt
              required:
                - eventId
                - environment
                - createdAtTs
                - version
                - organizationId
                - type
                - data
              example:
                environment: Live
                version: "1.0"
                organizationId: 98f7e6d5-c4b3-2a10-9876-543210fedcba
                eventId: hedge-completed_a1b2c3d4-e5f6-7890-abcd-ef1234567890
                createdAtTs: 1711461000000
                type: hedge.completed
                data:
                  hedgeId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  fromCurrency: USD
                  fromCurrencyAmount: 100000
                  toCurrency: EUR
                  toCurrencyAmount: 91250
                  settlementType: full
                  externalTransactionId: ext_tx_001
                  completedAt: 2026-03-26T00:00:00.000Z
      responses:
        "200":
          description: Return 2xx within 10s to acknowledge delivery.
  hedge.overdue:
    post:
      operationId: webhook.hedge.overdue
      summary: Hedge has passed its settlement date without settling.
      description: Sent when a hedge passes its settlement date without being settled.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId:
                  type: string
                  description: Deterministic unique UUID. Use for idempotency and deduplication.
                environment:
                  type: string
                  enum:
                    - Live
                    - Sandbox
                    - Demo
                  description: "\"Live\" or \"Sandbox\"."
                createdAtTs:
                  type: number
                  description: Unix timestamp (ms) indicating when the event was created.
                version:
                  type: string
                  description: Payload schema version. Currently "1.0".
                organizationId:
                  type: string
                  format: uuid
                  description: UUID of the organization the event belongs to.
                type:
                  type: string
                  enum:
                    - hedge.overdue
                data:
                  type: object
                  properties:
                    hedgeId:
                      type: string
                      format: uuid
                      description: Unique identifier of the hedge.
                    fromCurrency:
                      type: string
                      description: Source currency code (e.g., "USD").
                    fromCurrencyAmount:
                      type: number
                      description: Amount in the source currency.
                    toCurrency:
                      type: string
                      description: Target currency code (e.g., "EUR").
                    toCurrencyAmount:
                      type: number
                      description: Amount in the target currency.
                    settlementType:
                      type: string
                      enum:
                        - full
                        - offset
                        - manual
                      description: "\"full\", \"offset\", or \"manual\"."
                    externalTransactionId:
                      type: string
                      description: External transaction identifier.
                    overdueAt:
                      type:
                        - string
                        - "null"
                      description: Date the hedge became overdue (YYYY-MM-DD).
                  required:
                    - hedgeId
                    - fromCurrency
                    - fromCurrencyAmount
                    - toCurrency
                    - toCurrencyAmount
                    - settlementType
                    - externalTransactionId
                    - overdueAt
              required:
                - eventId
                - environment
                - createdAtTs
                - version
                - organizationId
                - type
                - data
              example:
                environment: Live
                version: "1.0"
                organizationId: 98f7e6d5-c4b3-2a10-9876-543210fedcba
                eventId: hedge-overdue_b2c3d4e5-f6a7-8901-bcde-f12345678901
                createdAtTs: 1711524000000
                type: hedge.overdue
                data:
                  hedgeId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  fromCurrency: USD
                  fromCurrencyAmount: 100000
                  toCurrency: EUR
                  toCurrencyAmount: 91250
                  settlementType: full
                  externalTransactionId: ext_tx_001
                  overdueAt: 2026-03-27T00:00:00.000Z
      responses:
        "200":
          description: Return 2xx within 10s to acknowledge delivery.
  hedge.initial.collateral.received:
    post:
      operationId: webhook.hedge.initial.collateral.received
      summary: Initial collateral deposit has been received.
      description: Sent when the initial collateral deposit for a hedge has been received.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId:
                  type: string
                  description: Deterministic unique UUID. Use for idempotency and deduplication.
                environment:
                  type: string
                  enum:
                    - Live
                    - Sandbox
                    - Demo
                  description: "\"Live\" or \"Sandbox\"."
                createdAtTs:
                  type: number
                  description: Unix timestamp (ms) indicating when the event was created.
                version:
                  type: string
                  description: Payload schema version. Currently "1.0".
                organizationId:
                  type: string
                  format: uuid
                  description: UUID of the organization the event belongs to.
                type:
                  type: string
                  enum:
                    - hedge.initial.collateral.received
                data:
                  type: object
                  properties:
                    hedgeId:
                      type: string
                      format: uuid
                      description: Unique identifier of the hedge.
                    fromCurrency:
                      type: string
                      description: Source currency code (e.g., "USD").
                    fromCurrencyAmount:
                      type: number
                      description: Amount in the source currency.
                    toCurrency:
                      type: string
                      description: Target currency code (e.g., "EUR").
                    toCurrencyAmount:
                      type: number
                      description: Amount in the target currency.
                    settlementType:
                      type: string
                      enum:
                        - full
                        - offset
                        - manual
                      description: "\"full\", \"offset\", or \"manual\"."
                    externalTransactionId:
                      type: string
                      description: External transaction identifier.
                    initialCollateralAmount:
                      type: number
                      description: Amount of collateral received.
                    initialCollateralReceivedAt:
                      type:
                        - string
                        - "null"
                      description: Date the collateral was received (YYYY-MM-DD).
                  required:
                    - hedgeId
                    - fromCurrency
                    - fromCurrencyAmount
                    - toCurrency
                    - toCurrencyAmount
                    - settlementType
                    - externalTransactionId
                    - initialCollateralAmount
                    - initialCollateralReceivedAt
              required:
                - eventId
                - environment
                - createdAtTs
                - version
                - organizationId
                - type
                - data
              example:
                environment: Live
                version: "1.0"
                organizationId: 98f7e6d5-c4b3-2a10-9876-543210fedcba
                eventId: hedge-initial-collateral-received_d4e5f6a7-b8c9-0123-defa-234567890123
                createdAtTs: 1710496500000
                type: hedge.initial.collateral.received
                data:
                  hedgeId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  fromCurrency: USD
                  fromCurrencyAmount: 100000
                  toCurrency: EUR
                  toCurrencyAmount: 91250
                  settlementType: full
                  externalTransactionId: ext_tx_001
                  initialCollateralAmount: 5000
                  initialCollateralReceivedAt: 2026-03-15T00:00:00.000Z
      responses:
        "200":
          description: Return 2xx within 10s to acknowledge delivery.
  hedge.initial.collateral.overdue:
    post:
      operationId: webhook.hedge.initial.collateral.overdue
      summary: Initial collateral deposit is past due.
      description: Sent when the initial collateral deposit has not been received by its due date.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId:
                  type: string
                  description: Deterministic unique UUID. Use for idempotency and deduplication.
                environment:
                  type: string
                  enum:
                    - Live
                    - Sandbox
                    - Demo
                  description: "\"Live\" or \"Sandbox\"."
                createdAtTs:
                  type: number
                  description: Unix timestamp (ms) indicating when the event was created.
                version:
                  type: string
                  description: Payload schema version. Currently "1.0".
                organizationId:
                  type: string
                  format: uuid
                  description: UUID of the organization the event belongs to.
                type:
                  type: string
                  enum:
                    - hedge.initial.collateral.overdue
                data:
                  type: object
                  properties:
                    hedgeId:
                      type: string
                      format: uuid
                      description: Unique identifier of the hedge.
                    fromCurrency:
                      type: string
                      description: Source currency code (e.g., "USD").
                    fromCurrencyAmount:
                      type: number
                      description: Amount in the source currency.
                    toCurrency:
                      type: string
                      description: Target currency code (e.g., "EUR").
                    toCurrencyAmount:
                      type: number
                      description: Amount in the target currency.
                    settlementType:
                      type: string
                      enum:
                        - full
                        - offset
                        - manual
                      description: "\"full\", \"offset\", or \"manual\"."
                    externalTransactionId:
                      type: string
                      description: External transaction identifier.
                    initialCollateralAmount:
                      type: number
                      description: Expected collateral amount.
                    initialCollateralDueAt:
                      type:
                        - string
                        - "null"
                      description: Date the collateral was due (YYYY-MM-DD).
                  required:
                    - hedgeId
                    - fromCurrency
                    - fromCurrencyAmount
                    - toCurrency
                    - toCurrencyAmount
                    - settlementType
                    - externalTransactionId
                    - initialCollateralAmount
                    - initialCollateralDueAt
              required:
                - eventId
                - environment
                - createdAtTs
                - version
                - organizationId
                - type
                - data
              example:
                environment: Live
                version: "1.0"
                organizationId: 98f7e6d5-c4b3-2a10-9876-543210fedcba
                eventId: hedge-initial-collateral-overdue_e5f6a7b8-c9d0-1234-efab-345678901234
                createdAtTs: 1710576000000
                type: hedge.initial.collateral.overdue
                data:
                  hedgeId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  fromCurrency: USD
                  fromCurrencyAmount: 100000
                  toCurrency: EUR
                  toCurrencyAmount: 91250
                  settlementType: full
                  externalTransactionId: ext_tx_001
                  initialCollateralAmount: 5000
                  initialCollateralDueAt: 2026-03-15T00:00:00.000Z
      responses:
        "200":
          description: Return 2xx within 10s to acknowledge delivery.
  hedge.upcoming.settlement:
    post:
      operationId: webhook.hedge.upcoming.settlement
      summary: Settlement date is approaching.
      description: Sent as a reminder that a hedge settlement date is approaching.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId:
                  type: string
                  description: Deterministic unique UUID. Use for idempotency and deduplication.
                environment:
                  type: string
                  enum:
                    - Live
                    - Sandbox
                    - Demo
                  description: "\"Live\" or \"Sandbox\"."
                createdAtTs:
                  type: number
                  description: Unix timestamp (ms) indicating when the event was created.
                version:
                  type: string
                  description: Payload schema version. Currently "1.0".
                organizationId:
                  type: string
                  format: uuid
                  description: UUID of the organization the event belongs to.
                type:
                  type: string
                  enum:
                    - hedge.upcoming.settlement
                data:
                  type: object
                  properties:
                    hedgeId:
                      type: string
                      format: uuid
                      description: Unique identifier of the hedge.
                    fromCurrency:
                      type: string
                      description: Source currency code (e.g., "USD").
                    fromCurrencyAmount:
                      type: number
                      description: Amount in the source currency.
                    toCurrency:
                      type: string
                      description: Target currency code (e.g., "EUR").
                    toCurrencyAmount:
                      type: number
                      description: Amount in the target currency.
                    settlementType:
                      type: string
                      enum:
                        - full
                        - offset
                        - manual
                      description: "\"full\", \"offset\", or \"manual\"."
                    externalTransactionId:
                      type: string
                      description: External transaction identifier.
                    settlementAt:
                      type:
                        - string
                        - "null"
                      description: Upcoming settlement date (YYYY-MM-DD).
                  required:
                    - hedgeId
                    - fromCurrency
                    - fromCurrencyAmount
                    - toCurrency
                    - toCurrencyAmount
                    - settlementType
                    - externalTransactionId
                    - settlementAt
              required:
                - eventId
                - environment
                - createdAtTs
                - version
                - organizationId
                - type
                - data
              example:
                environment: Live
                version: "1.0"
                organizationId: 98f7e6d5-c4b3-2a10-9876-543210fedcba
                eventId: hedge-upcoming-settlement_f6a7b8c9-d0e1-2345-fabc-456789012345
                createdAtTs: 1711180800000
                type: hedge.upcoming.settlement
                data:
                  hedgeId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  fromCurrency: USD
                  fromCurrencyAmount: 100000
                  toCurrency: EUR
                  toCurrencyAmount: 91250
                  settlementType: full
                  externalTransactionId: ext_tx_001
                  settlementAt: 2026-03-26T00:00:00.000Z
      responses:
        "200":
          description: Return 2xx within 10s to acknowledge delivery.
  wallet.deposit.received:
    post:
      operationId: webhook.wallet.deposit.received
      summary: A deposit has been received into a wallet.
      description: Sent when a deposit is received into a wallet.
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventId:
                  type: string
                  description: Deterministic unique UUID. Use for idempotency and deduplication.
                environment:
                  type: string
                  enum:
                    - Live
                    - Sandbox
                    - Demo
                  description: "\"Live\" or \"Sandbox\"."
                createdAtTs:
                  type: number
                  description: Unix timestamp (ms) indicating when the event was created.
                version:
                  type: string
                  description: Payload schema version. Currently "1.0".
                organizationId:
                  type: string
                  format: uuid
                  description: UUID of the organization the event belongs to.
                type:
                  type: string
                  enum:
                    - wallet.deposit.received
                data:
                  type: object
                  properties:
                    walletId:
                      type: string
                      format: uuid
                      description: Unique identifier of the wallet.
                    transferId:
                      type: string
                      format: uuid
                      description: Unique identifier of the transfer.
                    currency:
                      type: string
                      description: Currency code of the deposit (e.g., "USD").
                    amount:
                      type: number
                      description: Deposit amount.
                    completedAt:
                      type:
                        - string
                        - "null"
                      description: Date the deposit was completed (YYYY-MM-DD).
                    depositedBy:
                      type:
                        - string
                        - "null"
                      description: Name of the depositing entity, if available.
                  required:
                    - walletId
                    - transferId
                    - currency
                    - amount
                    - completedAt
                    - depositedBy
              required:
                - eventId
                - environment
                - createdAtTs
                - version
                - organizationId
                - type
                - data
              example:
                environment: Live
                version: "1.0"
                organizationId: 98f7e6d5-c4b3-2a10-9876-543210fedcba
                eventId: wallet-deposit-received_a7b8c9d0-e1f2-3456-abcd-567890123456
                createdAtTs: 1711200000000
                type: wallet.deposit.received
                data:
                  walletId: f1e2d3c4-b5a6-7890-fedc-ba0987654321
                  transferId: f6a7b8c9-d0e1-2345-f012-678901234567
                  currency: USD
                  amount: 25000
                  completedAt: 2026-03-23T00:00:00.000Z
                  depositedBy: Acme Corp
      responses:
        "200":
          description: Return 2xx within 10s to acknowledge delivery.
