Broker
This section shows how to implement a basic Broker platform using Nexus. The following steps are covered:
- Create and activate a new Customer
- Create an Account to enable Transactions
- Perform a Buy operation
- Perform a Sell operation
For automated reserve management, see Tradebot overview and Tradebot — Broker model.
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 the trust levels previously defined in Trust levels. |
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. In practice, this means creating an address pair: Withdraw address and Deposit address for each crypto-currency your customers use. Once activated, these addresses are internally whitelisted and treated as safe for future transactions.
Below you will find the API call to create an account.
NOTE
To activate an account, you only need to specify one of the two addresses. Nexus automatically creates a deposit address for each crypto-currency the customer uses.
| 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 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 ready to buy crypto for the first time. For a quick workflow overview, see Broker - Buy.
Broker buy transactions use the custodian transaction backend. The broker-specific API uses the BROKERBUY transaction type and returns the same transaction response shape used by custodian transaction endpoints.
Broker transaction route summary
| Flow | Endpoint |
|---|---|
| Simulate buy | baseURL/brokerbuy/simulate |
| Create buy | baseURL/brokerbuy |
| Commit staged buy | baseURL/transactions/custodian/{txCode}/commit |
| Simulate sell | baseURL/paymentrequest/brokersell/simulate |
| Create sell | baseURL/paymentrequest/brokersell |
| Set payout confirming | baseURL/transactions/custodian/{transactionCode}/payoutconfirming |
| Complete payout | baseURL/transactions/custodian/{transactionCode}/payout |
In the API calls below, you must specify a Payment method. Depending on the chosen one, fee settings and callback URLs differ. Once the request with the fiat amount is sent, Nexus calculates the fees and the resulting crypto-currency amount to be sent to the destination wallet.
These calculations are affected by the initial settings defined in Crypto-currencies and internal pricing.
NOTE
Trust level limits affect transaction volume and may lead to transaction errors when limits are reached.
Simulate a Buy transaction
| Request | Endpoint |
|---|---|
| POST | baseURL/brokerbuy/simulate |
Headers
| Key | Value |
|---|---|
api_version |
(required) (string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
customerCode |
(required) (string) unique identifier of the customer |
accountCode |
(string) Nexus generated account code. This is optional when your integration can resolve the broker account automatically |
bankAccountNumber |
(string) customer bank account number associated with this buy for reporting purposes |
currencyCode |
(required) (string) three-letter fiat currency code, for example EUR |
cryptoCode |
(required) (string) crypto-currency code, for example BTC |
fiatValue |
(required) (number<decimal>) fiat amount to buy |
destinationAddress |
(required) (string) blockchain destination address where Nexus sends the purchased crypto |
requestedPrice |
(number<decimal>) optional buy price override. Nexus validates it against the payment method wiggle room |
paymentMethodCode |
(required) (string) see Payment methods for details |
callbackUrl |
(string) optional callback override for this transaction |
blockchainMessage |
(string) optional blockchain message when the selected blockchain supports it |
data |
(dictionary<string,string>) optional custom metadata |
paymentReference |
(string) optional payment reference stored on the transaction |
Response body (JSON)
The simulation returns a transaction object aligned with the custodian transaction response model.
| Key | Value |
|---|---|
transaction.transactionCode |
Nexus transaction code |
transaction.type |
BROKERBUY |
transaction.status |
SIMULATED |
transaction.customerCode |
customer code |
transaction.accountCode |
account code |
transaction.cryptoCode |
crypto-currency code |
transaction.currencyCode |
fiat currency code |
transaction.paymentMethodCode |
payment method code |
transaction.destinationCryptoAddress |
destination wallet address |
transaction.requestedAmounts |
requested cryptoAmount, fiatValue, and cryptoPrice |
transaction.executedAmounts |
calculated cryptoAmount, fiatValue, and cryptoPrice |
transaction.fees |
fee object with partner, bank, and network fee values |
transaction.balanceMutation |
balance mutation object. For BROKERBUY, both values are 0 |
transaction.paymentReference |
optional payment reference |
transaction.data |
optional custom metadata |
Create a Buy transaction
| Request | Endpoint |
|---|---|
| POST | baseURL/brokerbuy |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
The buy create request accepts the full broker buy request body plus the stage flag.
| Key | Value |
|---|---|
customerCode |
(required) (string) unique identifier of the customer |
accountCode |
(string) Nexus generated account code. This is optional when your integration can resolve the broker account automatically |
bankAccountNumber |
(string) customer bank account number associated with this buy for reporting purposes |
currencyCode |
(required) (string) three-letter fiat currency code, for example EUR |
cryptoCode |
(required) (string) crypto-currency code, for example BTC |
fiatValue |
(required) (number<decimal>) fiat amount to buy |
destinationAddress |
(required) (string) blockchain destination address where Nexus sends the purchased crypto |
requestedPrice |
(number<decimal>) optional buy price override. Nexus validates it against the payment method wiggle room |
paymentMethodCode |
(required) (string) see Payment methods for details |
callbackUrl |
(string) optional callback override for this transaction |
blockchainMessage |
(string) optional blockchain message when the selected blockchain supports it |
data |
(dictionary<string,string>) optional custom metadata |
paymentReference |
(string) optional payment reference stored on the transaction |
stage |
(boolean) when true, Nexus creates the transaction with status Staged. You must commit it in a second step |
Response body (JSON)
The buy create endpoint returns the custodian-style transaction object. In the public API contract for BROKERBUY, transaction.status is Sending when stage is omitted or false, and Staged when stage is true.
| Key | Value |
|---|---|
transaction.type |
BROKERBUY |
transaction.status |
Sending when created directly, or Staged when stage is true |
transaction.destinationCryptoAddress |
destination wallet address |
transaction.requestedAmounts |
requested amount values |
transaction.executedAmounts |
executed amount values |
transaction.fees |
fee object |
transaction.balanceMutation |
0 crypto and 0 fiat at creation time |
transaction.data |
optional custom metadata |
Commit a staged Buy transaction
Use this endpoint only when the buy was created with stage: true.
Although this is a broker buy flow, staged broker buys are committed through the shared custodian transaction endpoint. There is no separate /brokerbuy/{txCode}/commit route.
| Request | Endpoint |
|---|---|
| POST | baseURL/transactions/custodian/{txCode}/commit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
txCode |
(required) (string) staged transaction code |
Response body (JSON)
The commit endpoint returns the same custodian-style transaction object as the create and simulate endpoints.
| Key | Value |
|---|---|
transaction.type |
BROKERBUY |
transaction.status |
Sending |
transaction.transactionCode |
committed transaction code |
transaction.destinationCryptoAddress |
destination wallet address |
transaction.requestedAmounts |
requested amount values |
transaction.executedAmounts |
executed amount values |
transaction.fees |
fee object |
transaction.balanceMutation |
0 crypto and 0 fiat at commit time |
transaction.data |
optional custom metadata |
Sell transaction
After a customer has bought crypto-currency, they may want to sell at a later time. The following section shows how to support that flow. For more context, see Broker - Sell.
Broker sell transactions use the custodian payment request flow. The broker-specific API uses the BROKERSELL transaction type and returns the custodian transaction response shape.
Simulate a Sell transaction
| Request | Endpoint |
|---|---|
| POST | baseURL/paymentrequest/brokersell/simulate |
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 of the customer |
accountCode |
(required) (string) source account code |
currencyCode |
(required) (string) three-letter fiat currency code, for example EUR |
cryptoCode |
(required) (string) crypto-currency code |
fiatValue |
(number<decimal>) requested fiat payout amount. Provide this or cryptoAmount, but not both |
cryptoAmount |
(number<decimal>) requested crypto amount to sell. Provide this or fiatValue, but not both |
requestedPrice |
(number<decimal>) optional sell price override. Nexus validates it against the payment method wiggle room |
paymentMethodCode |
(required) (string) payment method used for fees and payout configuration |
callbackUrl |
(string) optional callback override for this transaction |
data |
(dictionary<string,string>) optional custom metadata |
paymentReference |
(string) optional payment reference stored on the transaction |
Response body (JSON)
| Key | Value |
|---|---|
transaction.type |
BROKERSELL |
transaction.status |
SIMULATED |
transaction.destinationCryptoAddress |
single-use deposit address returned by the API for the customer payment |
transaction.requestedAmounts |
requested amount values |
transaction.executedAmounts |
calculated payout values |
transaction.fees |
fee object |
transaction.balanceMutation |
expected payout values without customer custody balance tracking |
transaction.data |
optional custom metadata |
Create a Sell transaction
| Request | Endpoint |
|---|---|
| POST | baseURL/paymentrequest/brokersell |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Use the same request and response fields as the simulation endpoint.
When created, the transaction status is Initiated. The sell response exposes the payment address in transaction.destinationCryptoAddress. After the customer sends the crypto to that address, Nexus tracks the blockchain payment and moves the transaction through the payout flow.
Payout flow for a Sell transaction
If the LabelPartner has the Payouts feature enabled, a confirmed BROKERSELL transaction moves to ToPayout. From there, operators can use the following endpoints.
Set Sell transaction to payout confirming
| Request | Endpoint |
|---|---|
| PUT | baseURL/transactions/custodian/{transactionCode}/payoutconfirming |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
transactionCode |
(required) (string) broker sell transaction code |
Request body (JSON)
| Key | Value |
|---|---|
customerBankAccountId |
(guid) optional customer bank account used for payout |
paymentReference |
(string) optional payout reference |
Response body (JSON)
| Key | Value |
|---|---|
transaction.type |
BROKERSELL |
transaction.status |
PayoutConfirming |
Complete Sell payout
| Request | Endpoint |
|---|---|
| PUT | baseURL/transactions/custodian/{transactionCode}/payout |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
transactionCode |
(required) (string) broker sell transaction code |
Request body (JSON)
| Key | Value |
|---|---|
customerBankAccountId |
(guid) optional customer bank account used for payout |
paymentReference |
(string) optional payout reference |
Response body (JSON)
| Key | Value |
|---|---|
transaction.type |
BROKERSELL |
transaction.status |
COMPLETED |
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, hot wallets, and cold stores
| Request | Endpoint |
|---|---|
| GET | baseURL/reserves |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |