Technical guide for using the Exchange API v2 with a confidential application with end user authentication

Audience

This document is meant for:

Partners implementing the Crypto Exchange API via a confidential application they develop.
Developers working on a confidential application with users using a Bity account.

Goals

Place orders via a confidential application, on behalf of users using their Bity account, in such a way that the following points are satisfied:

The rules applying specifically to the logged-in user are in effect which can enable more flexibility, such as: higher volume, money transfer, use of an unspecified object to pay the order, no need to provide a signature, listing and accessing previously placed orders etc. What is possible is dependant on the status of the account and the user consent.
The orders placed are recognized as being facilitated by the partner operating the application and are therefore subject to profit-sharing.
The application is able to request Bity to deduct an additional fee based on the input amount paid by the end user on behalf of the partner.

Definitions

Confidential application: an application which is able to keep values secret from its user (sometimes also called confidential application). For instance, server-side web applications or server-side APIs.

Overview

The confidential application uses the OAuth Authorization Code grant in order to authenticate the user and obtain an access token. To achieve the goals in a satisfactory manner, the application must use an access token when performing any operation on behalf of a user such as estimating amount, and placing orders.

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 cookies and the usage of the Client-Id header are unnecessary.

Implementation details

Authentication with the authorization code grant

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

Confidential applications are expected to use the Authorization Code grant (RFC 6749 § 4.1). It is recommended for confidential applications to use an existing OAuth client library supporting this type of OAuth grant.

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

OAuth client identifier
OAuth client secret
Authorization Endpoint: https://connect.bity.com/oauth2/auth
Token Endpoint: https://connect.bity.com/oauth2/token
Token Revocation Endpoint (optional): https://connect.bity.com/oauth2/revoke
Redirection URI: <An URI with HTTPS scheme on the domain of your application>
Scope: one of
- https://auth.bity.com/scopes/exchange.place: to place orders
- https://auth.bity.com/scopes/exchange.history: to list previously placed orders
- https://auth.bity.com/scopes/exchange.place https://auth.bity.com/scopes/exchange.history: to place orders and list previously placed orders

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 Exchange API via confidential application, requiring user authentication” while registering an application.

Calling the Exchange API

When calling the Exchange API, the application must include a valid OAuth access token with the Bearer scheme (RFC 6750) 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.

To avoid issues, ensure your confidential application always includes an Authorization header in the requests to the Exchange API when acting on behalf of an user.

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.

What is possible to perform on behalf of the user is limited by the user consent which is made visible to your application via the OAuth scope. Make sure your application work adequately even when the user did not grant the largest possible scope to your application. For instance, users may grant your application the possibility to place orders on their behalf but may not grant it the possibility to access the listing of previously placed orders. In such situation you are naturally expected to let the user place orders as listing previously placed orders is not necessary in order to successfully place and execute an order.

The following is an example amount estimation on behalf of a user. Note that in this specific case, the status of the account of the user is such that it is not required to provide information about the object paying such order placed by the user. If you forget to include the access token in such request you would also obtain a response but it would not be representative of the particular situation of the user.

POST /v2/orders/estimate HTTP/1.1
Host: exchange.api.bity.com
Authorization: Bearer uk4pe6eneib8xia6Ievaipae6suchieziekie3tu6aiT7oa7
Content-Type: application/json

{
  "input": {"currency": "ETH"},
  "output": {"currency": "CHF", "amount": "200"}
}

and the corresponding example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "input" : {
    "amount" : "1.398165328416715000",
    "currency" : "ETH",
    "object_information_optional" : true
  },
  "output" : {
    "amount" : "200",
    "currency" : "CHF",
    "minimum_amount" : "7.13"
  },
  "price_breakdown" : {
    "customer_trading_fee" : {
      "amount" : "0.011094292471898504",
      "currency" : "ETH"
    }
  }
}

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. Additionally, your application must adequately inform the user of the additional fee.

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