Tokenization
So you chose to implement your service through our Tokenization model, great! In this page we will guide you to achieve the basic operations you will need to perform as you advance with the development:
- Create and activate a new Customer
- Create Accounts for the Customer
- Perform a Funding operation
- Execute a Payment
- Perform a Payout operation
Create new customer
The creation of a Customer includes several aspects. For instance, an initial limit regarding the amount of transactions that can be executed will be set through the Trustlevels. During the customer creation, Nexus will create a blockchain account with the supplied address. In case Stellar is used for the tokenization, Nexus will also take care of creating a Stellar transaction envelope, which contains one or multiple signatures. Subsequently, Nexus will take care of creating a Stellar trustline between the newly created customer and the issuer of the token.
Create
| 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 |
|---|---|
code |
(string) unique identifier for this customer |
trustlevelCode |
one of values you previously defined in the initial setup. |
account |
object that holds the following information: - address: (string) public key of the customer - tokenSettings: (object) following additional token settings: -- allowedTokens: (array of strings) listing the accepted token codes (e.g. "CUSD", "TOK"...) |
Submit
The last step to confirm the creation of a new customer is to sign the envelope returned in the previous step. Signing is done locally using a SDK or tools provided by the designated blockchain. The private key of the corresponding address given during Customer creation is required to sign. The signed envelope must be submitted by making a request to the following API endpoint:
| Request | Endpoint |
|---|---|
| POST | baseURL/token/envelope/submit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
cryptoCode |
(required) (string) CryptoCode for the Envelope |
envelope |
(required) (string) encoded string of the transaction envelope signed by the Customer |
hash |
(string) |
cryptoCode |
(boolean) Do not verify that the envelope is already created |
Add an account
During Customer creation, an account will be automatically added. There can be use cases in which a customer wants to hold different accounts (e.g. due to different tokens). Nexus allows you to facilitate this process by calling the following endpoint to create additional accounts.
| 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 |
|---|---|
address |
public key of the customer |
tokenSettings |
an object holding the following additional token settings |
allowedTokens |
array listing the accepted token codes (e.g. "CUSD", "TOK"...) |
As in the customer's creation procedure, the call to the submit endpoint will also be called to finalize the operation and add it to the Stellar ledger.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/envelope/submit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
cryptoCode |
(required) (string) CryptoCode for the Envelope |
envelope |
(required) (string) encoded string of the transaction envelope signed by the Customer |
hash |
(string) |
cryptoCode |
(boolean) Do not verify that the envelope is already created |
Funding an account
Funding is the process of issuing new tokens and sending these to a customer's account buying the token. Payment processing is done outside of Nexus, the funding call should be done after a (when required) payment is finished successfully.
The endpoint to initiate the funding procedure is the following:
| Request | Endpoint |
|---|---|
| POST | baseURL/token/fund |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
customerCode |
(string) Customer identifier |
accountCode |
(float) Account identifier |
paymentMethodCode |
(float) PaymentMethod identifier |
amount |
(float) amount of stablecoin to be purchased |
tokenCode |
(string) the desired token code, e.g. "CUSD", "TEUR"... |
Depending on the token settings additional signing may be required by the designated account. This is equal to the previous steps for signing and submitting.
Execute a payment
Create payment request
To start sending tokens to another account you can initiate payment operations. The following API endpoint can be called:
| Request | Endpoint |
|---|---|
| POST | baseURL/token/payments |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
payments |
(array of objects) one or multiple payments, requiring the following information: - sender: (string) sender address - receiver: (string) receiving address - tokenCode: (string) the token code this transaction need to use - amount: (float) amount to be transferred |
Customer signs transaction
Once the payment request above is created, the customer needs to sign the Stellar envelope to proceed with the transfer of tokens. This can be achieved by signing it with the customer's private key, for instance by using the Stellar SDK.
Submit
Once the Stellar envelope has been signed by the customer, the transaction can be sent to Nexus by using the endpoint below.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/envelope/submit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
cryptoCode |
(required) (string) CryptoCode for the Envelope |
envelope |
(required) (string) encoded string of the transaction envelope signed by the Customer |
hash |
(string) |
cryptoCode |
(boolean) Do not verify that the envelope is already created |
Payout from an account
At some point, a merchant or customer will decide to cash out their tokens in exchange of fiat currency. To carry out this process, the following API endpoint can be called.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/payout |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
accountCode |
(string) code of the source account |
paymentMethodCode |
(string) payment method to be used to transfer the fiat currency |
tokenCode |
(string) code of the token to payout |
amount |
(float) amount of token to be cashed out |
callbackUrl |
(string) callback url to receive feedback on the status of the operation |
memo |
(string) additional field to store additional information you might need |
Create a token
When a customer wants to create a new token (Internal/External), Nexus allows you to facilitate this process by calling the following endpoint.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/tokens |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
code |
(string) unique code of the token (required) |
name |
(string) name of the token (required) |
tokenType |
(string) type of the token (PeggedByCurrency / PeggedByToken / PeggedByAsset) (required) |
ownerType |
(string) owner type of the token (Internal / External) (required) |
assetType |
(string) asset type of the token (Native / Other) |
issuerAddress |
(string) issuer address of the token (required in case of external assets) |
rate |
(decimal) rate of the token |
peggedBy |
(string) token/currency that pegs this token (Currency / Token / Asset) |
settings |
token settings (as mentioned below) |
data |
(dictionary<string,string>) optional data |
Settings
| Key | Value |
|---|---|
accountLimit |
(long) the account limit (default = null) |
overallLimit |
(long) the overall limit (default = null) |
Returnable |
(bool) can this token be returned? (default = true) |
freezeAfterFund |
(bool) freeze after fund? (default = false) |
stellarSettings |
stellar settings of the token (as mentioned below - for internal tokens only) |
StellarSettings
| Key | Value |
|---|---|
authorizationRequired |
(bool) is authorization required? (default = true) |
authorizationRevocable |
(bool) is authorization revocable? (default = true) |
authorizationImmutable |
(bool) is authorization immutable? (default = false) |
clawbackEnabled |
(bool) is clawback enabled? (default = true) |
In the case of Internal tokens, the token is created with the status = 'Active'.
In the case of External tokens, the token is created with the status = 'Created' and a Low Weight Signing Key is returned. To complete the token creation process the customer needs to add this key as a signer to their issuer with sufficient weight to meet the low threshold requirement. After this, call the following endpoint to activate the token.
Activate a token
Use this endpoint to activate an external token.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/tokens/{tokenCode} |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
tokenCode |
(required) (string) unique identifier of the token |
Trading of assets
Buy order
Customer A wants to buy some of the Gold assets in exchange of fiat currency. To carry out this process, they must create a 'Buy' order using the following API endpoint.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/orders |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
accountCode |
(string) code of the source account |
buying |
(string) token code and (decimal) buying amount |
selling |
(string) token code and (decimal) selling amount |
action |
(string) action of this token order (buy/sell) |
type |
(string) type of this token order (market/limit) |
expiring |
(dateTime) timestamp this token order expires |
memo |
(string) custom reference of this token order that is stored on the blockchain |
Once this 'buy' order is created, it is checked against the existing orderbook for that asset pair. If the submitted order is a marketable order (for a marketable buy limit order, the limit price is at or above the ask price; for a marketable sell limit order, the limit price is at or below the bid price), it is filled at the existing order price for the available quantity at that price. If the order is not marketable (i.e. does not cross an existing order), the order is saved on the orderbook until it is either consumed by another order, consumed by a path payment, or canceled by the account that created the order.
Sell order
Customer B wants to sell some of the Gold assets in exchange of fiat currency. To carry out this process, customer has to create a 'Sell' order using the same endpoint as mentioned above and then sign the transaction envelope.
Orders are executed on a price-time priority, meaning orders will be executed based first on price; for orders placed at the same price, the order that was entered earlier is given priority and is executed before the newer one.
Once the orders of customer A and customer B matches, their accounts will be updated accordingly.
Cancel an order
To cancel a particular order, the following API endpoint can be used.
| Request | Endpoint |
|---|---|
| PUT | baseURL/token/orders/cancel |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
tokenOrderCode |
(string) code of the token order |
TransactionEnvelope is returned that must be signed by the customer and sent to the Submit endpoint.
Customer signs transaction
Customer needs to sign the Stellar envelope to proceed with the operation (buy order/sell order/cancel order). This can be achieved by signing it with the customer's private key, for instance by using the Stellar SDK.
Submit
Once the Stellar envelope has been signed by the customer, the transaction can be sent to Nexus by using the endpoint below.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/envelope/submit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
cryptoCode |
(required) (string) CryptoCode for the Envelope |
envelope |
(required) (string) encoded string of the transaction envelope signed by the Customer |
hash |
(string) |
cryptoCode |
(boolean) Do not verify that the envelope is already created |
Get orders
To get the orders of an account, the following API endpoint can be used.
| Request | Endpoint |
|---|---|
| GET | baseURL/token/orders |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Query parameters
| Key | Value |
|---|---|
customerCode |
(string) code of the customer |
accountCode |
(string) code of the source account |
tokenOrderCode |
(string) code of the token order |
createdFrom |
(string) get only token orders created after from date |
createdTill |
(string) get only token orders created before till Date |
status |
(string) status of the token order (buy/sell) |
action |
(string) action of the token order (buy/sell) |
type |
(string) type of the token order (market/limit) |
tokenOrderTradeCode |
(string) blockchain code of the token order |
isPartial |
(bool) set it to true if the token order is partially executed |