Skip to main content
Scalar API 레퍼런스 · 잔고, 원가 및 수익 회계 · 발생주의 평가, Harvest 및 보고 · 데이터 API 연동 패턴 본 가이드는 기관 파트너 및 재무·회계팀이 SuperEarn Data API(https://api.superearn.io)를 활용하여 일별 장부를 마감하고, 회계감사 증빙을 산출하며, 수익률을 검증할 수 있도록 실제 운영 데이터를 기반으로 작성된 실무 레시피입니다. 본 워크스루의 모든 쿼리는 Kaia Super Vault 및 기관 파트너 라우터 계정의 실제 프로덕션 데이터를 사용합니다.

시나리오 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단계: 출금 발생 시 회계 분개

  1. 고객 출금 및 실현이익 전기:
    • (차변) 고객 예치 부채 / 출금 지급액: $166,430.95
    • (대변) 수탁 볼트 지분자산 (취득 원가): $164,036.98
    • (대변) 실현 투자수익 (Realized PnL): $2,393.98
  2. 잔여 보유 지분의 평가이익:
    • 잔여 지분의 누적 미실현 이익은 $145,083.63에서 $146,418.77+$1,335.14 증가.

시나리오 2: 감사인 제출용 볼트 잠금이익 대사 (Audit Reconciliation)

목적

외부 회계감사인에게 공식 장부상 환금 가능 잔고(totalValue / positionValue)와 스마트 컨트랙트 상 총자산(reportedPositionValue) 사이의 차이를 입증하고 대사 증빙을 제출합니다.

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단계: 목적별 수익률 엔드포인트 구분


일일 자동 결산용 배치 스크립트 예시

매일 자정에 실행하여 내부 원장과 SuperEarn 온체인 잔고의 일치 여부를 자동 검증하는 쉘 스크립트입니다: