solution architecture.md
Solution Architecture
Earn API is engineered for straightforward integration across custodian systems. This overview outlines integration partner responsibilities without requiring knowledge of your specific architecture.
Integration tasks overview
The solution involves eight key tasks. Synchronous operations occur alongside user interface actions; asynchronous operations run as background jobs.
| # | Task | Description | Dependencies |
|---|---|---|---|
| 1 | Authentication | OAuth2 Client Credentials Flow (M2M) is used to acquire an access token for Earn API. | — |
| 2 | Product list | Partners retrieve product listings from internal storage, with options for automated sync or manual database maintenance. | 1 |
| 3 | Create Tesseract user and accounts | User and account creation before deposits, implementable synchronously at deposit time or beforehand. | 1, 2 |
| 4 | Deposit | Partner calls Earn API to book a user deposit into Tesseract's accounting with no immediate crypto transfer. | 1, 3 |
| 5 | Balance and transaction views | Balance and transaction details sourced from partner systems. | 4b, 6b, 8 |
| 6 | Withdrawal | Partner books a withdrawal on Earn API with no immediate crypto transfer. | 1, 4 |
| 7 | Daily settlement | Partners fetch daily reports containing settlement figures and initiate crypto transactions where deposits exceed withdrawals. | 1 |
| 8 | Daily interest sync | The daily report contains all journal entries for the day, requiring partner synchronisation. | 1 |
Accounting cycle
The accounting cycle executes daily at 00:00 (typically UTC) and handles user interest distribution, partner margin allocation, and report generation.
Daily settlement process
When Earn API is used to deposit and withdraw assets to accounts, no actual crypto transfers are sent or received. Instead, all deposits and withdrawals are netted per-currency once per day. Partners configure wallet addresses within Earn API for automated settlement, with complete visibility through daily reports.
Multi-entity compliance structure
Partners receive separate authentication credentials for each product line due to regulatory requirements. Partners must maintain credential-to-user mappings and create dual Earn API user accounts per end user while presenting a unified product experience. See Data Model Mapping for the mapping pattern.