잔고, 원가 및 수익 회계

​

TL;DR

• 총 평가 자산: totalValue = positionValue + redemptionReceivable (총 평가 자산 = 활성 운용 지분 가치 + 출금 대기금)
• 지분과 평가액의 구분: shares는 볼트 지분 토큰 단위(shareToken)이며, positionValue는 이를 기초 자산으로 환산 평가한 가치(shares × PPS, asset 단위)입니다.
• 출금 대기금 단위: redemptionReceivable은 지분 토큰이 아닌 **기초 자산 토큰 단위(asset)**입니다. 출금 신청 시 지분이 소각/락업되고 원금 확정액이 CooldownVault에 보관되므로, positionValue와 동일 단위로 직접 합산됩니다.
• 취득원가 (costBasis): 이동평균원가법(Pro-rata Moving Average Cost)을 적용하여 잔여 활성 지분의 역사적 취득원가를 추적합니다.
• 미실현손익 변화량 (unrealizedPnlChange): 기간 중 변동분(Flow)이며, opening.unrealizedPnl 및 closing.unrealizedPnl은 경계 시점의 잔액(Stock)입니다.
• 수익률 표기: return.periodRate와 return.apr을 기본 표준으로 사용하십시오. return.apy는 수익률이 정의되는 모든 기간에 산출되지만, 7일 미만 구간에서는 가상의 연환산 외삽값이므로 단기 구간에는 return.apr과 return.periodRate를 우선 사용하십시오.
• null 값 보존: quality.status와 quality.reasons를 확인하십시오. 과거 온체인 데이터 수집 미완료 시 관련 필드는 null로 반환됩니다. 이를 임의로 0으로 바꾸지 마십시오.

​

API 요청 및 응답 필드 규격

​

단위(Unit) 체계

​

GET /v1/balances (시점 잔고 스냅샷)

​

요청 파라미터 (Request)

​

응답 필드 (Response: data[].assets[])

​

GET /v1/earnings (기간 손익 및 수익률)

​

요청 파라미터 (Request)

​

응답 필드 (Response: data[].assets[])

​

4대 회계 불변식

• GET /v1/earnings를 interval=all로 호출하고, opening.totalValue가 0이 되도록 start를 계정의 최초 활동 시점 또는 그 이전으로 지정하십시오. start는 GET /v1/accounts/{account}/positions의 openedAt을 사용하면 되며(그보다 이른 시점도 가능), end는 보고 기준 시점으로 지정합니다. 이때 해당 행의 inflows, outflows, pnl이 생애 누적 값입니다.
• inflows와 outflows는 트랜잭션 단위로 상계되고, 출금은 청구(claim) 대금이 지급되는 시점에 인식되며, 지갑 범위에서는 이전 작업 시점의 볼트 지분 가치로 평가한 지분 이전을 포함합니다. 총 현금 입금액·출금액이 아닙니다. 보관처 이전(Custody Migration)의 경우 이전된 지분은 수신 지갑의 inflows에 평가 가치로 반영됩니다. 예: 유입액 21,509,075.692925 = 승계 원가 21,503,019.316660 + 내재 이익 6,056.376265이며, 이 내재 이익은 netTransferredUnrealizedPnl로 보고됩니다.
• inflows, outflows, pnl이 null이면 해당 행은 검산 실패가 아니라 검산 불가 상태입니다(quality.reasons 확인).
• 이 수치를 /v1/accounts/{account}/positions의 totalEarnings와 혼용하지 마십시오. 두 수치는 산출 방식이 달라 서로 대사되지 않습니다.
• 생애 누적 조회는 캐시가 없을 때 10초 이상 걸릴 수 있으므로 단독 요청으로 실행하십시오.

​

조회 범위

• /v1/vaults에서 chain-qualified vault.id를 확인하십시오. 비활성 보유분도 보존됩니다.
• 각 자산은 {chainId, address, decimals}를 갖습니다. 동일 자산 내에서만 금액을 합산하십시오.
• 지갑 범위는 온체인 주소를 따릅니다. 동일 실소유자 통합은 소유권 확인·유효일·이전 연결 증거를 갖춘 별도 파트너 원장이 필요합니다.
• account를 생략하면 지분 보유자의 투자 성과를 집계합니다. 운영자 매출은 별도 회계 범위가 필요하며, 전략 손익은 harvest 보고에서 확인합니다.

​

한 번에 조회: KST 일별 보고

