Upvest API Documentation
Operating Model:
Upvest API Documentation
Operating Model:

Cash Balances

Download Spec

All cash balance related paths

Retrieve an account group's cash balance

get /account_groups/{account_group_id}/payments/cash_balance

Retrieve an account group's cash balance

Authentication

OAuth2 oauth-client-credentials

Required Scopes:

positions:read

All Scopes

  • accounts:admin · Create/update/delete accounts and account groups
  • accounts:read · Read accounts and account groups
  • checks:admin · Create checks
  • checks:read · Read checks
  • credit_fundings:read · Credit Fundings read operations
  • fees:admin · Create and read fee operations
  • fees:read · Read fee operations
  • instruments:read · Read instruments
  • mandates:admin · Create/update/delete mandates
  • mandates:read · Read mandates
  • orders:admin · Create/update/delete orders
  • orders:read · Read orders
  • payments:admin · Payins and withdrawal operations
  • payments:read · Payins and withdrawal read operations
  • portfolios:admin · Modify portfolios
  • portfolios:read · Read portfolios
  • positions:read · Read positions
  • reference_accounts:admin · Create/update/delete reference accounts
  • reference_accounts:read · Read reference accounts
  • reports:read · Read reports
  • taxes:admin · Modify tax residencies
  • taxes:read · Read tax residencies
  • topups:admin · Topups operations
  • topups:read · Topups read operations
  • transactions:read · Read cash and securities transactions
  • users:admin · Create/update/delete users
  • users:read · Read users
  • valuations:read · Read valuations
  • webhooks:admin · Create/update/delete webhooks
  • webhooks:read · Read webhooks
Flow Type:
Client Credentials
Token URL:
https://sandbox.upvest.co/auth/token

upvest-client-id

string

uuid

required

Tenant Client ID

Example
"ebabcf4d-61c3-4942-875c-e265a7c2d062"

authorization

string

^Bearer [a-zA-Z0-9\-\._~+/]*=*

required

Bearer (access) token from the OAuth flow with correct scopes. https://datatracker.ietf.org/doc/html/rfc6750

Example
"Bearer c2VjcmV0Cg=="

signature

string

required

https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

signature-input

string

required

https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

upvest-api-version

string

Upvest API version (Note: Do not include quotation marks)

Default
"1"
Enum
  • 1
Example
1

account_group_id

string

uuid

required

Account group unique identifier.

Responses

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/json

account_group_id

string

uuid

required

Account group unique identifier.

currency

string

ISO4217

required

Three-letter ISO 4217 alphabetical currency code.

  • EUR - Euro
Default
"EUR"
Enum
  • EUR

balance

string

^-?[0-9]{0,63}(\.[0-9]{1,27})?$

required

locked_for_trading

string

^[0-9]{0,63}(\.[0-9]{1,27})?$

required

pending_settlement

string

^[0-9]{0,63}(\.[0-9]{1,27})?$

required

available_for_withdrawal

string

^-?[0-9]{0,63}(\.[0-9]{1,27})?$

required

available_for_trading

string

^-?[0-9]{0,63}(\.[0-9]{1,27})?$

required

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/problem+json

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/problem+json

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/problem+json

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/problem+json

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/problem+json

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/problem+json

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

Response Headers

upvest-request-id

string

uuid

Example
"169ae4c7-ebd7-4041-94da-25369653eba7"

Response: application/problem+json

type

string

required

URL to a document describing the error condition.

status

int

required

Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

title

string

A short, human-readable title for the general error type; the title should not change for given types.

detail

string

A human-readable description of the specific error.

instance

string

This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

request_id

string

Correlation ID for the original request.

Response Examples

{
  "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
  "available_for_trading": "80",
  "available_for_withdrawal": "80",
  "balance": "100.25",
  "currency": "EUR",
  "locked_for_trading": "10",
  "pending_settlement": "10"
}
{
  "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
  "available_for_trading": "0",
  "available_for_withdrawal": "0",
  "balance": "1000",
  "currency": "EUR",
  "locked_for_trading": "1000",
  "pending_settlement": "0"
}
{
  "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
  "available_for_trading": "0",
  "available_for_withdrawal": "0",
  "balance": "0",
  "currency": "EUR",
  "locked_for_trading": "0",
  "pending_settlement": "0"
}
{
  "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
  "available_for_trading": "828.75",
  "available_for_withdrawal": "0",
  "balance": "828.75",
  "currency": "EUR",
  "locked_for_trading": "0",
  "pending_settlement": "828.75"
}
{
  "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
  "available_for_trading": "0",
  "available_for_withdrawal": "200",
  "balance": "200",
  "currency": "EUR",
  "locked_for_trading": "0",
  "pending_settlement": "0"
}
{
  "status": 401,
  "type": "unauthorized"
}
{
  "status": 403,
  "type": "forbidden"
}
{
  "status": 404,
  "type": "not_found"
}
{
  "status": 404,
  "type": "not_found"
}
{
  "status": 429,
  "type": "too_many_requests"
}
{
  "status": 500,
  "type": "internal_server_error"
}
{
  "status": 503,
  "type": "method_not_allowed"
}

Cash Balance events

webhook

Cash Balance events

application/json

created_at

string

date-time

required

Date and time when the event was created. RFC 3339-5, ISO8601 UTC

id

string

uuid

required

Event unique identifier

object

object (object)

required

account_group_id

string

uuid

required

Account group unique identifier.

available_for_trading

string

^-?[0-9]{0,63}(\.[0-9]{1,27})?$

required

available_for_withdrawal

string

^-?[0-9]{0,63}(\.[0-9]{1,27})?$

required

balance

string

^-?[0-9]{0,63}(\.[0-9]{1,27})?$

required

currency

string

ISO4217

required

Three-letter ISO 4217 alphabetical currency code.

  • EUR - Euro
Default
"EUR"
Enum
  • EUR

locked_for_trading

string

^[0-9]{0,63}(\.[0-9]{1,27})?$

required

pending_settlement

string

^[0-9]{0,63}(\.[0-9]{1,27})?$

required

type

string

required

Event type

Default
"CASH_BALANCE.UPDATED"
Enum
  • CASH_BALANCE.UPDATED

webhook_id

string

uuid

required

Webhook unique identifier.

Responses

Request Examples

{
  "created_at": "2021-07-21T14:11:00.00Z",
  "id": "8c049f77-dc72-489d-8f5f-3871db782252",
  "object": {
    "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
    "available_for_trading": "0",
    "available_for_withdrawal": "0",
    "balance": "0",
    "currency": "EUR",
    "locked_for_trading": "0",
    "pending_settlement": "0"
  },
  "type": "CASH_BALANCE.UPDATED",
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}
{
  "created_at": "2021-07-22T14:12:00.00Z",
  "id": "a59c81ee-7770-4f6b-9ebe-8c268b78beb4",
  "object": {
    "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
    "available_for_trading": "0",
    "available_for_withdrawal": "0",
    "balance": "200",
    "currency": "EUR",
    "locked_for_trading": "0",
    "pending_settlement": "0"
  },
  "type": "CASH_BALANCE.UPDATED",
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}
{
  "created_at": "2021-07-21T14:10:00.00Z",
  "id": "8962b496-8d42-4560-bfab-10490dd1a724",
  "object": {
    "account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
    "available_for_trading": "80",
    "available_for_withdrawal": "80",
    "balance": "100.25",
    "currency": "EUR",
    "locked_for_trading": "10",
    "pending_settlement": "10"
  },
  "type": "CASH_BALANCE.UPDATED",
  "webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}

Was this page helpful?