Get started with Solaris Digital Assets

Introduction

This guide provides step-by-step instructions for how to onboard customers onto the Solaris Digital Assets (SDA) platform from start to finish. It focuses more on the high-level process than the details of each required API resource and endpoint. However, each section contains a link to the relevant guide for further details.

Prerequisites

Before you can onboard customers onto the SDA platform, you must complete the following steps:

Authenticate with the Solaris APIs

You must authenticate with both the Solaris Digital Banking API and the Solaris Digital Assets API. Please follow the setup instructions in both of these guides:

• Digital Banking API authentication guide
• Digital Assets API authentication guide

Create Person or Business + Customer KYC

The SDA platform represents all of your customers as Entities. However, each underlying Entity requires a Person resource (for retail customers) or Business resource (for business customers). This entails collecting personal/business-related data from your customer in your signup flow and creating the respective Entity for the customer using the Digital Banking API. Additionally, each customer must successfully complete the KYC process.

Please implement the customer onboarding steps in your solution based on one of the guides below:

• Onboard a person (steps 1-4 only)
• Onboard a business (steps 1-6 only)

Step 1: Solaris Digital Assets Terms and Conditions

Before you can onboard your customer, they must first agree to the Solaris Digital Assets Terms and Conditions.

You must display all of the SDA T&C documents listed on the Solaris website and collect their consent:

• English
• German

Please ensure that your solution uses the permalinks from the website and does not directly query the PDF files.

When the customer consents to the T&Cs, call the following endpoint to register their consent in Solaris' system:

POST Accept SDA Terms and Conditions

This endpoint registers an Entity's acceptance of the Solaris Digital Assets Terms and Conditions. The API will store a UTC timestamp from when the Entity accepted the Terms and Conditions in the terms_conditions_signed_at property.

Request URL:

POST /entities/{entity_id}/terms_and_conditions

The API will respond with 201 - Created.

Click here to view the full API reference.

(Brokerage only) POST Accept Trading Terms and Conditions

If your SDA solution includes Brokerage, then the customer must also accept the Trading Terms and Conditions using a separate endpoint.

• English
• German

Request URL:

POST /entities/{entity_id}/trading_terms_and_conditions

The API will respond with 201 - Created and record the customer's acceptance on the trading_terms_conditions_signed_at property.

Click here to view the full API reference.

Step 2: Create Entity

Next, you must create an Entity for your customer.

The Entity represents the customer on the SDA platform and is inherently linked to the Person or Business resource you created in the previous step. When you create the Entity, you will have to use its unique ID to perform all actions on behalf of the customer, such as requesting Transactions or creating ApprovalRequests.

To create an Entity, call the POST Create an Entity endpoint:

Request URL:

POST /v1/entities

Request example:

{
  "type": "PERSON",
  "person_id": "5b1c711ef5cf4b7012b688616ed052d3cper"
}

Response example:

Use the id from the response for all API calls pertaining to the Entity you just created.

// 201 Created

{
  "id": "10ef67dc895d6c19c273b1ffba0c1692enty",
  "type": "PERSON",
  "person_id": "5b1c711ef5cf4b7012b688616ed052d3cper",
  "terms_conditions_signed_at": "2022-10-31T13:27:32Z",
  "state": "ACTIVE",
  "legally_closed_at": null,
  "closed_at": null,
  "created_at": "2022-10-31T13:27:32Z",
  "updated_at": "2022-10-31T13:27:32Z",
}

Click here to view the full API reference.

Step 3: Create and activate ApprovalMethod

Now that you've created an Entity, you must create an ApprovalMethod for the Entity.

An ApprovalMethod defines the multifactor authentication (MFA) mechanism that an Entity uses to approve Transactions.

The SDA platform offers multiple types of ApprovalMethods:

• AUTHY_PUSH: Uses a push notification from the Authy app. All Entity types can use this ApprovalMethod type.
• SMS: Uses an SMS one-time password (OTP) sent to the customer's registered mobile number. All Entity types can use this ApprovalMethod type.
• DSA_ED25519: Uses an ECDSA-based MFA mechanism. This ApprovalMethod is designed for automated systems or custom integrations (e.g., custom mobile apps). Only Business and Partner Entities can use this ApprovalMethod type.

• GROUP: Represents a group of approvers with a quorum. Only Business Entities can use this ApprovalMethod type.

  • Note: Only Solaris can create GROUP ApprovalMethods.

To create an ApprovalMethod, call the POST Create an ApprovalMethod endpoint:

Request URL:

POST /entities/{entity_id}/approval_methods

Request example:

