Exchange API Product Guide
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 5,000 CHF yearly 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.
We will soon be launching an interface built around the Exchange API, directly in our website. As of today, the best example of third-party integration with the Exchange API is the exit to fiat in MyEtherWallet. Alternatively, end users may also follow the order placement workflow by manually sending HTTP requests to the API endpoints as per the technical documentation, although this is not the recommended way.
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.
Exchange API for currency exchange and money transfer
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.
Exchange API orders
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:
- The end user successfully places an order and the Exchange API responds with the details for payment.
- The order price is guaranteed for 10 minutes while our engine awaits the payment of the funds.
- The end user sends the funds via their preferred means to the destination described in the payment details.
- Our engine, upon payment of the funds, triggers the transfer of the funds in the correct currency to the desired cryptocurrency address or bank account.
- Once completed, the order is considered fully executed.
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.
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 5,000 CHF worth of cryptocurrency annually. This holds true only for currency exchange operations, that is where the destination of the the exchanged funds are in control of the same user that placed the order. In order to sell and buy more than 5,000 CHF a year 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||5,000 CHF annual and per transaction||Allowed||Not allowed|
|Fiat||Crypto||5,000 CHF annual and per transaction||Allowed||Not allowed|
|Crypto||Crypto||5,000 CHF annual and per transaction||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 a reference number associated with that order. The user will then be able to check the order's status at any given time using the provided reference number at the order status page (soon to be launched).
Placing orders with an account
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.
We provide multiple authentication methods to place orders through the Exchange API. Graphical interfaces that allow placing orders with credentials will always support at least one of the following methods. End users may then be able to place orders with their preferred available one.
Authentication with a phone number
This authentication method allow us to associate orders with an account simply using a phone number. Using the provided phone number, we will send a code via SMS that needs to be sent back to retrieve an authentication token. This proves that the end user is in control of the provided phone number.
Authentication with OAuth
Authentication with a private key challenge
Exchange API Assisting tools
This subsection details the tools we provide to end users so they are able to properly manage their orders placed through the Exchange API.
Order status page
After an order is placed through the Exchange API, its status can be viewed at the order status page (soon to be launched) introducing its reference number. With the goal to protect our customers' privacy, only non-sensitive information regarding the order is displayed. For the time being, full details of orders placed without an account cannot be consulted. 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 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.
Common use cases
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.
Allow crypto-to-anything exchanges to anyone in your platform:
- To be added...
Allow fiat-to-crypto exchanges to anyone in your platform:
- To be added...
Allow unlimited any-to-any exchanges to our customers in your platform:
- To be added...
Pay your business' fiat bills with crypto:
- To be added...
Enable receiving crypto-to-fiat payments from anyone for your business:
- To be added...
UX best practices
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.
Keeping up with API changes
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.
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 email@example.com and we'll be more than happy to expand further or schedule a call to discuss.
Benefits for partners
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 20% 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:
- When volume is between 0 CHF to 1 CHF, the partner receives 10%.
- When volume is between 1M CHF and 2M CHF, the partner receives 20%.
- When volume is larger than 2M CHF, the partner receives 30%.
Priority technical support
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.
Public relations and marketing
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.
Duties for 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:
- Inform the user, before they place an order, that it will be executed by Bity.
- Indicate to the user, when they place an order, that by placing it they accept our terms and conditions.
- Transmit to the user, after they have placed an order, the reference number as well as a link to the status of the order in our system.
- Provide to the user a way to view all the orders they placed in our system.
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.
How to become a partner
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 firstname.lastname@example.org 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 identification code 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.
How to request payouts
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.