Technical guide for using the Exchange API v2 with a confidential application acting on behalf of its operator


This document is meant for:


Place orders via a confidential application on behalf of the application operator such that the following points are satisfied:



The confidential application uses the OAuth Client Credentials grant to authenticate itself. To achieve the goals in a satisfactory manner, the application must be authenticated when estimating amounts, placing orders, duplicating orders, listing orders and accessing orders details.

The additional fees deducted by Bity on behalf of the partner are gathered with the partner revenue coming from the profit-sharing scheme.

When an OAuth access token is used, the usage of the Client-Id header is unnecessary.

Implementation details

Authentication with client credentials

The Exchange API expects OAuth access tokens to be located in the Authorization header with the Bearer scheme (RFC 6750).

The confidential application uses the Client Credentials Grant (RFC 6749 § 4.4) with one of the two most widely used authentication methods described below in order to obtain access tokens. It is recommended for the confidential application to use one of the already existing OAuth client libraries.

The confidential application needs to be configured with the following information in order to be able to obtain OAuth access tokens enabling to achieve the goals:

Additionally, the OAuth client library you choose might need to be informed of which authentication method to use if it supports more than one. Please consult its documentation in that regard.

The aforementioned values (identifier, secret, etc.) are accessible in the OAuth clients management application (opens in a new window).

Requesting client credentials

To obtain new application credentials needed to achieve the goals, use the dedicated application (opens in a new window) and select “Using the Exchange API on your behalf” while registering an application.

Client secret in HTTP basic authentication

With HTTP basic authentication (RFC 7617), the request to the Token Endpoint look as follow:

POST /oauth2/token HTTP/1.1
Authorization: Basic base64("OAuthClientId:OAuthClientSecret")
Content-Type: application/x-www-form-urlencoded


base64("OAuthClientId:OAuthClientSecret") are the encoded secrets which in an actual request will look like QWxhZGRpbjpvcGVuIHNlc2FtZQ==.

An actual request will not have the extraneous new lines in the body which may have been inserted in this document during formatting.

Client secret in POST body

With the client secrets in the POST body, the request to the Token Endpoint look as follow:

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded


OAuthClientId and OAuthClientSecret are an example, an actual request will have different values.

An actual request will not have the extraneous new lines in the body which may have been inserted in this document during formatting.

Calling the Exchange API

When calling the Exchange API, the application must include a valid OAuth access token with the Bearer scheme in the Authorization header in order to achieve the goals. Please note that authentication in the Exchange API is optional so one can not expect to obtain an immediate feedback if the Authorization header is missing. When the Authorization header is invalid, a 401 or 403 response will be returned and the WWW-Authenticate header will contain additional information.

For simplicity, ensure your confidential application always includes an Authorization header in the requests to the Exchange API.

The documentation of the Exchange API endpoints is available on as an OpenAPI Specification in YAML format and a rendered HTML version.

The following sections insist on the important details for achieving the goals.

Consulting order details and history, placing orders

To achieve the goals, it is sufficient to ensure the Authorization header is present when performing the following operations:

The rules applying to the Bity account of the operator are used. For instance the quota of the operator is used and if the operator does not need to provide proof of wallet ownership then orders will not have a message to sign.

For instance, a request for order details will look like the following example:

GET /v2/orders/87af11f3-b3cb-4683-a2f2-035ee0f86507 HTTP/1.1
Authorization: Bearer Ui3N9lDnaEFVNpQlWTa4mrn23AR0SDBGjEaRqyLF8lFuDnYsxZSAfw6gKa

Specifying an additional fee

To specify an additional fee in a satisfactory manner, the same additional fee must be specified when estimating amounts and when placing the corresponding order.

How to do this is detailed in the Technical guide for specifying an additional fee.