https://api.superearn.io)를 활용하여 일별 장부를 마감하고, 회계감사 증빙을 산출하며, 수익률을 검증할 수 있도록 실제 운영 데이터를 기반으로 작성된 실무 레시피입니다.
본 워크스루의 모든 쿼리는 Kaia SuperVault(EarnUSDT) 및 고정이율 BoringVault(EarnJPYC, 배포 블록 230960963) 계정의 실제 프로덕션 데이터를 사용합니다.
시나리오 1: 일별 원장 대사 및 결산 (Daily Ledger Reconciliation)
목적
파트너사의 내부 회계 원장 잔고와 온체인 자금 흐름(입출금) 및 당일 발생 이자를 기간 경계(00:00:00 UTC) 기준으로 대사합니다. 순수 입금 상황과 출금(실현이익 발생) 상황을 모두 검증합니다.사례 1-A: 신규 입금 및 미실현 이자 발생 (출금 없음)
유저의 추가 입금만 있고 출금이 발생하지 않은 경우, 발생한 모든 이자는 미실현 손익 증가로 반영되며 실현손익은 0으로 유지됩니다.1단계: 24시간 구간 /v1/earnings 호출
실제 API 응답 데이터
2단계: 원장 항등식 검증
outflows = 0이므로 realizedPnl = 0이며, unrealizedPnlChange = pnl = $1,522.04가 성립합니다.
사례 1-B: 출금 집행 및 실현손익(Realized PnL) 인식 (유출액 발생)
볼트 지분을 출금(redeem)하거나 전송(transfer)하여 처분하는 경우, 처분된 지분에 귀속되는 원가는 장부에서 제거되고 처분 대금과 취득 원가의 차액이 **실현손익(realizedPnl)**으로 확정됩니다.
1단계: 출금이 포함된 기간 /v1/earnings 호출
실제 API 응답 데이터
2단계: 손익 분해 및 원장 항등식 이중 검증
불변식 A: 총손익 분해 항등식
불변식 B: 마스터 원장 잔고 항등식
불변식 C: 이동평균 원가 제거 검증
$166,430.95의 출금이 발생했을 때, 해당 처분 지분에 매칭되어 제거된 원가는 다음과 같습니다:
3단계: 출금 발생 시 회계 분개
- 고객 출금 및 실현이익 전기:
- (차변)
고객 예치 부채/출금 지급액:$166,430.95 - (대변)
수탁 볼트 지분자산 (취득 원가):$164,036.98 - (대변)
실현 투자수익 (Realized PnL):$2,393.98
- (차변)
- 잔여 보유 지분의 평가이익:
- 잔여 지분의 누적 미실현 이익은
$145,083.63에서$146,418.77로+$1,335.14증가.
- 잔여 지분의 누적 미실현 이익은
시나리오 2: 감사인 제출용 볼트 잠금이익 대사 (EarnUSDT 전용)
목적
변동금리SuperVault(EarnUSDT)에서 외부 회계감사인에게 공식 장부상 환금 가능 잔고(totalValue / positionValue)와 스마트 컨트랙트 상 총자산(reportedPositionValue) 사이의 차이를 입증하고 대사 증빙을 제출합니다. 고정이율 EarnJPYC에는 7일 lockedProfit 버퍼가 없으므로(include=reconciliation 호출 시 reconciliation.quality.status: "unavailable", 사유 accounting_rpc_unavailable), 아래 시나리오 4를 참고하세요.
1단계: include=reconciliation을 포함하여 /v1/balances 호출
실제 API 응답 데이터 (블록 #226797199)
2단계: 자산 대사 항등식 검증
3단계: 다자간 지분율 안분 검증 (Pro-Rata Verification)
감사인에게 잠금이익 배분이 전체 볼트 참여자 사이에서 공정하고 정확하게 안분되었음을 증명하려면, 동일 블록에서account를 생략하여 볼트 전체를 조회합니다:
시나리오 3: 공시 수익률 대사 및 성과 점검 (Yield & APY Verification)
목적
대고객 대시보드에 표기되는 볼트 관측 APY와 실제 계정 포지션의 실현 수익률을 상호 비교하여 수익률 관련 문의를 해소합니다.1단계: 최근 7일 관측 APY 조회 (/v1/apy)
- 볼트 7일 관측 APY: 5.64%
- 시나리오 1과의 일관성: 사례 1-A에서 1일 시간가중수익률(
return.apy)은 5.78%, 사례 1-B에서 3일 시간가중수익률은 **4.53%**로, 볼트가 유지 중인 변동 연이율 궤적과 일치합니다.
2단계: 목적별 수익률 엔드포인트 구분
시나리오 4: 고정이율 볼트 (EarnJPYC, 18 Decimals) 일일 마감 및 대사
목적
고정이율BoringVault(EarnJPYC, 18 decimals)의 KST(Asia/Seoul) 일일 마감 손익(valuation=pps)을 검증하고, AtomicQueue 정산 후 출금 슬롯(assets vs claim.assets)을 대사합니다.
1단계: KST 일일 마감 /v1/earnings 호출 (2026-11-16 KST)
실제 API 응답 요약 (2026-11-16 KST)
2단계: 18-Decimal 회계 항등식 및 AtomicQueue 출금 정산 대사
- 원장 항등식 검증 (Python
Decimal완전 정밀도):opening.totalValue(1571386.344881141536243) +pnl(83.067262772204247) =1571469.412143913740490=closing.totalValue(0오차).- 고정이율 볼트는 7일
lockedProfit버퍼가 없으므로valuation=pps(기본값)로quality.status: "complete"가 보장됩니다.
AtomicQueue출금 정산 확인 (GET /v1/accounts/{account}/redemptions):- 요청 대기 중에는
redemptionReceivable가"0"이며 지분은 계속positionValue에서 이자가 누적됩니다. - 솔버의
redeemSolve체결 후status: "claimed"행에서는 온체인 대기 슬롯이 비워지므로assets.value가"0"으로 표시되며, 실제 수령한JPYC금액(예:"480000")은claim.assets.value에서 대사해야 합니다.
- 요청 대기 중에는
일일 자동 결산용 배치 스크립트 예시
매일 자정에 실행하여 내부 원장과 SuperEarn 온체인 잔고의 일치 여부를 자동 검증하는 쉘 스크립트입니다 (EarnUSDT 및 EarnJPYC 공용, 임의 정밀도 Decimal == 0 비교):