Technical guide for specifying an additional fee


This document is meant for:



Partners can specify an additional fee for each order they facilitate. This fee is hereafter referred to as the “Partner Fee”. The Partner Fee is specified on a per order basis. The partner is responsible for informing the end users of the fees.

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

Implementation details

To be able to specify a partner fee, your application must be including a valid Authorization header or a valid Client-Id header in the request in order to be able to specify a partner fee. When a valid Authorization header is present, the Client-Id is unnecessary.

A valid Authorization header is naturally present in the following use cases:

The Partner Fee can be specified when estimating amounts and when placing orders. It is specified as a fraction of the input amount. If the user does not pay the expected amount, the Partner Fee is adjusted accordingly.

Your application must adequately inform the user of the fees.

Amount estimation

The Partner Fee can be specified when estimating amounts. Specifying the Partner Fee during amount estimation is required for the estimation to be representative of an order including a Partner Fee.

The following example is an estimation including a Partner Fee of 2%.

POST /v2/orders/estimate HTTP/1.1
Content-Type: application/json

  "input": {"currency": "BTC"},
  "output": {"currency": "CHF", "amount": "100"},
  "partner_fee": {"factor": 0.02}

The corresponding response is:

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

  "input": {
    "amount": "0.01453194",
    "currency": "BTC",
    "object_information_optional": false,
  "output": {
    "amount": "100",
    "currency": "CHF"
    "minimum_amount": "7.16"
  "price_breakdown": {
    "customer_trading_fee": {
      "amount": "0.00011305",
      "currency": "BTC"
    "partner_fee": {
      "amount": "0.00029064",
      "currency": "BTC"

So in this example the additional Partner Fee would be 0.0029064 BTC provided that the customer pays 0.01453194 BTC. If the customer pays a different amount, the fee will be adjusted accordingly. The amount in the input object is the actual price which includes all the fees.

Placing orders

When placing an order, the additional fee is specified in the same manner as for amount estimation. For instance for a 3% additional fee, you can specify "partner_fee": {"factor": 0.03}. A valid Authorization header or a valid Client-Id header is required.

Order details

Similarly to the example amount estimation above, the order details include a price_breakdown property which will contain the amount of the additional fee for the order, provided the order is subject to such a fee. Similarly to the other amounts in the order details, when the order is not executed yet they are an estimation and not a final value.

In case the customer pays a different amount than the indicated input amount, the additional fee is adjusted accordingly (the Partner Fee stays the same fraction of the input amount).