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

Audience

This document is meant for:

Partners implementing the Crypto Exchange API via a confidential application they operate and which acts of their behalf.
Developers working on a confidential application to be operated by partners (the user and the operator is the same person, the application is not provided as a service).

Goals

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

The confidential application is able to list orders associated to the Bity account of the operator.
The confidential application is able to place orders such that they are associated to the Bity account of the operator.
The orders are subject to profit-sharing with the operator.
The confidential application is able to request Bity to deduct an additional fee based on the input amount paid by the end user on behalf of its operator.

Definitions

Confidential application: an application which is able to keep values secret from its user. For instance a server-side application.
Public application: an application which is not able to keep values secret from its user, for instance a smartphone application, desktop application or client-side web application.

Overview

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:

OAuth client identifier
OAuth client secret
Token Endpoint: https://connect.bity.com/oauth2/token
Token Revocation Endpoint (optional): https://connect.bity.com/oauth2/revoke
Scope: https://auth.bity.com/scopes/exchange.history https://auth.bity.com/scopes/exchange.place

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
Host: connect.bity.com
Authorization: Basic base64("OAuthClientId:OAuthClientSecret")
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=https%3A%2F%2Fauth.bity.com%2Fscopes%2F
exchange.history+https%3A%2F%2Fauth.bity.com%2Fscopes%2Fexchange.place

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
Host: connect.bity.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=https%3A%2F%2Fauth.bity.com%2Fscopes%2F
exchange.history+https%3A%2F%2Fauth.bity.com%2Fscopes%2Fexchange.place
&client_id=OAuthClientId&client_secret=OAuthClientSecret

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 https://doc.bity.com/ 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:

Estimate the amount of an order
Place an order
List previously placed orders
Get the details of an order
Duplicate an order
Sign proof of wallet ownership message

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
Host: exchange.api.bity.com
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.