Welcome to the product guide for our Exchange API, also referred to as the Crypto Exchange API in the product page. We wrote this guide as an intermediate step between our product page and the API endpoints documentation where we describe all possible usages and nuances of the Exchange API without delving into code nor API responses.
In a nutshell, the Exchange API gives programmatic access to our engine and it allows users to exchange up to 1,000 CHF per day and 100,000 CHF per year without identity verification, or above this limit with identity verification. The Exchange API was designed for individuals that need to automate currency exchange orders as well as for third parties wanting to offer a seamless crypto exchange service to their users. Additionally, we offer profit-sharing incentives to trustworthy third parties willing to partner with us.
More generally, the Exchange API, as a Bity product, comes with a collection of user interfaces that assist end users in fulfilling their crypto exchange orders, obtaining information about the status of their orders, and receiving customer support.
For those of you interested in learning more or getting started, we hope to be able to provide you with everything you need to help you make the most out of our Exchange API in this guide.
If you are interested in the general features of the Exchange API, how we calculate our exchange prices, or how crypto exchange orders are placed and processed, jump over to the section for end users.
If you are familiar with the Exchange API features for end users and are ready to integrate them into your own system, jump over to the section for system integrators. This section provides more detailed information related to the Exchange API, including how to communicate with it, where you can go for technical support, and other relevant insights for a successful integration.
Finally, if you are interested in integrating our Exchange API into your system or platform while also wanting to engage in a profit-sharing partnership with us for the orders placed through your system, jump over to the section for financial partners.
We consider end users as the individuals placing orders using the Exchange API. End users are expected to be guided through the whole order placement workflow via a graphical interface that integrates with the Exchange API.
In addition to the operations of the Exchange API, we provide a number of graphical interfaces and support channels. These are designed to assist end users so that they can understand and troubleshoot instances involving their funds.
The next few subsections cover details about the exchange services accessible via the Exchange API, the lifecycle of placed orders, as well as assisting tools and support channels.
The Exchange API allows an end user to buy crypto (fiat → crypto), to sell crypto (crypto → fiat), as well as to trade cryptos (crypto → crypto). The Exchange API can be used for currency exchange (i.e. when the exchanged funds are sent to the end user) in all cases. Money transfer (i.e. when the exchanged funds are sent to a person different than the end user) is also possible but only with identity verification.
We are committed to offering a competitive price. This is determined by the liquidity pools at our disposal and the additional fees that exist out of necessity to ensure that end users receive their funds.
Examples of additional fees may include fees charged by the cryptocurrency network (anything → crypto), SEPA network (crypto → fiat), and Forex fees when orders are done using CHF. Finally, we charge a small handling fee. This is where our profits come from.
The price we show is all-inclusive. The fee taken by Bity as well as the fee taken by the partner (if any) are visible in amount estimations and in the order details.
This subsection describes in more detail the steps an order goes through, as well as the differences between placing orders with and without an account.
Orders can be placed via HTTP request to the Exchange API defining the desired operation.
The typical lifecycle of an order looks as follows:
Note that, as bank transfers may take days, fiat to crypto orders are kept open indefinitely and the conversion rate used is fixed when we receive the funds.
TEMPORARY CAVEAT
Neither order execution nor price is guaranteed if the payment arrives after 10
minutes. We are working on providing a more deterministic order execution
window and outcome.
Placing orders through the Exchange API can be done without having an account. In accordance with current Swiss regulations, a non-identified user is able to buy or sell the equivalent of a maximum of 1,000 CHF per day and 100,000 CHF per year. This holds true only for currency exchange operations; that is where the destination of the exchanged funds is in control of the same user that placed the order. In order to sell and buy more than 1,000 CHF daily or 100,000 CHF yearly or to send funds to another person, the user will have to create an account and become a KYC verified customer with us in my.bity.com.
More specifically, a non-KYC verified user can perform the following:
| From | To | Limit | Currency exchange | Money transfer |
|---|---|---|---|---|
| Crypto | Fiat | 1,000 CHF daily and 100,000 yearly | Allowed | Not allowed |
| Fiat | Crypto | 1,000 CHF daily and 100,000 yearly | Allowed | Not allowed |
| Crypto | Crypto | 1,000 CHF daily and 100,000 yearly | Allowed | Not allowed |
These quotas are upheld by limiting the amount that a transacting object may exchange. This is done by keeping track of the volume received from and transferred to each cryptocurrency address and fiat bank account. The Exchange API won’t allow placing orders that would make the annual transacted volume of the involved accounts go beyond their quota. Note that the Exchange API will reject placing crypto-to-fiat orders whose IBAN destination is from a high-risk country.
Currency exchange restrictions are guaranteed in fiat-to-crypto thanks to a wallet ownership proof we require at the time of placing the order. This wallet ownership proof can be produced by signing a message with the private key associated with the address that will receive the exchanged funds.
Upon successfully placing an order, the API will respond with an identifier associated with that order. The user will then be able to check the order’s status at any given time using the provided identifier at the order status page (https://go.bity.com/order-status).
Placing orders through the Exchange API can also be done using the credentials of an account. This method is required for users wanting to circumvent the limitations described in the previous section. Once a customer has a KYC verified account on our site, they will be able to buy, sell, and trade a larger volume of crypto as specified in our account limits table. They will also be allowed to perform money transfer operations.
Creating an account can be done directly on the registration page, and the KYC verification of an account can be initiated while logged into my.bity.com. In cases where a customer is creating an account from a high-risk country, a video call proving their identity will be required. For detailed instructions on how to create and verify an account on our site, feel free to consult Bity’s FAQ.
Authentication happens through OAuth, please consult the guides and API documentation available on https://doc.bity.com/.
This subsection details the tools we provide to end users so they are able to properly manage their orders placed through the Exchange API.
After an order is placed through the Exchange API, its status can be viewed at the order status page (https://go.bity.com/order-status) introducing its reference number. With the goal to protect our customers’ privacy, only non-sensitive information regarding the order is displayed. Full details of the order can be checked if accessing the status page with the same device using stored cookies. The full details of orders placed with an account can be consulted logging into my.bity.com.
If any issues are encountered for an order placed through the Exchange API, all questions regarding troubleshooting and refunds should be directed to our support team via live chat. For orders placed without an account, the live chat needs to be initiated directly from the corresponding order status page. For orders placed with an account, the live chat needs to be initiated while logged into my.bity.com.
Graphical interfaces that allow placing orders through the Exchange API will always facilitate a link to the order status page (https://go.bity.com/order-status) so that end users can easily reach our support team.
An integrator is someone that maintains a project that integrates with our Exchange API endpoints with the goal of exchanging currencies via our engine. This integration may or may not provide a graphical interface but, in both cases, the system needs to keep up with the changes of the Exchange API.
Anyone interested in integrating the Exchange API, can get started with the links below:
The next few subsections expand on other concerns integrators may have such as understanding common Exchange API use cases, best practices for integrating them in graphical interfaces, staying up-to-date with the evolution of the API endpoints, or requesting technical support.
An integrator who wishes to automate the order lifecycle as much as possible may be interested in reading examples of some common use cases of the Exchange API and how they can be implemented.
UPCOMING CONTENT
Allow crypto-to-anything exchanges to anyone in your platform:
Allow fiat-to-crypto exchanges to anyone in your platform:
Allow unlimited any-to-any exchanges to our customers in your platform:
Pay your business’ fiat bills with crypto:
Enable receiving crypto-to-fiat payments from anyone for your business:
To prevent confusion when Exchange API workflows are presented to end users, graphical interfaces are expected to use what we consider UX best practices. These practices are the result of our experience in providing different user interfaces to exchange services to our customers.
UPCOMING CONTENT
As the Exchange API evolves, some endpoints may be added, changed, deprecated, or eventually removed. In order to avoid disruptions, an integrator should keep up with all changes to the Exchange API.
UPCOMING FEATURE
Soon, an integrator will be able to choose being notified of changes to the API
via a news feed.
If technical issues are encountered while using our Exchange API, please start a conversation with our support via live chat on bity.com. When launching the conversation, make sure to indicate that you are integrating with the Exchange API and to give us a detailed description of your technical problem.
A financial partner is someone who, in addition to maintaining an integration with our Exchange API within their own system, is also enjoying a share of the profits we make from the orders placed through the partner’s system.
The next few subsections explore our profit sharing agreement in detail, other benefits we offer to our partners, how to begin a partnership and request payouts, as well as some expected tasks to maintain the partnership in great health.
If after review you still have any questions or concerns, feel free to send an email to partners@bity.com and we’ll be more than happy to expand further or schedule a call to discuss.
Partners enjoy additional benefits that are not available to end users or system integrators including profit sharing based on volume, priority technical support, and promotion of your company on all of our digital marketing channels.
First and foremost, a partner is engaged in a profit sharing agreement with us. In such an agreement, a partner will receive from 10% to 30% of the customer handling fee for each successfully executed order placed through their system using our Exchange API.
The percentage is determined by the total volume exchanged monthly:
| From | To | Commission |
|---|---|---|
| 0 CHF | 1M CHF | 10% |
| 1M CHF | 2M CHF | 20% |
| 2M CHF | above | 30% |
We understand that our partners may be relying on the income generated by the profit sharing of the Exchange API. Due to this, we are committed to handle any and all technical problems a partner encounters as quickly as possible.
UPCOMING CONTENT
We are working on providing a more detailed commitment on our priority
technical support.
It is an honor for us to collaborate with partners that share our vision and values, and we want to express and share that with everyone. We list all those likeminded partners on our website, unless they explicitly express otherwise, displaying their logo, URL, and some information about them. We also provide all listed partners with greater visibility by featuring them in our social media posts, blog posts and more.
UPCOMING CONTENT
We are working on providing a comprehensive list of possible public relations
and co-op marketing opportunities with our partners.
All our partners are representing us to a degree and are, therefore, expected to ensure the following in regard to how the exchange services are presented and how well the services operate:
The partner must:
The partner is responsible of informing their key account manager, at all times, if they suspect that funds related to criminal activity are being exchanged through their platform.
Partners that do not meet the above requirements will receive notification reminders. If these are not addressed, it could lead a partner to lose their status.
For someone to be considered eligible to become a financial partner for the Exchange API they first need an account on my.bity.com and to complete our KYC verification process up to Advanced Level. If the company or the authorized signatory is located in or comes from high-risk countries, they may need to complete a video-call to verify their identity.
Once the KYC verification is complete, they can request a partnership by sending an email to partners@bity.com expressing their interest. After a background investigation that should take no longer than a week we will respond with a partnership agreement to be signed by both parties. Upon signing, the partner will be assigned a key account manager that will be the point of contact for any non-technical question.
Once the partnership is formed, we will send an API client ID that must be attached when placing orders via the Exchange API. This will ensure that any orders that originate from the partner’s users can be properly attributed and a percentage of the execution fee is added to the total payout.
UPCOMING FEATURE
We are working on making the API client ID available from a web interface.
A partners can always request a payout to their assigned key account manager, specifying the desired currency and the destination crypto address or bank account for the payout. Payouts can be done in any of our supported currencies and will be sent to the desired cryptocurrency address or bank account. Depending on the partner’s bank, payouts could take more or less time to be executed.
Any requested payout will be executed no later than the 15th of the following month. There is no minimum amount before a partner may request a payout, however a payout may only be executed if there are enough funds to cover the necessary fees for the transfer.
TEMPORARY CAVEAT
Payouts currently need to be requested and processed manually.
UPCOMING FEATURE
Soon, automatic and more flexible payout processing will be available.