Grain Conversions API

openapi: 3.2.0
info:
  title: Grain Conversions API
  version: 1.0.0
  description: Grain's API provides a comprehensive set of endpoints for managing hedging, currency conversions, 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
servers:
- url: https://api.grainfinance.co/v1
  description: Grain API
tags:
- name: Conversions
  description: Conversion objects represent currency conversions executed for immediate or near-term settlement.
paths:
  /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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionQuoteRequestBody'
      summary: Quote
      x-summary-source: derived
  /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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptConversionProposalRequestBody'
      summary: Accept
      x-summary-source: derived
  /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:
          $ref: '#/components/schemas/UUID'
      summary: Get
      x-summary-source: derived
  /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'
      summary: List
      x-summary-source: derived
components:
  schemas:
    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
    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
    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:
      description: The payload required in order to accept a conversion proposal.
      properties:
        conversionProposalId:
          $ref: '#/components/schemas/UUID'
          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
    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
    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
    PerPage:
      type: number
      format: double
      description: number of items in a page
      minimum: 1
      maximum: 100
    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}
    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
    ConversionQuoteRequestBody:
      description: Information required by Grain in order to generate a conversion quote proposal.
      properties:
        fromCurrency:
          $ref: '#/components/schemas/CurrencyCode'
          description: The currency in which the transaction should be paid at by your customer.
          example: MXN
        toCurrency:
          $ref: '#/components/schemas/CurrencyCode'
          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
    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
    CurrencyCode:
      type: string
      example: EUR
      description: The alpha-3 ISO 4217 currency code of the related entity, in upper case.
      pattern: ^[A-Z]{3}$
    UUID:
      type: string
      format: uuid
      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}'
    Page:
      type: number
      format: double
      description: The page indicating which set of items are returned
      minimum: 1
    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}
    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
  securitySchemes:
    api-key:
      type: http
      scheme: basic
      description: Basic authentication using the partner API keys from https://console.grainfinance.co/keys