Grain Wallets API

openapi: 3.2.0
info:
  title: Grain Wallets 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: Wallets
  description: Endpoints to view balances, manage funding, and perform transfers.
paths:
  /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: []
      summary: List
      x-summary-source: derived
  /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'
      summary: Get
      x-summary-source: derived
  /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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawRequestBody'
      summary: Withdraw
      x-summary-source: derived
components:
  schemas:
    WalletsResponse:
      properties:
        wallets:
          items:
            $ref: '#/components/schemas/PartnerWallet'
          type: array
          description: List of the Partner's Wallets
      required:
      - wallets
      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
    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
    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:
          $ref: '#/components/schemas/UUID'
          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
    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}'
    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
  securitySchemes:
    api-key:
      type: http
      scheme: basic
      description: Basic authentication using the partner API keys from https://console.grainfinance.co/keys