Broker
Now that the general settings have been defined, let's focus on implementing a simple, initial version of a Broker platform through Nexus. Here are the steps we will go through:
- Create and activate a new Customer
- Create an Account to enable Transactions
- Perform a Buy operation
- Perform a Sell operation
NOTE
You can find a sample application to bootstrap your development in the Sample applications section.
Create a customer
| Request | Endpoint |
|---|---|
| POST | baseURL/customer |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
customerCode |
(required) (string) unique identifier for this customer |
portfolioCode |
(string) grouping of customers (when using portfolios) |
trustLevel |
(required) (string) one of trust levels you previously defined in the initial setup. |
status |
(string) possible values: "NEW", "ACTIVE" |
currencyCode |
(string) example: "EUR" |
Activate a new customer
NOTE
This step is required only if during the creation of a new customer the status option was set to NEW. If already set to ACTIVE you can skip this step.
| Request | Endpoint |
|---|---|
| PUT | baseURL/customer/{customerCode} |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
customerCode |
(required) (string) unique identifier for this customer |
Request body (JSON)
| Key | Value |
|---|---|
status |
(required) (string) "ACTIVE" |
Create an Account for the customer
To allow the Customer to execute Transactions, you need to create at least one Account, which basically means to create a pair of addresses, namely the Withdraw address and the Deposit address for each crypto-currency your customers decide to use. Once activated, the addresses are internally whitelisted and therefore considered safe for future transactions.
Below you will find the API call to create an account.
NOTE
The activation of an account requires only to specify one of the two required addresses. The reason behind this is that Nexus automatically creates a deposit address once you activate an account, for each crypto the customer desires to use. Neat!
| Request | Endpoint |
|---|---|
| POST | baseURL/customer/{customerCode}/accounts |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
customerCode |
(required) (string) unique identifier for this customer |
Request body (JSON)
| Key | Value |
|---|---|
customerCryptoAddress |
(required) (string) new customer's wallet address (Withdraw address in Nexus terminology) |
dcCode |
(string) in case the currency cannot be automatically determined, this is code for the crypto-currency of the customer's wallet (visit the Crypto-currency section for information regarding the ones currently supported) |
Buy transaction
At this point, your customers are eager to buy their crypto for the first time, let's make that happen! For a quick overview on how it works in Nexus, please check our knowledge base at the Broker - Buy section.
In the API call below, you will have to specify a Payment method. Depending on the chosen one, fee settings and callback URLs will differ. Once the request with the fiat amount is sent, Nexus will process it by calculating the fees and thus the final amount in crypto-currency to be sent to the customer's wallet.
Just as a reminder, these calculations are affected by the initial settings you have defined in the Crypto-currencies and internal pricing section during the initial setup.
NOTE
Do you remember when we initially set-up the trust levels for our customers? Keep in mind that those limits will affect the transaction volume, potentially leading to transaction errors if those limits are reached.
Simulate a Buy transaction
| Request | Endpoint |
|---|---|
| POST | baseURL/buy/broker/simulate |
Headers
| Key | Value |
|---|---|
api_version |
(required) (string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
paymentMethodCode |
(required) (string) see Payment methods for further details. |
accountCode |
(required) (string) unique id of a customer's account |
amount |
(required) (float) amount to buy (in fiat) |
currency |
(required) (string) e.g. "EUR" |
Create a Buy transaction
| Request | Endpoint |
|---|---|
| POST | baseURL/buy/broker |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
paymentMethodCode |
(required) (string) see Payment methods for further details. |
accountCode |
(string) unique id of a customer's account |
amount |
(float) amount to buy (in fiat) |
currency |
(string) e.g. "EUR" |
ip |
(string) IP of customer, for logging/analytics purposes |
Execute a transaction based on payment result
| Request | Endpoint |
|---|---|
| POST | baseURL/Transaction/execute |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
transactionCode |
(required) (string) Code of the transaction to execute |
resultCode |
(required) (string) Result of the payment. |
Sell transaction
Now that you allowed your customer to buy their first crypto-currency, they are very excited about a recent value increase of the crypto they previously bought and they want to sell it to cash the profit. Here's how you can allow them to do so! Again, to have a better understanding on how Nexus works, refer to the Broker - Sell section of our knowledge base.
Create a Sell transaction
| Request | Endpoint |
|---|---|
| POST | baseURL/sell/broker |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
accountCode |
(required) (string) the source account, where the currency will be sent from |
paymentMethodCode |
(required) (string) payment method that will be used to send the fiat currency |
cryptoAmount |
(float) crypto-currency amount to sell |
ip |
(string) IP of customer, for logging/analytics purposes |
Update Sell transaction status
| Request | Endpoint |
|---|---|
| PUT | baseURL/transaction/{transactionCode} |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.1 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
transactionCode |
(required) (string) Code of the transaction to execute |
Request body (JSON)
| Key | Value |
|---|---|
statusCode |
(required) new status to be set. Options: SellCompleted (if the previous was either ToPayout or PayoutConfirming) or PayoutConfirming (if previous was ToPayout). Check the Broker - Sell for a more in-depth explanation on the statuses. |
Additional useful endpoints
Retrieve buy/sell prices
| Request | Endpoint |
|---|---|
| GET | baseURL/prices/{currency} |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
currency |
(required) (string) example: "EUR" |
Get reserves of crypto and fiat currencies on Exchanges, HotWallet and Coldstore
| Request | Endpoint |
|---|---|
| GET | baseURL/reserves |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |