Currencycloud Balances API

openapi: 3.2.0
info:
  description: The Currencycloud API is a robust, predictable, easy-to-use API for converting money between currencies and making payments around the world. Dynamically register sub-accounts to provide white labeled money transfer services to your own customers.
  version: 2.43.0
  title: Currencycloud Balances API
  termsOfService: https://www.currencycloud.com/terms-and-conditions/
  contact:
    name: support
    email: support@currencycloud.com
servers:
- url: https://devapi.currencycloud.com/v2
tags:
- name: Balances
  description: Provides access to view balance information. View the balances that you currently hold in different currencies on your Currencycloud account.
paths:
  /balances/{currency}:
    get:
      tags:
      - Balances
      x-api-group: manage
      summary: Get Balance
      description: Gets the balance for a currency from the account of the authenticated user.
      operationId: GetBalance
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: currency
        in: path
        required: true
        description: Three-letter ISO currency code.
        schema:
          type: string
          format: iso-4217
          pattern: ^[A-Z]{3}$
      - name: on_behalf_of
        in: query
        required: false
        description: A contact UUID for the sub-account you're acting on behalf of.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '400':
          description: Client error.
          x-errors:
          - code: invalid_currency
            category: currency
            message: XYZ is not a valid ISO 4217 currency code
            params: '{ "currency" => "XYZ" }'
          - code: currency_is_in_invalid_format
            category: currency
            message: currency is not a valid ISO 4217 currency code
            params: '{ "type" => "currency" }'
          - code: on_behalf_of_is_not_valid_uuid
            category: on_behalf_of
            message: on_behalf_of should be in UUID format
            params: ''
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          - code: contact_not_found
            category: on_behalf_of
            message: Contact was not found for this id
            params: ''
          - code: unsupported_currency
            category: currency
            message: Unsupported currency XYZ
            params: '{ "currency": "UAH" }'
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalanceError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
  /balances/find:
    get:
      tags:
      - Balances
      x-api-group: manage
      summary: Find Balances
      description: Searches for currency balances in the main account or a sub-account owned by the authenticated user.
      operationId: FindBalances
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: on_behalf_of
        in: query
        required: false
        description: A contact UUID for the sub-account you're acting on behalf of.
        schema:
          type: string
          format: uuid
      - name: amount_from
        in: query
        required: false
        description: Minimum balance amount.
        schema:
          type: number
          pattern: ^\d+(\.\d{1,3})?$
      - name: amount_to
        in: query
        required: false
        description: Maximum balance amount.
        schema:
          type: number
          pattern: ^\d+(\.\d{1,3})?$
      - name: as_at_date
        in: query
        required: false
        description: A valid ISO 8601 format, e.g. "2019-12-31T23:59:59".
        schema:
          type: string
          format: date-time
      - name: scope
        in: query
        required: false
        description: '"Own" account, "clients" sub-accounts, or "all" accounts.'
        schema:
          type: string
          enum:
          - all
          - clients
          - own
          default: own
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          pattern: ^\d+$
      - name: per_page
        in: query
        required: false
        description: Number of results per page.
        schema:
          type: integer
          pattern: ^\d+$
      - name: order
        in: query
        required: false
        description: A field name to change the sort order - "created_at", "amount", "updated_at" or "currency".
        schema:
          type: string
          enum:
          - amount
          - created_at
          - currency
          - updated_at
          default: created_at
          maxLength: 255
          minLength: 1
      - name: order_asc_desc
        in: query
        required: false
        description: Sort records in ascending or descending order.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  balances:
                    type: array
                    items:
                      $ref: '#/components/schemas/Balance'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Client error.
          x-errors:
          - code: contact_not_found
            category: on_behalf_of
            message: Contact was not found for this id
            params: ''
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          - code: as_at_date_is_in_invalid_format
            category: as_at_date
            message: as_at_date should be in ISO 8601 format
            params: '{ "type": "datetime" }'
          - code: amount_from_type_is_wrong
            category: amount_from_type
            message: amount_from should be of decimal type
            params: '{"type": "decimal"}'
          - code: amount_to_type_is_wrong
            category: amount_to_type
            message: amount_to should be of decimal type
            params: '{"type": "decimal"}'
          - code: order_not_in_range
            category: order
            message: 'order should be in range: created_at, amount, updated_at, currency'
            params: '{"range": "created_at, amount, updated_at, currency"}'
          - code: order_asc_desc_not_in_range
            category: order_asc_desc
            message: 'order_asc_desc should be in range: asc, desc'
            params: '{"range": "asc, desc"}'
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindBalancesError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
  /balances/top_up_margin:
    post:
      tags:
      - Balances
      x-api-group: manage
      summary: Top Up Margin Balance
      description: Tops up the margin balance.
      operationId: TopUpMarginBalance
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpMarginBalance'
        '400':
          description: Client error.
          x-errors:
          - code: currency_is_required
            category: currency
            message: currency is required
            params: ''
          - code: currency_is_in_invalid_format
            category: currency
            message: currency is not a valid ISO 4217 currency code
            params: '{ "type" => "currency" }'
          - code: amount_is_required
            category: amount
            message: amount is required
            params: ''
          - code: amount_type_is_wrong
            category: amount
            message: amount should be of numeric_greater_than_zero type
            params: '{ "type" => "numeric_greater_than_zero" }'
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          - code: contact_not_found
            category: on_behalf_of
            message: Contact was not found for this id
            params: ''
          - code: on_behalf_of_is_not_valid_uuid
            category: on_behalf_of
            message: on_behalf_of should be in UUID format
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpMarginBalanceError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                currency:
                  type: string
                  format: iso-4217
                  pattern: ^[A-Z]{3}$
                  description: Three-letter ISO currency code for the currency to top up.
                amount:
                  type: string
                  pattern: ^\d+(\.\d{1,3})?$
                  description: Amount to top up.
                on_behalf_of:
                  type: string
                  format: UUID
                  maxLength: 36
                  minLength: 36
                  description: A contact UUID for the sub-account you're acting on behalf of.
              required:
              - currency
              - amount
