Working with Reports

Getting visibility to Earn Api accounting system

As part of daily accounting cycle Earn Api publishes reports. Partner needs to access reports to sync Interest transactions and to implement automated daily settlements.

Access reports with following steps:

1. Get list of reports available by calling GET /v1/reports?type=Report

2. If there are new reports available, call GET /v1/reports/{reportId}/download-uri

3. Download report from url got on step 2

FullTransactionJournal and IncrementalTransactionJournal report types are deprecated and will be removed in future releases. You should always request list of reports using GET /v1/reports?type=Report.

Daily settlements

As part of integration process Tesseract and Partner exchanges wallet addresses for each currency. Partner is expected to transfer outstanding balance every day to wallet addresses received from Tesseract as part of Process. In similar way Tesseract will every day settle to wallet addresses received from Partner.

Visibility on direction and amount of the outstanding balance and expected crypto transfer is available in the daily report for each currency in balances[].outstandingBalance entry. The direction depends on the sign: negative value means Partner is expected to settle towards Tesseract.

In the example report below Tesseract owes 32.532298176173658034 BTC for Partner and Partner owes 48.399149760390872272 SOL for Tesseract. Corresponding settlements are expected to happen within the next day.

A report example published as a result of the accounting cycle somewhere very early morning of 2025-03-19. The report contains full visibility to Earn Api accounting system during day of 2025-03-18. Report contains 596229 rows out of which majority is suppressed for clarity.

Transaction sync

Important function of the Accounting cycle is to distribute interest for all user accounts. Distributed interest entries are available in report under transactions[] array with type === "Interest". Partner is expected to synch these entries from the report for purposes of displaying the entries for end user and to be able to calculate balance for each account.

Below one example Interest entry from the same report.

{
    "id": "d5266ad5-b724-4fce-9de0-27505317881d",
    "type": "Interest",
    "currency": "XRP",
    "amount": "0.000000173182690071",
    "createdAt": "2025-03-19T00:01:55.703Z",
    "accountingDate": "2025-03-19T00:00:00.000Z",
    "meta": {
        "productId": "d09f17ff-d527-42e6-8876-83af2fe56df6",
        "productName": "XRP Lending",
        "accountType": "user",
        "accountId": "3a7a9fa9-e6ca-4bf6-b563-ed58cb5d9cbf",
        "groupId": "0ab365dd-4fea-4c53-a2fb-65287ae97725",
        "userId": "c5640ae3-1b4b-41b0-b63a-6ea58da3fdd7"
    }
}

Example reports

Reports are available in all Environments. Best way to get examples is to do some deposits in Development or Test environments and download real reports from Earn Api.

Report schema

30KB

report-json-schema.json

The JSON data consists of the following fields:

1. id: UUID of the report.

2. partnerId: UUID of the partner.

3. type: Specifies the type of the report, which is "Report".

4. dateFrom: Start date of the accounting cycle in UTC+0 ISO date format.

5. dateTo: End date of the accounting cycle in UTC+0 ISO date format.

6. balances: List of balance objects per currency. Each object contains the following fields:

   • currency: Tesseract currency symbol format.

   • outstandingBalance: Balance to be settled after minimal settlement amount has been taken into account.

   • outstandingTotal: The complete outstanding balance.

   • accruedReceivables: Accrued receivables (partner perspective) or accounts-payables (Tesseract perspective).

   • accruedPayables: Accrued payables (partner perspective) or accounts-receivables (Tesseract perspective).

   • accountsReceivables: Accounts receivables (partner perspective) or accounts-payables (Tesseract perspective).

   • accountsPayables: Accounts payables (partner perspective) or accounts-receivables (Tesseract perspective).

7. settlements: List of settlement objects per currency. Each object represents a settlement and contains the following fields:

   • id: UUID of the settlement.

   • createdAt: UTC+0 ISO date of settlement creation.

   • currency: Tesseract currency symbol.

   • transactionIds: Array of UUIDs representing transaction identifiers associated with the settlement.

8. products: Snapshot list of product objects. Each object represents a product and contains the following fields:

   • id: UUID of the product.

   • group: The type of the product (Interest, Staking, or DEFI).

   • name: The name of the product.

   • currency: Tesseract currency symbol.

   • calculationMethod: The method used to calculate interest (Fixed, Variable, etc.).

   • fixedInterestRate: String representation of the fixed interest rate (e.g., "0.01" for 1% APR or APY).

   • rateType: APR or APY.

   • withdrawalPeriodDays: Number of days for the withdrawal period.

   • tiers: Array of objects representing different tiers for the product. Each object contains the following fields:

     • id: UUID for the tier.

     • lowerBound: Lower bound value for the tier.

     • userInterestRate: Interest rate for the tier.

9. aum: List of AUM balance objects. Each object represents the assets under management for a specific product and contains the following fields:

   • productId: UUID of the product.

   • productName: The name of the product.

   • productGroup: The group to which the product belongs.

   • currency: Tesseract currency symbol.

   • deposits: Total deposits for the AUM.

   • withdrawals: Total withdrawals for the AUM.

   • interest: Total interest earned for the AUM.

   • negativeInterest: Total negative interest for the AUM.

   • depositCorrections: Corrections made to deposits.

   • withdrawalCorrections: Corrections made to withdrawals.

   • interestCorrections: Corrections made to interest.

   • negativeInterestCorrections: Corrections made to negative interest.

   • amount: Total AUM for the product.

10. transactions: List of transaction objects. Each object represents a transaction and contains the following fields:

    • id: UUID of the transaction.

    • type: Type of the transaction (Deposit, Withdrawal, Interest, Margin, Fee, etc.).

    • currency: Tesseract currency symbol.

    • amount: Number as a string representing the transaction amount with 18 decimal precision.

    • createdAt: UTC+0 ISO date of the transaction creation.

    • accountingDate: UTC+0 ISO date of the transaction for accounting purposes.

    • meta: Object containing metadata associated with the transaction. The properties within the meta object vary based on the transaction type.

Transaction types

The following are the available transaction types in the Report;

• User accounts

  • Deposit - Deposit to an account.

  • Withdrawal - Withdrawal from an account.

  • Interest - Interest distributed to an account.

  • NegativeInterest - Negative interest distributed to an account.

  • Margin - Margin distributed to an account.

  • Fee - Fees distributed to the account.

• Partner account

  • SettlementIn - requested settlement booked to outstanding balances.

  • SettlementOut - requested settlement booked to outstanding balances.

  • TransferIn - when money has been recorded to be received in the outstanding balances account.

  • TransferOut - when money has been recorded to be received in the outstanding balances account.

• Corrections

  • DepositCorrection

  • InterestCorrection

  • WithdrawCorrection

  • NegativeInterestCorrection

  • MarginCorrection

  • FeeCorrection

  • TransferInCorrection

  • TransferOutCorrection