Partner Reconciliation Walkthrough

Scalar API reference · Balances, cost and returns · Valuation and harvest reporting · Data API patterns This guide provides end-to-end operational recipes for institutional partners and finance teams to reconcile daily statements, prove audit numbers, and verify yield using the SuperEarn Data API (https://api.superearn.io). All queries in this walkthrough use real production data from the Kaia Super Vault and an institutional partner router account.

Parameter	Walkthrough Value	Description
API Base URL	`https://api.superearn.io`	Production Data API serving endpoint
Partner Account	`0xa1963b0ad126aca96547b598e50fe2714993af70`	Institutional Partner Deposit Router on Kaia
Vault ID	`eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6`	SuperVault (EarnUSDT) on Kaia
Native Asset	`USD₮` (`0xd077a400968890eacc75cdc901f0356c943e4fdb`)	Token decimals = 6

Scenario 1: Daily Ledger Reconciliation

Objective

Reconcile your internal accounting ledger against on-chain fund flows and net earned interest at period boundaries, under both deposit-only and redemption (realized gain) conditions.

Case 1-A: Inflows and Accrued Interest (No Redemptions)

When users only deposit and no shares are liquidated, all earned interest increases unrealized PnL, and realized PnL remains zero.

1. Query `/v1/earnings` for the 24-hour cycle

curl -s "https://api.superearn.io/v1/earnings?account=0xa1963b0ad126aca96547b598e50fe2714993af70&start=2026-09-01T00:00:00Z&end=2026-09-02T00:00:00Z" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'

Actual API Response

{
  "asset": {
    "chainId": 8217,
    "address": "0xd077a400968890eacc75cdc901f0356c943e4fdb",
    "symbol": "USD₮",
    "decimals": 6
  },
  "shareToken": {
    "chainId": 8217,
    "address": "0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6",
    "symbol": "EarnUSDT",
    "decimals": 6
  },
  "opening": {
    "totalValue": "9707876.752939",
    "shares": "9452378.123456",
    "positionValue": "9707876.752939",
    "redemptionReceivable": "0",
    "costBasis": "9565668.515112",
    "unrealizedPnl": "142208.237827",
    "block": {
      "number": "226020599",
      "timestamp": "2026-08-31T23:59:59.000Z"
    }
  },
  "closing": {
    "totalValue": "10201166.745453",
    "shares": "9896431.654321",
    "positionValue": "10201166.745453",
    "redemptionReceivable": "0",
    "costBasis": "10057436.465738",
    "unrealizedPnl": "143730.279715",
    "block": {
      "number": "226106982",
      "timestamp": "2026-09-01T23:59:59.000Z"
    }
  },
  "inflows": "491767.950626",
  "outflows": "0",
  "pnl": "1522.041888",
  "realizedPnl": "0",
  "unrealizedPnlChange": "1522.041888",
  "netTransferredUnrealizedPnl": "0",
  "return": {
    "periodRate": "0.00015399637928157",
    "method": "time_weighted",
    "apr": "0.05620867843777335",
    "apy": "0.057813826875357062",
    "estimated": false
  },
  "quality": {
    "status": "complete",
    "reasons": []
  }
}

2. Validate Ledger Invariant

Closing Total Value = Opening Total Value + Inflows - Outflows + Net PnL

Plugging in the actual response values:

  Opening Total Value:    $9,707,876.752939
+ Gross Inflows:           +$491,767.950626  (User deposits during the day)
- Gross Outflows:                    -$0.00  (Zero redemptions executed)
+ Net PnL (Yield):            +$1,522.041888  (On-chain vault interest accrued)
-------------------------------------------------------------------------------
= Closing Total Value:   $10,201,166.745453  (Matches closing.totalValue)

Because outflows = 0, realizedPnl = 0 and unrealizedPnlChange = pnl = $1,522.04.

Case 1-B: Redemptions and Realized Capital Gains (With Outflows & Realized PnL)

When vault shares are redeemed or transferred out, the cost basis of those disposed shares is removed from the book, and the difference between redemption proceeds and acquisition cost crystallizes as Realized PnL (realizedPnl).

1. Query `/v1/earnings` for the active redemption period

curl -s "https://api.superearn.io/v1/earnings?account=0xa1963b0ad126aca96547b598e50fe2714993af70&start=2026-09-03T00:00:00Z&end=2026-09-06T00:00:00Z" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'

Actual API Response

{
  "asset": {
    "chainId": 8217,
    "address": "0xd077a400968890eacc75cdc901f0356c943e4fdb",
    "symbol": "USD₮",
    "decimals": 6
  },
  "shareToken": {
    "chainId": 8217,
    "address": "0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6",
    "symbol": "EarnUSDT",
    "decimals": 6
  },
  "opening": {
    "totalValue": "10215965.552927",
    "shares": "9904231.112233",
    "positionValue": "10215965.552927",
    "redemptionReceivable": "0",
    "costBasis": "10070881.919276",
    "unrealizedPnl": "145083.633651",
    "block": {
      "number": "226192502",
      "timestamp": "2026-09-02T23:59:59.000Z"
    }
  },
  "closing": {
    "totalValue": "10175436.158102",
    "shares": "9862145.445566",
    "positionValue": "10175436.158102",
    "redemptionReceivable": "0",
    "costBasis": "10029017.384182",
    "unrealizedPnl": "146418.77392",
    "block": {
      "number": "226451669",
      "timestamp": "2026-09-05T23:59:59.000Z"
    }
  },
  "inflows": "122172.44322",
  "outflows": "166430.954515",
  "pnl": "3729.11647",
  "realizedPnl": "2393.976201",
  "unrealizedPnlChange": "1335.140269",
  "netTransferredUnrealizedPnl": "0",
  "return": {
    "periodRate": "0.000364265450288304",
    "method": "time_weighted",
    "apr": "0.044318963118410337",
    "apy": "0.045307283245151404",
    "estimated": false
  },
  "quality": {
    "status": "complete",
    "reasons": []
  }
}

2. Validate Dual PnL and Ledger Invariants

Invariant A: Total PnL Decomposition

Total PnL = Realized PnL + Unrealized PnL Change

Plugging in the response values:

  Realized PnL (crystallized upon exit):     +$2,393.976201
+ Unrealized PnL Change (held shares):       +$1,335.140269
------------------------------------------------------------
= Total Period PnL:                          +$3,729.116470  (Matches period pnl)

Invariant B: Master Ledger Balance Equation

Closing Total Value = Opening Total Value + Inflows - Outflows + Total PnL

Plugging in the response values:

  Opening Total Value:    $10,215,965.552927
+ Gross Inflows:             +$122,172.443220  (Deposits received)
- Gross Outflows:            -$166,430.954515  (Proceeds paid out to redeeming users)
+ Total PnL:                   +$3,729.116470  (Net yield generated across all shares)
--------------------------------------------------------------------------------------
= Closing Total Value:    $10,175,436.158102  (Matches closing.totalValue)

Invariant C: Cost Basis Derecognition

When $166,430.95 was redeemed, the cost basis of those specific shares was derecognized:

Derecognized Cost Basis = Outflows - Realized PnL
                        = $166,430.954515 - $2,393.976201
                        = $164,036.978314

Closing Cost Basis = Opening Cost Basis + Inflows - Derecognized Cost Basis
                   = $10,070,881.919276 + $122,172.443220 - $164,036.978314
                   = $10,029,017.384182  (Matches closing costBasis)

3. Accounting Journal Entries for Redemptions

User Outflows & Capital Gain:
- (Debit) User Deposit Liabilities / Cash Paid: $166,430.95
- (Credit) Custody Vault Shares (Cost Basis): $164,036.98
- (Credit) Realized Investment Gain (PnL): $2,393.98
Remaining Retained Shares:
- Unrealized gain on retained shares increased by $1,335.14 ($145,083.63 -> $146,418.77).

Scenario 2: Audit Locked-Profit Reconciliation

Objective

Provide financial auditors with evidence reconciling the difference between the statutory claimable balance (totalValue / positionValue) and the smart contract total assets (reportedPositionValue).

Step 1: Query `/v1/balances` with `include=reconciliation`

curl -s "https://api.superearn.io/v1/balances?account=0xa1963b0ad126aca96547b598e50fe2714993af70&at=2026-09-10T00:00:00Z&include=reconciliation" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'

Actual API Response (Block `#226797199`)

{
  "asset": {
    "chainId": 8217,
    "address": "0xd077a400968890eacc75cdc901f0356c943e4fdb",
    "symbol": "USD₮",
    "decimals": 6
  },
  "shareToken": {
    "chainId": 8217,
    "address": "0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6",
    "symbol": "EarnUSDT",
    "decimals": 6
  },
  "totalValue": "9519763.267825",
  "shares": "9218451.987654",
  "positionValue": "9519763.267825",
  "redemptionReceivable": "0",
  "costBasis": "9383181.890268",
  "unrealizedPnl": "136581.377557",
  "reconciliation": {
    "reportedPositionValue": "9528415.90959",
    "adjustments": [
      {
        "type": "lockedProfit",
        "amount": "8652.641765"
      },
      {
        "type": "rounding",
        "amount": "0"
      }
    ],
    "quality": {
      "status": "complete",
      "reasons": []
    }
  },
  "quality": {
    "status": "complete",
    "reasons": []
  }
}

Step 2: Validate the Asset Reconciliation Invariant

Reported Position Value = Position Value + Locked Profit Adjustment + Rounding

Plugging in the response values:

  Claimable Position Value (PPS):    $9,519,763.267825
+ Unreleased Locked Profit Buffer:      +$8,652.641765
+ Integer Rounding Difference:                   $0.00
------------------------------------------------------
= Contract Reported Value:            $9,528,415.909590  (Matches reportedPositionValue)

Step 3: Multi-Party Pro-Rata Verification

To prove to auditors that the locked profit allocation is fair and pro-rata across all vault participants, query the entire vault at the exact same block by omitting account:

curl -s "https://api.superearn.io/v1/balances?vault=eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6&at=2026-09-10T00:00:00Z&include=reconciliation" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'

Metric	Whole SuperVault	Partner Share	Share Percentage
Claimable Balance (`positionValue`)	`$12,784,612.406668`	`$9,519,763.267825`	74.4627%
Contract Locked Profit (`lockedProfit`)	`$11,620.107365`	`$8,652.641765`	74.4627%
Gross Reported Assets (`reportedPositionValue`)	`$12,796,232.514033`	`$9,528,415.909590`	74.4627%

Partner Share = 9,519,763.267825 / 12,784,612.406668 = 74.46266%
Allocated Locked Profit = 11,620.107365 * 74.46266% = $8,652.641765 (Matches adjustments[0].amount)

Scenario 3: Trailing Yield & Performance Verification

Objective

Reconcile marketing/displayed vault APY against actual position returns to address partner inquiries regarding rate consistency.

Step 1: Query the 7-day trailing observed APY (`/v1/apy`)

curl -s "https://api.superearn.io/v1/apy?vault=eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6" | jq .data[0]

{
  "at": "2026-09-11T04:01:10.900886417Z",
  "start": "2026-09-04T04:01:33Z",
  "end": "2026-09-11T04:00:51Z",
  "apy": "0.056375660533308306",
  "quality": {
    "status": "complete",
    "reasons": []
  }
}

Observed Vault APY: 5.64% over the trailing 7 days.
Consistency with Ledger: In Case 1-A, the 1-day time-weighted return (return.apy) was 5.78%, and in Case 1-B the 3-day time-weighted return was 4.53%, consistent with the vault’s floating yield range.

Step 2: Rate Distinction Reference

Rate Type	Endpoint	Best Used For
Observed Vault APY	`GET /v1/apy?vault=…`	Displaying 7-day trailing APY on partner end-user dashboards
Account Period Return	`GET /v1/earnings` (`return.apr` / `apy`)	Measuring actual investment yield on held capital across deposits and withdrawals
Strategy Harvest Events	`GET /v1/harvests?account=…&start=…&end=…`	Confirming individual keeper harvest events and fee deductions
Pre-Harvest Venue Estimates	`GET /v1/earnings?valuation=estimated_nav`	Tracking economic interest before strategy harvest events report back to the root vault

Automation Script for Daily Cron Jobs

You can automate daily balance reconciliation using this lightweight shell script:

#!/usr/bin/env bash
set -euo pipefail

ACCOUNT="0xa1963b0ad126aca96547b598e50fe2714993af70"
VAULT="eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6"

# Define yesterday and today midnight UTC
END_DATE=$(date -u -v-0d "+%Y-%m-%dT00:00:00Z" 2>/dev/null || date -u -d "today" "+%Y-%m-%dT00:00:00Z")
START_DATE=$(date -u -v-1d "+%Y-%m-%dT00:00:00Z" 2>/dev/null || date -u -d "yesterday" "+%Y-%m-%dT00:00:00Z")

echo "Running reconciliation for $ACCOUNT ($START_DATE to $END_DATE)..."

RESP=$(curl -s "https://api.superearn.io/v1/earnings?account=${ACCOUNT}&vault=${VAULT}&start=${START_DATE}&end=${END_DATE}")

OPENING=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .opening.totalValue')
CLOSING=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .closing.totalValue')
INFLOWS=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .inflows')
OUTFLOWS=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .outflows')
PNL=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .pnl')

# Check Invariant: Closing == Opening + Inflows - Outflows + PnL
DIFF=$(python3 -c "from decimal import Decimal; print(Decimal('$CLOSING') - (Decimal('$OPENING') + Decimal('$INFLOWS') - Decimal('$OUTFLOWS') + Decimal('$PNL')))")

if [ "$DIFF" == "0" ] || [ "$DIFF" == "0.000000" ]; then
    echo "✅ [Reconciliation Verified] Invariant balanced."
    echo "   Opening: $OPENING | Inflows: $INFLOWS | Outflows: $OUTFLOWS | PnL: $PNL | Closing: $CLOSING"
else
    echo "❌ Discrepancy detected: $DIFF"
    exit 1
fi

Overview

Protocol

Risks

Security and Transparency

Developers

Resources

Partner Reconciliation Walkthrough

Scenario 1: Daily Ledger Reconciliation

Objective

Case 1-A: Inflows and Accrued Interest (No Redemptions)

1. Query `/v1/earnings` for the 24-hour cycle

Actual API Response

2. Validate Ledger Invariant

Case 1-B: Redemptions and Realized Capital Gains (With Outflows & Realized PnL)

1. Query `/v1/earnings` for the active redemption period

Actual API Response

2. Validate Dual PnL and Ledger Invariants

Invariant A: Total PnL Decomposition

Invariant B: Master Ledger Balance Equation

Invariant C: Cost Basis Derecognition

3. Accounting Journal Entries for Redemptions

Scenario 2: Audit Locked-Profit Reconciliation

Objective

Step 1: Query `/v1/balances` with `include=reconciliation`

Actual API Response (Block `#226797199`)

Step 2: Validate the Asset Reconciliation Invariant

Step 3: Multi-Party Pro-Rata Verification

Scenario 3: Trailing Yield & Performance Verification

Objective

Step 1: Query the 7-day trailing observed APY (`/v1/apy`)

Step 2: Rate Distinction Reference

Automation Script for Daily Cron Jobs

​Scenario 1: Daily Ledger Reconciliation

​Objective

​Case 1-A: Inflows and Accrued Interest (No Redemptions)

​1. Query /v1/earnings for the 24-hour cycle

​Actual API Response

​2. Validate Ledger Invariant

​Case 1-B: Redemptions and Realized Capital Gains (With Outflows & Realized PnL)

​1. Query /v1/earnings for the active redemption period

​Actual API Response

​2. Validate Dual PnL and Ledger Invariants

Invariant A: Total PnL Decomposition

Invariant B: Master Ledger Balance Equation

Invariant C: Cost Basis Derecognition

​3. Accounting Journal Entries for Redemptions

​Scenario 2: Audit Locked-Profit Reconciliation

​Objective

​Step 1: Query /v1/balances with include=reconciliation

​Actual API Response (Block #226797199)

​Step 2: Validate the Asset Reconciliation Invariant

​Step 3: Multi-Party Pro-Rata Verification

​Scenario 3: Trailing Yield & Performance Verification

​Objective

​Step 1: Query the 7-day trailing observed APY (/v1/apy)

​Step 2: Rate Distinction Reference

​Automation Script for Daily Cron Jobs

Scenario 1: Daily Ledger Reconciliation

Objective

Case 1-A: Inflows and Accrued Interest (No Redemptions)

1. Query `/v1/earnings` for the 24-hour cycle

Actual API Response

2. Validate Ledger Invariant

Case 1-B: Redemptions and Realized Capital Gains (With Outflows & Realized PnL)

1. Query `/v1/earnings` for the active redemption period

Actual API Response

2. Validate Dual PnL and Ledger Invariants

3. Accounting Journal Entries for Redemptions

Scenario 2: Audit Locked-Profit Reconciliation

Objective

Step 1: Query `/v1/balances` with `include=reconciliation`

Actual API Response (Block `#226797199`)

Step 2: Validate the Asset Reconciliation Invariant

Step 3: Multi-Party Pro-Rata Verification

Scenario 3: Trailing Yield & Performance Verification

Objective

Step 1: Query the 7-day trailing observed APY (`/v1/apy`)

Step 2: Rate Distinction Reference

Automation Script for Daily Cron Jobs