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

Audience

This document is meant for:

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:

Definitions

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:

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.