{
  "type": "DSA_ED25519",
  "pub_key": "f7bdb63a96ecee424a821d1a5e1f7d582eaabac453ba0560d4e05ff67ece2f20"
}

Response example:

{
  "id": "6ec2fbc16ccb8238cbc89b3bf7ea7f39apmt",
  "entity_id": "31adbcbbcede1a7a8cffb4a0e598ad5centy",
  "type": "DSA_ED25519",
  "state": "ACTIVATED",
  "created_at": "2019-11-03T12:21:16Z",
  "updated_at": "2019-11-03T12:46:10Z"
}

Click here to view the full API reference.

Step 4: Create Account

Next, your Entity needs an Account. An Account represents an aggregation of funds of a certain type owned by an Entity.

Each Account is tied to an Entity as well as an Asset. An Asset represents a crypto asset of some sort.

Before you can create an Account, you must retrieve the Asset ID of the Asset to which the Account will be tied. Call the GET List all Assets endpoint to retrieve the complete list:

Request URL:

GET /v1/assets

Response example:

{
  "items": [
    {
      "id": "00000000000000000000000000000001asst",
      "code": "BTC",
      "description": "Bitcoin",
      "precision": 8,
      "address_validation": "^(bc(0([ac-hj-np-z02-9]{39}|[ac-hj-np-z02-9]{59})|1[ac-hj-np-z02-9]{8,87})|[13][a-km-zA-HJ-NP-Z1-9]{25,35})$",
      "tx_min_amount": "0.00001",
      "type": "BASE",
      "created_at": "2019-03-01T22:46:38Z",
      "updated_at": "2019-03-01T22:46:38Z"
    }
  ],
  "pagination": {
    "next": 0,
    "prev": 0
  }
}

Store the value returned in the id property of the Asset you would like to use with your Account.

Next, call the POST Create an Account endpoint. Use the value of id from the previous API call as the value of asset_id in this request:

Request URL:

POST /v1/entities/{entity_id}/accounts

Request example:

{
  "asset_id": "00000000000000000000000000000001asst"
}

Response example:

// 201 Created

{
  "id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
  "asset_id": "00000000000000000000000000000001asst",
  "entity_id": "10ef67dc895d6c19c273b1ffba0c1692enty",
  "balance": "0.00000000",
  "available_balance": "0.00000000",
  "type": "BASE",
  "created_at": "2019-02-02T13:41:34Z",
  "updated_at": "2019-02-02T13:41:34Z"
}

Click here to view the full API reference.

Implement ClosureRequests

The contractual relationship between a customer and Solaris Digital Assets can be terminated by both parties. To initiate a contract termination, you must create a ClosureRequest. This resource keeps track of the termination status.

After a ClosureRequest has been created, the customer will have 30 days (if the reason is CUSTOMER_WISH or COMPLIANCE_IMMEDIATE_INTERNAL) or 90 days (if the reason is ORDINARY_INTERNAL) to withdraw their assets from their accounts.

Implement the following API endpoints for handling ClosureRequests:

POST Create a ClosureRequest

This endpoint creates a ClosureRequest for the Entity specified in the request URL.

Request URL:

POST /v1/entities/{entity_id}/closure_requests

Request example:

{
  "reason": "CUSTOMER_WISH"
}

Response example:

// 201 Created
{
  "id": "6138143133c91f3235a108d31dc90805creq",
  "entity_id": "5a991ba917c829ca2ab6ce9a4ee3f9fcenty",
  "reason": "CUSTOMER_WISH",
  "state": "PROCESSING",
  "valid_until": "2021-01-01T12:35:38Z",
  "created_at": "2020-12-02T12:35:38Z",
  "updated_at": "2020-12-02T12:35:38Z"
}

Click here to view the full API reference.

POST Confirm ClosureRequest

Use this endpoint to register the customer's confirmation of their closure for ClosureRequests of type COMPLIANCE_IMMEDIATE_INTERNAL and ORDINARY_INTERNAL.

Request URL:

POST /entities/{entity_id}/closure_requests/{closure_request_id}/confirm

Response example:

{
  "id": "ae93e4dcb3d0f5d0e36a227a94ff39e5creq",
  "reason": "COMPLIANCE_IMMEDIATE_INTERNAL",
  "entity_id": "275cf8f7559fd88710b4c919f85777aaenty",
  "state": "PROCESSING",
  "valid_until": "2019-04-01T22:31:06Z",
  "legal_closure_scheduled_at": "2019-03-01T22:31:06Z",
  "created_at": "2019-03-01T22:31:06Z",
  "updated_at": "2019-03-01T22:31:06Z"
}

Click here to view the full API reference.

GET List all ClosureRequests for an Entity

