Currencycloud Balances API
Provides access to view balance information. View the balances that you currently hold in different currencies on your Currencycloud account.
OpenAPI Specification
openapi: 3.0.3
info:
title: api-onboarding Account Usage Balances API
version: v1
description: Provides access to view balance information. View the balances that you currently hold in different currencies on your Currencycloud account.
servers:
- url: /onboarding
description: Relative URL
- url: https://api.currencycloud.com/onboarding
description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
description: Dev server (uses test data)
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
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: currency
in: path
required: true
type: string
description: Three-letter ISO currency code.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: on_behalf_of
in: query
required: false
type: string
description: A contact UUID for the sub-account you're acting on behalf of.
format: uuid
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Balance'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'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" }'
schema:
$ref: '#/definitions/GetBalanceError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
schema:
$ref: '#/definitions/NotFoundError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'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: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/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
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: on_behalf_of
in: query
required: false
type: string
description: A contact UUID for the sub-account you're acting on behalf of.
format: uuid
- name: amount_from
in: query
required: false
type: number
description: Minimum balance amount.
pattern: ^\d+(\.\d{1,3})?$
- name: amount_to
in: query
required: false
type: number
description: Maximum balance amount.
pattern: ^\d+(\.\d{1,3})?$
- name: as_at_date
in: query
required: false
type: string
format: date-time
description: A valid ISO 8601 format, e.g. "2019-12-31T23:59:59".
- name: scope
in: query
required: false
type: string
enum:
- all
- clients
- own
default: own
description: '"Own" account, "clients" sub-accounts, or "all" accounts.'
- name: page
in: query
required: false
type: integer
description: Page number
pattern: ^\d+$
- name: per_page
in: query
required: false
type: integer
description: Number of results per page.
pattern: ^\d+$
- name: order
in: query
required: false
type: string
default: created_at
description: A field name to change the sort order - "created_at", "amount", "updated_at" or "currency".
enum:
- amount
- created_at
- currency
- updated_at
minLength: 1
maxLength: 255
- name: order_asc_desc
in: query
required: false
type: string
enum:
- asc
- desc
default: asc
description: Sort records in ascending or descending order.
responses:
'200':
description: Success.
schema:
type: object
properties:
balances:
type: array
items:
$ref: '#/definitions/Balance'
pagination:
$ref: '#/definitions/Pagination'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'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"}'
schema:
$ref: '#/definitions/FindBalancesError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'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: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/balances/top_up_margin:
post:
tags:
- Balances
x-api-group: manage
summary: Top Up Margin Balance
description: Tops up the margin balance.
operationId: TopUpMarginBalance
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: currency
in: formData
required: true
type: string
description: Three-letter ISO currency code for the currency to top up.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: amount
in: formData
required: true
type: string
description: Amount to top up.
pattern: ^\d+(\.\d{1,3})?$
- name: on_behalf_of
in: formData
required: false
type: string
description: A contact UUID for the sub-account you're acting on behalf of.
format: UUID
minLength: 36
maxLength: 36
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/TopUpMarginBalance'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'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: ''
schema:
$ref: '#/definitions/TopUpMarginBalanceError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'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: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
components:
securitySchemes:
AuthToken:
type: apiKey
in: header
name: X-Auth-Token
definitions:
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
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: {}
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
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'
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
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
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