components:
  schemas:
    Pagination:
      type: object
      description: Pagination.
      properties:
        total_entries:
          type: integer
        total_pages:
          type: integer
        current_page:
          type: integer
        per_page:
          type: integer
          description: Number of results per page.
        previous_page:
          type: integer
        next_page:
          type: integer
        order:
          type: string
          description: The field name by which the results are sorted.
        order_asc_desc:
          type: string
          enum:
          - asc
          - desc
          default: asc
          description: Whether results are sorted in ascending or descending order.
      example:
        total_entries: 1
        total_pages: 1
        current_page: 1
        per_page: 25
        previous_page: -1
        next_page: 2
        order: created_at
        order_asc_desc: asc
    GetBalanceError:
      type: object
      description: 'Client error information for the Get Balance endpoint.

        '
      required:
      - error_code
      - error_messages
      properties:
        error_code:
          type: string
          description: A high-level error code for the whole request.
        error_messages:
          type: object
          description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
          additionalProperties:
            type: array
            items:
              type: object
              description: An object that represents one of the reasons why the input parameter failed.
              required:
              - code
              - message
              properties:
                code:
                  type: string
                  description: A unique code that identifies this error. It can be used for translations.
                message:
                  type: string
                  description: An explanation of the error in English.
                params:
                  type: object
                  default: {}
                  description: Relevant validation rules that failed. This can be used for translations.
                  example:
                    minlength: 1
                    maxlength: 255
    Balance:
      type: object
      description: Balance.
      properties:
        id:
          type: string
          description: Balance UUID
          format: UUID
        account_id:
          type: string
          description: Account UUID
          format: UUID
        currency:
          type: string
          description: Three-letter ISO currency code for the currency the amount is shown in.
        amount:
          type: string
          description: The balance amount.
        created_at:
          type: string
          format: date-time
          description: Date/time the record was created.
        updated_at:
          type: string
          format: date-time
          description: Date/time the record was last updated.
      example:
        id: 18230F1D-648A-406A-AD1F-A09CBC02E9E9
        account_id: TcC
        currency: USD
        amount: '1000.00'
        created_at: '2023-12-31T23:59:59.000Z'
        updated_at: '2023-12-31T23:59:59.000Z'
    UnauthorizedError:
      type: object
      description: Authorization error.
      required:
      - error_code
      - error_messages
      properties:
        error_code:
          type: string
          description: A high-level error code for the whole request.
          enum:
          - auth_failed
        error_messages:
          type: object
          description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
          additionalProperties:
            type: array
            items:
              type: object
              description: An object that represents one of the reasons why the input parameter failed.
              required:
              - code
              - message
              properties:
                code:
                  type: string
                  description: A unique code that identifies this error. It can be used for translations.
                message:
                  type: string
                  description: An explanation of the error in English.
                params:
                  type: object
                  default: {}
                  description: Relevant validation rules that failed. This can be used for translations.
                  example:
                    minlength: 1
                    maxlength: 255
      example:
        error_code: auth_failed
        error_messages:
          api_key:
          - code: invalid_supplied_credentials
            message: Authentication failed with the supplied credentials
            params: {}
    TopUpMarginBalanceError:
      type: object
      description: 'Client error information for the Top Up Margin Balance endpoint.

        '
      required:
      - error_code
      - error_messages
      properties:
        error_code:
          type: string
          description: A high-level error code for the whole request.
        error_messages:
          type: object
          description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
          additionalProperties:
            type: array
            items:
              type: object
              description: An object that represents one of the reasons why the input parameter failed.
              required:
              - code
              - message
              properties:
                code:
                  type: string
                  description: A unique code that identifies this error. It can be used for translations.
                message:
                  type: string
                  description: An explanation of the error in English.
                params:
                  type: object
                  default: {}
                  description: Relevant validation rules that failed. This can be used for translations.
                  example:
                    minlength: 1
                    maxlength: 255
    RateLimitError:
      type: object
      description: Too many requests.
      required:
      - error_code
      - error_messages
      properties:
        error_code:
          type: string
          description: A high-level error code for the whole request.
        error_messages:
          type: object
          description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
          additionalProperties:
            type: array
            items:
              type: object
              description: An object that represents one of the reasons why the input parameter failed.
              required:
              - code
              - message
              properties:
                code:
                  type: string
                  description: A unique code that identifies this validation/error.
                message:
                  type: string
                  description: An explanation of the error in English.
                params:
                  type: object
                  default: {}
                  description: Relevant validation rules that failed. This can be used for translations.
                  example:
                    minlength: 1
                    maxlength: 255
    TopUpMarginBalance:
      type: object
      description: Bank Details.
      required:
      - account_id
      - currency
      - transferred_amount
      additionalProperties: false
      properties:
        account_id:
          type: string
          description: Account identifier
        currency:
          type: string
          description: Currency code for currency transferred.
        transferred_amount:
          type: string
          description: Amount of transfer.
      example:
        account_id: 6c046c51-2387-4004-8e87-4bf97102e36d
        currency: EUR
        transferred_amount: 100.0
    NotFoundError:
      type: object
      description: Resource not found.
      required:
      - error_code
      - error_messages
      properties:
        error_code:
          type: string
          description: A high-level error code for the whole request.
        error_messages:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              description: An object that represents one of the reasons why the input parameter failed.
              required:
              - code
              - message
              properties:
                code:
                  type: string
                  description: A unique code that identifies this error. It can be used for translations.
                message:
                  type: string
                  description: An explanation of the error in English.
                params:
                  type: object
                  default: {}
                  description: Relevant validation rules that failed. This can be used for translations.
                  example:
                    minlength: 1
                    maxlength: 255
    FindBalancesError:
      type: object
      description: 'Client error information for the Find Balances endpoint.

        '
      required:
      - error_code
      - error_messages
      properties:
        error_code:
          type: string
          description: A high-level error code for the whole request.
        error_messages:
          type: object
          description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
          additionalProperties:
            type: array
            items:
              type: object
              description: An object that represents one of the reasons why the input parameter failed.
              required:
              - code
              - message
              properties:
                code:
                  type: string
                  description: A unique code that identifies this error. It can be used for translations.
                message:
                  type: string
                  description: An explanation of the error in English.
                params:
                  type: object
                  default: {}
                  description: Relevant validation rules that failed. This can be used for translations.
                  example:
                    minlength: 1
                    maxlength: 255
externalDocs:
  description: API overview
  url: https://www.currencycloud.com/developers/