This endpoint returns an array containing all ClosureRequests for the Entity specified in the request URL.

Request URL:

GET /entities/{entity_id}/closure_requests

Response example:

{
  "items": [
    {
      "id": "ae93e4dcb3d0f5d0e36a227a94ff39e5creq",
      "reason": "ORDINARY_INTERNAL",
      "entity_id": "275cf8f7559fd88710b4c919f85777aaenty",
      "state": "APPROVED",
      "valid_until": "2019-07-01T22:31:06Z",
      "legal_closure_scheduled_at": "2019-05-01T22:31:06Z",
      "created_at": "2019-03-01T22:31:06Z",
      "updated_at": "2019-03-01T22:31:06Z"
    }
  ],
  "pagination": {
    "next": 0,
    "prev": 0
  }
}

Click here to view the full API reference.

GET Retrieve a ClosureRequest

This endpoint returns information about the ClosureRequest specified in the request URL.

Request URL:

GET /entities/{entity_id}/closure_requests/{closure_request_id}

Response example:

{
  "id": "ae93e4dcb3d0f5d0e36a227a94ff39e5creq",
  "reason": "CUSTOMER_WISH",
  "entity_id": "275cf8f7559fd88710b4c919f85777aaenty",
  "state": "PROCESSING",
  "valid_until": "2019-04-01T22:31:06Z",
  "legal_closure_scheduled_at": "2019-03-01T22:31:06Z",
  "created_at": "2019-03-01T22:31:06Z",
  "updated_at": "2019-03-01T22:31:06Z"
}

Click here to view the full API reference.

Step 5: Create Address

An Address represents a blockchain-level digital asset address.

Customers can create and associate many Addresses with an Account, and they can use these Addresses to transfer funds to their Accounts. Once created, an Address will permanently remain valid and associated with the Account. Solaris uses the Address resource to track the ownership of funds deposited to blockchain-level addresses.

Call the POST Create an Address endpoint to create an Address for your customer:

Request URL:

POST /v1/entities/{entity_id}/accounts/{account_id}/addresses

Response example:

// 201 Created

{
  "id": "42049cb01a6962d0232223e632aac68baddr",
  "account_id": "9c41ec8a82fb99b57cb5078ae0a8b569acct",
  "address": "1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX",
  "created_at": "2019-02-02T13:43:34Z",
  "updated_at": "2019-02-02T13:43:34Z"
}

Click here to view the full API reference.

See also:

• GET List all Addresses for an Account
• GET Retrieve an Address

Step 6: Implement Transactions

Finally, your customer is ready to begin making Transactions on the SDA platform. All Transactions belong to one of three general categories: deposits, transfers, and withdrawals.

Below is a list of possible type values:

Transaction processing workflow

The SDA platform keeps track of a Transaction's progress using the state property. The possible values for the state property are:

• PENDING
• APPROVED
• COMPLETED
• FAILED
• CANCELLED

All Transactions have an initial state value of PENDING when created.

Implement ApprovalRequests

After creation, each Transaction must be approved by the Transaction initiator. For Transfers and Withdrawals, you must collect approval from the corresponding Account holder using an ApprovalRequest. The form that the ApprovalRequest takes will depend on the type of the transaction initiator's registered ApprovalMethod.

Once the initiator approves the ApprovalRequest, the Transaction will transition to the APPROVED state.

Once a Transaction reaches the APPROVED state, the platform will queue it for processing.

When Solaris successfully processes the Transaction and updates the Account balance accordingly, then the Transaction will transition to the COMPLETED state. This state is final.

If an error occurs that prevents the successful processing of the Transaction, then it will transition to the FAILED state. Any locked funds will be released, and the Account's available balance will be updated. This state is final.

Transactions can be canceled up until they reach the APPROVED state. If you or the customer cancel a Transaction, then it will transition to the CANCELLED state and any locked funds will be released. This state is final.

Transaction validation checks

Whenever a Transaction is requested by the partner, the platform runs validation checks on the request. These validation checks depend on a number of properties defined on the Asset resource:

If any of these checks fail, the API will return a 400 - Invalid Request error.

{
  "message": "Invalid request",
  "params": {
    "address": "invalid"
  }
}

If other validation checks fail, then the API will create a Transaction and immediately set the state to FAILED. This can happen, for example, when the corresponding Account does not have enough funds for the requested Transaction.

Transfer & Withdrawal API endpoints

Call the following endpoints to create Transfers and Withdrawals:

• POST Create a Transfer
• POST Create a Withdrawal

Next steps

Congratulations! You have implemented the Solaris Digital Assets onboarding process.

If you wish to offer your customers the ability to trade crypto assets using your solution, then see the Brokerage guide.