Working with Reports

As part of the daily accounting cycle, Earn API publishes reports. Partners need to access reports to sync interest transactions and to implement automated daily settlements.

Access reports with the following steps:

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

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

3. Download the report from the URL returned in step 2.

⚠️ Deprecation notice. FullTransactionJournal and IncrementalTransactionJournal report types are deprecated and will be removed in future releases. Always request the report list using GET /v1/reports?type=Report.

Daily settlements

As part of the integration process, Tesseract and the partner exchange wallet addresses for each currency. The partner is expected to transfer the outstanding balance every day to the wallet addresses received from Tesseract. Tesseract likewise settles daily to the wallet addresses received from the partner.

Visibility into the direction and amount of the outstanding balance and the expected crypto transfer is available in the daily report per currency under balances[].outstandingBalance. The direction depends on the sign: a negative value means the partner is to settle towards Tesseract.

For example, if Tesseract owes 32.532298176173658034 BTC to the partner and the partner owes 48.399149760390872272 SOL to Tesseract, the corresponding settlements are expected to happen within the next day.

Transaction sync

An important function of the accounting cycle is to distribute interest to all user accounts. Distributed interest entries are available in the report under the transactions[] array with type === "Interest". Partners are expected to sync these entries for displaying to end users and for calculating per-account balances.

Example interest entry:

{
  "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. The easiest way to get examples is to do some deposits in Development or Test and download real reports from Earn API.

Report schema

The JSON report contains the following fields:

1. id — UUID of the report.

2. partnerId — UUID of the partner.

3. type — the type of the report ("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:

   • currency — Tesseract currency symbol.

   • outstandingBalance — balance to be settled after the minimum settlement amount has been taken into account.

   • outstandingTotal — the complete outstanding balance.

   • accruedReceivables — accrued receivables (partner perspective).

   • accruedPayables — accrued payables (partner perspective).

   • accountsReceivables — accounts receivables (partner perspective).

   • accountsPayables — accounts payables (partner perspective).

7. settlements — list of settlement objects per currency:

   • id — UUID of the settlement.

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

   • currency — Tesseract currency symbol.

   • transactionIds — UUIDs of transactions associated with the settlement.

8. products — snapshot list of product objects:

   • id, group, name, currency.

   • calculationMethod — e.g. Fixed, Variable.

   • fixedInterestRate — string representation (e.g. "0.01" = 1% APR or APY).

   • rateType — APR or APY.

   • withdrawalPeriodDays.

   • tiers — array of { id, lowerBound, userInterestRate }.

9. aum — AUM balance objects per product (deposits, withdrawals, interest, corrections, total amount).

10. transactions — list of transaction objects:

    • id, type, currency, amount (18-decimal string).

    • createdAt, accountingDate — UTC+0 ISO dates.

    • meta — metadata object whose properties vary by transaction type.

Transaction types

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 / SettlementOut — requested settlement booked to outstanding balances.

• TransferIn / TransferOut — money recorded as received in the outstanding balances account.

Corrections:

• DepositCorrection, InterestCorrection, WithdrawCorrection, NegativeInterestCorrection, MarginCorrection, FeeCorrection, TransferInCorrection, TransferOutCorrection.