Earn Direct API integration
Last updated
Last updated
Our goal is to ensure tech teams have as much guidance and context as needed to successfully build their front-end solution towards our API. This guidebook is aimed at helping partners quickly ingest all needed requirements and guidelines.
The integration project has 6 stages (as depicted in the diagram from 0-5, and 5 gates that enable have exit-criteria for the stage. Below we outline each stage and the exit criteria.
There are a few technical elements that partner must be aware before starting a project.
Requirement
Description
Partner has Web3 SDK or similar capability
UI must be able to sign transactions with user private keys and broadcast them to blockchain.
Users sign-up and authenticate on Tesseract OAuth2 server to use the service
Current standard authentication solution is that Tesseract provides OAuth2 server where users sign-up and authenticate. If users already have identity on e.g. Partner’s identity management then by default there is no SSO.
Tesseract is willing to discuss alternative options.
Sumsub used for KYC
Earn Direct currently uses Sumsub for KYC process.
Tesseract is willing to discuss alternative options.
Partner is responsible for UI deployment
Partner should have capability to deploy to cloud in case of Web UI and to Google/Apple stores in case of Mobile.
Exit criteria for stage 0: Partner has reviewed the requirements and accepts them
Developing your own front-end for Earn Direct is something we support, and we understand the need to maintain a consistent and unified user experience for your end customers. However to make the experience both easy to understand and compliant with regulation there are some mandatory requirements the development team should be aware of.
Earn Direct consists of four main use-cases, and below we have depicted the mandatory requirements of each stage:
View available products: The first natural step for any user is to understand what is on offer:
The user can view the product list (product name, currency and APY).
They are able to learn more from the product specific info view. The summary is available directly within the web app, and more specific details are linked separately as a product-specific PDF. The details of the PDF must be available for the user so that we can meet the minimum requirements of data for providing them.
Deposit to a product: Once a user has found a product they want to invest in, they can initiate the deposit flow:
First they need to link a wallet, so that we can read the available balance.
Then they submit how much from the available balance they want to invest. They must accept our terms and conditions (note: these are different for Lending and DeFi products, and we maintain a record of which T&Cs have been accepted so as to be able to require them again upon a change) and our privacy policy. These documents must be available and they must be accepted before a user can progress.
Note: The user cannot deposit the full amount in their wallet as then they do not have funds for gas fee. There are a few different approaches to solve this issue with varying levels of complexity/work required.
At this point if the user is not authenticated we force authentication (via email and with Auth0), and if the user has not done KYC we initiate the KYC flow (within the same session and with Sumsub).
After successful KYC the user is returned to the page to finalise the deposit. Once the deposit is done, we show a success page with a direct link to the My Portfolio section.
View outstanding investments: Once a user has made an investment, they can track the progress in My Portfolio. They can see their total amount invested and total rewards accrued as estimated values based on crypto currency prices of the moment (this information is fetched every second minute).
In My Transactions the use can see the state of any transaction, either deposit or withdraw (A new deposit is “In Progress” until we read programatically that the money has moved to our custody, after which the state is “Done”).
In My Rewards the user can see their accrued interest per product per day (we pay interest daily each night).
In My products the user can see how much they have invested to each product and from which wallet and with what terms (APY).
Withdraw your funds: Once a user wants to withdraw they need to select the specific product from My Products view and initiate the withdraw flow:
First they need to define how much of the investment they want to withdraw, either partially or fully.
Note: Withdraws are ALWAYS done to the source wallet they originate from. This is a compliance requirement that must be met.
Note 2: It is good practise to have an additional confirmation step to verify the amount.
After withdraw request we show a success page, and the user can track the progress in My Transactions view.
Note: We maintain in our Terms and Conditions a maximum of 7 days to return assets.
In addition to the above there are other use-cases to ensure a good user experience. These are soft-requirements that can be managed in a variety of ways depending on the other aspects of the partner product flow.
Logout/Login: There should be a way for the user to logout of the EARN section of the product flow. This is so that they can ensure no one else who uses their device has access, or if they want to access an alternative profile. The placement of this feature should be evaluated in a way that it makes sense for the partner flow.
Customer tracking (eg. cookies): If the service is being offered as a web app, we would highly encourage the utilisation of cookies so as to enable tracking of the user journey. We suggest utilising Google Analytics and HotJar or similar to gain valuable customer insights.
Exit criteria for stage 1: Partner provides a UX/UI plan (eg. Figma / Sketch) to show what the front-end solution will look like.
Development will happen against our “partner environment”. In this environment developers are able to test deposits to Tesseract products using real crypto. Rewards are also distributed daily just like in production.
Prerequisite for entering to Development & Testing phase is that UX design has been agreed with Tesseract. Tesseract will configure authentication etc. on the platform and deliver following information that you will need during development.
Information
Description
Earn Direct Api base url
Partner environment:
OAuth2 clientId
UI needs this to implement authentication
OAuth2 domain
UI needs this to implement authentication
OAuth2 issuer
UI needs this to implement authentication
OAuth2 audience
UI needs this to implement authentication
Tesseract partner name
UI needs this to call Api endpoints which don’t require authentication
UX requirement is to display product list for non-authenticated users so that they can choose product to invest to. To get the list to display UI should call GET /v1/products endpoint with X-tesseract-partner HTTP header set to partner name given by Tesseract.
Endpoints other than GET /v1/products and GET /v1/exchange-rates require Authorization header to be set with user access token. Curl example below.
In the core of the deposit process UI calls POST /v1/deposit-wallets endpoint to establish a user and product specific wallet address where all deposit transactions for that user and product should be signed to. Successful call will return deposit wallet address and after that it is totally up to UI to sign transaction to the wallet address using partner’s web3 capabilities. On Tesseract side we monitor deposit wallets for incoming transactions and know based on the wallet metadata to book the deposit transaction into our accounting system for correct user and product.
In this context it is also important to note that we allow users to withdraw assets only to same accounts where we received deposit transaction from.
Below the expected sequence on high level. Subsections after that describe prerequisites for a successful POST /v1/deposit-wallets call and how to work them out.
2.3.1 How to get productId
You get productId easily by displaying product list for user and letting user choose product to deposit to.
2.3.2 How to know if user has already accepted product terms
Response of GET /v1/products contains termCategory of each product. Calling the endpoint does not require authentication and authorization and therefore we don’t include user specific info such as terms consent info into response. Instead UI needs to call GET /v1/user-info endpoint to know if user has already accepted terms for the termCategory.
It is under UI responsibility to display a link to product terms, make sure user has clicked the link and given consent. The information if user has already accepted terms can be used e.g. to force consent only if not previously given. Prerequisite for successful POST /v1/deposit-wallets call is the termsAccepted is set to true even if consent was previously given.
2.3.3 How to do KYC
Call to POST /v1/deposit-wallets will respond with HTTP status 451 if user has not completed KYC. UI must then take user through KYC process. From UI perspective there are 3 steps:
Generate Sumsub access token by calling GET /v1/kyc/sumsub/token
Poll GET /v1/kyc/verified until response is true and call POST /v1/deposit-wallets again with the same parameters as previously. Logic for the step is that behind the scenes Sumsub delivers users' KYC results to Tesseract using webhook. Return value of GET /v1/kyc/verified reflects results received.
GET /v1/kyc/verified deprecation warning
We will be adding capabilities to push events from Earn Direct Api to clients. Once these capabilities are added partners GET /v1/kyc/verified endpoint will be deprecated.
Please refer to Api documentation under category “User position”.
To make withdrawal UI needs to let user choose account using response from PUT /v1/user/accounts. Once user has chosen account with balance on it and given the amount to withdraw UI can call POST /v1/withdrawal-requests.
Tesseract organizes customer support via email. In order for users to identify themselves to customer support they need to tell their id. For displaying user id for users UI can call GET /v1/user-info endpoint.
Tesseract provides transaction level reporting to Partner allowing partner to monitor users' assets under Tesseract management as well as partner share. Specification for partner reporting will be added to API Documentation once it is stabilized.
Exit criteria for stage 2: Partner provides a short 30 min demo of how the service works in their staging environment.
Prerequisite for moving to Production deployment phase is that partner organizes demo of the UI for Tesseract product and technical people. Tesseract wants to check that UX and technical implementation is aligned with our standards.
After the demo Tesseract will setup partner to access production environment and deliver the same information as listed in the beginning of chapter 2. Development & testing.
Partner is expected complete development and production deployment on their side and deliver access instruction to Tesseract.
Exit criteria for stage 3: Partner provides production access instructions for acceptance testing.
Partner should give Tesseract an access to their production build of the UI. Tesseract will once more check UX and technical implementation is according to Tesseract standards. After acceptance test is passed partner can open access to the retail customers.
Exit criteria for stage 4: Tesseract has done test transactions are reviewed compliance requirements are met and closes acceptance testing (on average 1-2 business days)
After go-live the partner and Tesseract shall maintain active discussion on how to develop the service. When we update the API, we will inform the partners development team with due time to develop and test the new release in staging effectively.
Contact customer support: If the user is unclear on the state of any action or some information is not understandable, they will look for guidance. It is up for discussion how this is setup for a partner, but we maintain a generic mailbox that routes all in-bound requests to an our centralised customer support workflow. This email address is configured for each partner separately so as to ensure easy to track origins.
Following subsections describe engineering of each high level use case. Our goal is to give developers context around the API documentation available at .
To authenticate users assumption is that UI implements OAuth2 flow to acquire access token. Tesseract OAuth2 server is provided by Auth0 in the domain given to you in beginning of Development & Testing phase. Recommendation is to use client libraries provided Auth0.
Initialize Sumsub or and pass on Sumsub access token to it. Their SDK will take user through the KYC process.