• closing.totalValue = opening.totalValue + inflows - outflows + pnl
• 원가·손익 증거가 완전한 경우: pnl = realizedPnl + unrealizedPnlChange - netTransferredUnrealizedPnl
• 예시는 9월 9일 00:00 KST에 마감하며, 다음 날 시작은 동일한 경계를 사용합니다. opening.block과 closing.block은 해당 시점 직전의 확정 블록을 나타냅니다.

​

보고 구간 변경

• KST 일별·월별 보고는 선택한 지역 달력을 따릅니다. IANA 시간대는 서머타임을 반영하며, 고정 오프셋은 일정한 시계 규칙을 유지합니다.
• 일별·월별 보유액은 각 행의 opening과 closing을 확인하십시오. 시간가중 평균 보유액은 별도 산출 정책이 필요합니다.
• interval을 생략하면 임의의 전체 기간을 조회할 수 있습니다. 동일 기준의 이웃 TWR은 기하 연결됩니다: 1 + 전체 기간 수익률 = Product(1 + 행 수익률). 연환산값은 전체 기간을 조회하십시오.
• 보고서를 마감하기 전에 전체 페이지를 확인하고, 쿼리·응답·증거를 내보내기 파일과 함께 보존하십시오.

​

평가 기준별 수익률 제공 범위

​

경계 평가

총 평가 자산 (totalValue) = 활성 운용 지분 가치 (positionValue) + 출금 대기금 (redemptionReceivable)
활성 운용 지분 가치 (positionValue) = 보유 지분 수량 (shares) × PPS

• Free funds: Free Funds = 보고된 총자산 - 유효 Locked Profit
• 기초 토큰 배분액: Underlying 배분액 = floor(보유 지분 * Free Funds / 총 발행량)
• 자산 환산: Wrapper 볼트(예: EarnUSDT가 seCDV를 거쳐 USDT로 환산)의 경우 동일 블록의 하위 볼트 convertToAssets를 통해 환산되며, 토큰 소수점(10^6)으로 나누기 전에 정수 내림(floor)을 유지합니다.
• 출금 대기금: 미수령 출금 청구권의 명목 가치.

• 원시 지분에 free funds를 곱하고 발행량으로 한 번 나눈 뒤 underlying 금액을 환산하십시오. 반올림된 pricePerShare 견적은 참고용이며, 대규모 보유분에 직접 곱하면 정밀도 손실이 발생합니다.
• EarnUSDT는 동일 블록에서 seCDV를 거쳐 USDT로 환산되며, 각 컨트랙트 단계는 정수 내림을 유지합니다.
• 정상적인 빈 Vault는 발행량과 보유 지분이 0이며 보유 가치는 0입니다. 불일치 상태는 제공되지 않습니다.
• Free funds는 유효 locked profit을 제외하며, 보고된 자산은 전략 보고를 따릅니다. 추정 NAV는 보고 전 지원되는 전략 추정치를 포함할 수 있습니다. 발생주의 평가, Harvest 및 보고를 참고하십시오.
• 기간은 [t_0, t_1)로 정의됩니다: t_0의 이벤트는 포함되고, t_1의 이벤트는 다음 기간으로 넘어갑니다.

​

원가와 인식

미실현손익 = 활성 지분 가치 - 취득원가

• 활성 지분 가치 (positionValue): 선택한 평가 기준에 따른 활성 지분 평가액.
• 취득원가 (costBasis): 활성 지분에 배분된 검증된 잔여 취득원가 (출금 채권 제외).
• 미실현손익 (unrealizedPnl): 경계 시점의 평가이익 잔액.

안분 차감 원가 = floor(이전 전 원가 * 처분 지분 / 이전 전 지분)
잔여 취득원가  = 이전 전 원가 - 안분 차감 원가
실현손익       = 처분 대가 - 안분 차감 원가

• 정상적인 지분 이전의 경우 안분된 원가가 수신 지갑으로 승계됩니다.
• 출금(소각) 시 수령 대가와 안분된 원가의 차이가 realizedPnl로 인식됩니다.
• 보관처 이전 (Custody Migration, 지갑 간 이전): 구 수탁 지갑에서 신 수탁 지갑으로의 지분 이동에는 임의의 두 지갑 간 영수증 검증된 지분 이전과 동일한 일반 규칙(wallet-transfer-pro-rata-v1)이 적용됩니다. SuperEarn은 주소·법인 등록부를 운영하지 않으며 실소유자에 대해 어떠한 판단도 하지 않습니다. 전량 이전은 남은 원가 전부를 승계하고, 일부 이전은 floor(원가 × 송신 지분 / 보유 지분)만 승계하며 나머지는 송신 지갑에 남습니다. 순수 이전은 처분이 아니므로 실현손익은 0입니다. FAQ Q3 참조.

