@bity/preact-exchange-client
A user interface to interact with the Bity Exchange API.
Installation
npm install @bity/preact-exchange-client preact@8 @bity/styles @bity/api
Deploy as an interfacing service
It is possible to deploy the component as an interfacing service. node serve.js starts a very simple web server which reads a configuration file from
/etc/bity-preact-exchange-client/config.js. This configuration file is the
configuration object which is used by the component. This path is currently not
configurable.
There is a pre-configured example-interfacing-service.config.js which
changes can be made to. It is commented explaining what the fields mean.
Be sure to place the component under the same domain as where you will integrate it. Because of web security policies, authentication will not work if you don't.
For example, if there is a web dashboard which is available on https://my.bity.com, the interfacing service should be hosted under it, for example: https://my.bity.com/exchange-client .
Again, do not under any circumstance host it any other way. Hosting it on its own sub-domain will cause authentication issues.
Usage
index.jsx:
import { h, render } from 'preact';
import ExchangeClient from '@bity/preact-exchange-client';
const root = document.querySelector('#root');
render(<ExchangeClient
exchangeApiUrl="https://exchange.api.bity.com"
legacyV2ApiUrl="https://bity.com"
/>, root);
index.html:
<html>
<head>
<title></title>
<!-- Bity's base styles - without this, everything would look horrible. -->
<link rel="stylesheet" href="./node_modules/@bity/styles/index.css"/>
<!-- Yes, you read that right: preact. This react component is built on it, so we pull its built styles from there. -->
<link rel="stylesheet" href="./node_modules/@bity/preact-exchange-client/index.css"/>
</head>
<body>
<div id="root"></div>
<script src="./index.js"></script>
</body>
</html>
Prefilled information
It is possible to prefill the amount to be exchanged and the currencies of the exchange by specifying these values in the configuration file:
import { h, render } from 'preact';
import ExchangeClient from '@bity/preact-exchange-client';
const root = document.querySelector('#root');
const defaultOrderParameters = {
inputCurrency: 'CHF',
outputCurrency: 'BTC',
inputAmount: '200',
};
render(<ExchangeClient defaultOrderParameters={defaultOrderParameters} />, root);
It is also possible to pre-fill the output address of the exchange (ie. The address Bity will send the funds to) when the output is a crypto currency. An address may be specified for each currency. The output address of the exchange will be pre-filled with the address corresponding to the currency selected by the user; Optionally, if an address was specified for this currency, the user may be prevented from modifying it:
defaultOrderParameters: {
inputCurrency: 'CHF',
outputCurrency: 'ETH',
inputAmount: '200',
// Addresses used to pre-fill the exchange output address.
outputAddressesForPrefilling: {
NYM: 'n1qh0mxa7ka8gtxm4zuh2mql0mqn3kgnp7jcsqy3',
ETH: '0x24305d091f79ee490a34de080b0db5773be5bef4',
},
// Whether the user should be prevented from modifying prefilled output addresses.
lockOutputAddressWhenPrefilled: false,
};
Special care must be taken with these addresses, in particular when the user is prevented from modifying the output address: The exchange client will place the order with the address "as-is". Note that pre-filling an address still requires the user to confirm it.
Restrict inputs to certain currencies
Some companies only choose to support certain currencies for various reasons. To restrict the type of currencies a user can send and receive, the following properties can be passed (examples):
restrictCurrenciesToSend={['CHF']}
restrictCurrenciesToReceive={['ETH']}
This will restrict trading to the single pair CHF → ETH.
Mind that the amount and currencies of the exchange must be prefilled if the currencies to send or receive are restricted. Special care must be taken to ensure the prefilled values respect the specified restrictions. Refer to the [corresponding section][#prefilled-information] for instructions on how to prefill these values.
Limit max amount in the exchange UI
Integrators may choose to limit the maximum amount their users can exchange.
This can be done through the amountTooLargePredicate property. For example:
import { h, render } from 'preact';
import ExchangeClient from '@bity/preact-exchange-client';
const root = document.querySelector('#root');
const amountTooLargePredicate = function(amount, currency, direction) {
if (direction == 'input' && currency == 'ETH')
return amount > 10;
if (direction == 'output' && currency == 'CHF')
return amount > 10000;
return false;
}
render(<ExchangeClient
amountTooLargePredicate={amountTooLargePredicate}
restrictCurrenciesToSend={['ETH']}
/>, root);
Bity dashboard URL
Specify the dashboard URL to navigate to. This will display a "dashboard" button.
bityDashboardUrl="https://my.bity.com"
Configuring to ask user for login
Depending on the context, sometimes it's not necessary to ask the user to chose if they want to login as a Bity user or a guest. In order to determine this, you can pass a function which returns true or false.
shouldAskForLogin={(): boolean => { /* true or false */ }}
Events
Below are a list of events which can be hooked into.
onOrderCreated={(order: Order): void => { /* ... */ }}
onOrderCreationFailure={(errors: { message: string }[]): void => { /* ... */ }}