​

손익 분해와 대사

기간 총순손익 = 실현손익 + 미실현손익 변화량 - 순 이전 미실현손익

• 미실현손익 변화량 (unrealizedPnlChange): 기말 미실현손익 - 기초 미실현손익
• 순 이전 미실현손익 (netTransferredUnrealizedPnl): 지분 이전으로 유입/유출된 내재 평가이익:
  순 이전 미실현손익 = 유입 지분의 (시가 - 승계원가) 합계 - 유출 지분의 (시가 - 승계원가) 합계
  
• 대사 잔여값 (residual): 검증된 원장에서 총순손익 - (실현손익 + 미실현손익 변화량 - 순 이전 미실현손익) = 0이 성립해야 합니다.

​

지분 이전 예시

​

예시

​

기간 손익

기말 총자산 (closing.totalValue) = 기초 총자산 (opening.totalValue) + 외부 유입 - 외부 유출 + 기간 손익(PnL)

기간 손익(PnL) = 기말 총자산 - 기초 총자산 - (외부 유입 - 외부 유출)

​

기간 수익률

• 자금 이동 없는 구간의 성장률:
  구간 성장률 = 구간 기말 잔고 / 구간 기초 잔고
  
• 자금 이동 시점 경계: 외부 자본 추가 및 인출 효과를 분리하기 위해 이동 직전과 직후의 자산을 측정합니다.
• 기간 TWR: 모든 하위 구간의 성장 배수를 기하 연쇄합니다:
  1 + 기간 TWR = Product(하위 구간 성장 배수)
  

​

연환산 지표

공식 선형 APR = 기간 TWR * (Year Seconds / Elapsed Seconds)
복리 APY      = (1 + 기간 TWR) ^ (Year Seconds / Elapsed Seconds) - 1

• 공식 선형 APR (return.apr): 모든 기간(1시간, 1일, 1개월)에 걸쳐 지수적 왜곡 없이 일관되게 제공되는 공식 연환산 기준.
• 복리 APY (return.apy): 7일 미만 구간을 포함하여 수익률이 정의되는 모든 기간에 산출됩니다. 기간 수익률을 산출할 수 없거나 연환산 결과를 표현할 수 없는 경우에만 null입니다. 7일 미만 구간의 값은 하베스트 및 잠금이익 해제 시점의 영향을 증폭하는 가상의 연환산 값이므로, null이 아닌 return.apy라고 해서 그대로 표시하기에 적합한 것은 아닙니다. 단기 구간에는 return.apr과 return.periodRate를 우선 사용하고, 필요하면 자체 표시 기준(예: end - start < 7일이면 apy 숨김)을 적용하십시오.

​

PPS APY

PPS APY = (기말 PPS / 기초 PPS) ^ (Year Seconds / Elapsed Seconds) - 1

• 기초 PPS와 기말 PPS는 관측 윈도우 시작과 종료 시점의 확정 주당 가치입니다.
• 지갑의 개별 자금 흐름을 반영한 포트폴리오 수익률은 /earnings의 return.apr 및 return.apy를 확인하십시오.

​

계약 이자

기간 이자 = 기지급 이자 + 기말 미수 이자 - 기초 미수 이자

미수 발생 이자 = floor((체크포인트 스케일 이자 + 원금 * 이율_bps * 발생 경과 초) / (10,000 * Year Seconds))

• 발생 경과 초: max(최근 체크포인트, 시작 시간)부터 min(T, 만기)까지의 경과 초.
• 원금 및 이율: 기본 토큰 atoms 단위 원금과 베이시스 포인트(100 bps = 1%) 이율.

​

파트너 회계 FAQ

​

보고 근거

• Scalar에서 잔고 규격, 손익 필드 및 정밀도, APY 필드를 확인하십시오.
• 별도로 지원되는 손상 및 보고 조정은 발생주의 평가, Harvest 및 보고를 참조하십시오.
• 기존 레거시 내보내기는 경로별 수식을 유지합니다. Legacy 비교를 확인하십시오.