> ## Documentation Index > Fetch the complete documentation index at: https://docs.superearn.io/llms.txt > Use this file to discover all available pages before exploring further. # 잔고, 원가 및 수익 회계 > 회계 모델, 4대 감사 불변식, 이동평균 원가, 손익 인식 및 파트너 감사 FAQ. [Scalar API 레퍼런스](https://api.superearn.io/v1/docs) · [데이터 API 개요](/ko/developers/data-access) · [연동 패턴](/ko/developers/data-api) · [발생주의 평가, Harvest 및 보고](/ko/developers/accrual-accounting) · [실무 회계 대사 워크스루](/ko/developers/reconciliation-guide) ## TL;DR **조회 기간의 완전한 재무제표를 얻으려면 `GET /v1/earnings`를 한 번 호출하십시오.** `account`와 `vault`를 지정하고 시작일과 종료일을 선택합니다. 응답의 `data[]` 내 각 기간별로, `assets[]` 항목에서 다음 필드를 확인합니다: | 재무적 질문 | API 필드 | 회계적 의미 및 성격 | | -------------------------- | ------------------------------------------ | -------------------------------------------------------------------------- | | 기초/기말에 총 얼마를 보유했는가? | `opening.totalValue`, `closing.totalValue` | 미수금을 포함한 재무상태표상 총 자산 | | 현재 볼트의 몇 지분을 보유하고 있는가? | `shares` | 볼트 지분 토큰 수량 (소각/환금 전 원시 지분 수량) | | 지분 토큰의 온체인 정보는 무엇인가? | `shareToken` | 지분 토큰 메타데이터 (`chainId`, `address`, `symbol`, `decimals`) | | 활성 운용액과 출금 대기금은 각각 얼마인가? | `positionValue`, `redemptionReceivable` | 이자 창출 운용 자산 vs 이자 미발생 확정 채권 | | 활성 지분에 남아있는 투자 원금은 얼마인가? | `costBasis` | 잔여 지분에 배분된 이동평균 기준 역사적 취득원가 | | 현재 누적된 미실현 평가이익은 얼마인가? | `unrealizedPnl` | 활성 운용 지분 가치에서 잔여 취득원가를 뺀 평가이익 | | 이번 기간에 순수하게 얼마를 벌었는가? | `pnl` | 외부 자금 유출입을 발라낸 기간 총 순손익 | | 출금으로 확정된 실현이익은 얼마인가? | `realizedPnl` | 기중 출금/처분 대가에서 안분 차감된 취득원가를 뺀 확정 실현익 | | 미실현 평가이익은 얼마나 변했는가? | `unrealizedPnlChange` | 기말 미실현이익 잔액 - 기초 미실현이익 잔액 | | 지분 이전으로 유입/유출된 평가이익은 얼마인가? | `netTransferredUnrealizedPnl` | 지분 이체 시 승계된 순 미실현 평가이익 | | 이번 기간의 실질 기간 수익률은 얼마인가? | `return.periodRate` | 해당 기간의 실질 True TWR 수익률 (100을 곱해 % 표시) | | 공식 선형 연환산 수익률은 얼마인가? | `return.apr` | ACT/365 기준 단순 연환산 (모든 기간에 일관된 공식 기준) | | 복리 연환산 수익률은 얼마인가? | `return.apy` | ACT/365 기준 복리 연환산 (수익률이 정의되는 모든 기간에 산출. 7일 미만은 가상의 외삽값이므로 `return.apr` 권장) | | 어떤 수익률 산출 방식이 사용되었는가? | `return.method` | `time_weighted` (모든 외부 자금 흐름을 분할한 True TWR) | **결산 전 필수 확인 사항** * **총 평가 자산**: `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 요청 및 응답 필드 규격 통합 회계 엔드포인트인 `GET /v1/balances`와 `GET /v1/earnings`의 핵심 파라미터 및 응답 필드 정의입니다. 상세 대화형 스펙 및 실시간 테스트는 [Scalar API 레퍼런스](https://api.superearn.io/v1/docs)를 참고하십시오. ### 단위(Unit) 체계 SuperEarn의 모든 수치 필드는 명확한 단위 규격을 따릅니다: | 단위 표기 | 대상 필드 | 설명 | | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- | | **`[Unit: asset]`** | `totalValue`, `positionValue`, `redemptionReceivable`, `costBasis`, `unrealizedPnl`, `inflows`, `outflows`, `pnl`, `realizedPnl`, `unrealizedPnlChange`, `netTransferredUnrealizedPnl` | Vault의 기준 기초 자산 토큰 단위 (예: USDT, JPYC). 포트폴리오 총액과 손익을 측정하는 법정 통화 대용 단위. | | **`[Unit: shareToken]`** | `shares` | Vault가 발행한 지분 ERC-20 토큰 단위 (예: EarnUSDT, EarnJPYC). 소각/환금 전 원시 보유 수량. | | **`[Unit: ratio]`** | `return.periodRate`, `return.apr`, `return.apy` | 무차원 백분율 비율 (1.0 = 100%). | ### `GET /v1/balances` (시점 잔고 스냅샷) 특정 시점(온체인 확정 블록) 기준의 자산 평가액 및 잔고 구성을 조회합니다 (재무상태표 잔액 측정용). #### 요청 파라미터 (Request) | 파라미터 | 필수 | 타입 | 기본값 | 설명 | | ----------- | :----: | ------------------------ | ----- | ------------------------------------------------------------------- | | `at` | **필수** | ISO-8601 | - | 잔고 측정 기준 시각 (예: `2026-09-01T00:00:00Z`). 해당 시각 직전의 최신 온체인 확정 블록 기준. | | `account` | 선택 | 주소 (`0x...`) | 전체 | 조회할 지갑 주소. 생략 시 볼트의 전체 지분 보유자(수수료 계정 포함) 합산. | | `vault` | 선택 | Vault ID | 전체 | 조회할 볼트 ID (`eip155:8217:0x...`). 생략 시 전체 볼트 합산. | | `valuation` | 선택 | `pps` \| `estimated_nav` | `pps` | 평가 기준 (`pps`: 볼트 공식 주당순자산가치 / `estimated_nav`: 하위 전략 실시간 추정치 포함). | | `include` | 선택 | `reconciliation` | - | 온체인 회계 대사용 보조 증빙 데이터(컨트랙트 원천 지표) 포함 여부. | #### 응답 필드 (Response: `data[].assets[]`) | 필드명 | 단위 | 타입 | 회계적 의미 및 실무 정의 | | | ---------------------- | :----------: | ---------------------- | ----------------------------------------------------------------------------- | ----------------------------- | | `totalValue` | `asset` | Decimal String | **총 관리 자산 평가액** = `positionValue` + `redemptionReceivable`. (지갑 내 미예치 현금 제외). | | | `shares` | `shareToken` | Decimal String \| null | **활성 운용 지분 토큰 수량** (볼트 지분 ERC-20 토큰의 원시 보유 수량. 지분 미보유 시 0 또는 null). | | | `shareToken` | - | Object \| null | **지분 토큰 메타데이터** (`chainId`, `address`, `symbol`, `decimals`). | | | `positionValue` | `asset` | Decimal String | **활성 운용 지분 가치** (볼트 내에서 이자가 창출 중인 지분 평가액, `shares × PPS`). | | | `redemptionReceivable` | `asset` | Decimal String | **출금 대기 채권** (출금 신청 완료 후 쿨다운 중이거나 수령 대기 중인 원금 확정액. 이자 미발생). | | | `costBasis` | `asset` | Decimal String \| null | **잔여 취득원가** (이동평균원가법 기준 잔여 활성 지분의 취득 원금. 증빙 부족 시 `null`). | | | `unrealizedPnl` | `asset` | Decimal String \| null | **누적 미실현 평가손익** = `positionValue - costBasis`. | | | `block` | - | Object | 스냅샷 기준 온체인 확정 블록 정보 (`number`, `hash`, `timestamp`). | | | `quality` | - | Object | 온체인 증빙 완전성 상태 (\`status: "complete" | "partial"`, `reasons: \[]\`). | *** ### `GET /v1/earnings` (기간 손익 및 수익률) 특정 기간 동안의 자산 변동, 자금 유출입, 실현/미실현 손익, 수익률을 조회합니다 (손익계산서 작성용). #### 요청 파라미터 (Request) | 파라미터 | 필수 | 타입 | 기본값 | 설명 | | ----------- | :----: | --------------------------------------------- | ---------- | ----------------------------------------------------- | | `start` | **필수** | ISO-8601 / 날짜 | - | 조회 시작 시각 (구간 포함, `[start, end)`). | | `end` | **필수** | ISO-8601 / 날짜 | - | 조회 종료 시각 (구간 제외). `start`보다 늦어야 합니다. | | `account` | 선택 | 주소 (`0x...`) | 전체 | 조회할 지갑 주소. | | `vault` | 선택 | Vault ID | 전체 | 조회할 볼트 ID (`eip155:8217:0x...`). | | `interval` | 선택 | `all` \| `hour` \| `day` \| `week` \| `month` | `all` | 기간 분할 단위 (`all`: 단일 전체 구간, `hour`: 1시간, `day`: 1일 등). | | `timezone` | 선택 | IANA 명칭 / 오프셋 | `UTC` | 회계 캘린더 타임존 (예: `Asia/Seoul`, `+09:00`). | | `cutoff` | 선택 | `HH:mm:ss` | `00:00:00` | 일별/월별 마감 기준 시각 (예: `09:00:00` 지정 시 오전 9시 기준 하루 분할). | | `valuation` | 선택 | `pps` \| `estimated_nav` | `pps` | 평가 기준. | | `limit` | 선택 | Integer (1\~100) | `20` | 페이징 행 수 (`interval=all`일 때는 생략). | | `cursor` | 선택 | String | - | 다음 페이지 조회를 위한 커서 토큰 (`page.nextCursor`). | #### 응답 필드 (Response: `data[].assets[]`) | 필드명 | 단위 | 타입 | 회계적 의미 및 실무 정의 | | ----------------------------- | :-----: | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `opening` | - | Object | **기초 시점 잔고 스냅샷** (시작 시점의 `totalValue`, `shares`, `positionValue`, `costBasis` 등). | | `closing` | - | Object | **기말 시점 잔고 스냅샷** (종료 시점의 `totalValue`, `shares`, `positionValue`, `costBasis` 등). | | `shareToken` | - | Object \| null | **지분 토큰 메타데이터** (`chainId`, `address`, `symbol`, `decimals`). | | `inflows` | `asset` | Decimal String \| null | **외부 자금 순유입액** (트랜잭션 단위로 상계한 외부 흐름 중 양수의 합: 입금, 그리고 지갑 범위에서는 이전 작업 시점 가치로 평가한 지분 수신. 총 입금 규모가 아님). | | `outflows` | `asset` | Decimal String \| null | **외부 자금 순유출액** (트랜잭션 단위로 상계한 외부 흐름 중 음수의 절댓값 합: 청구(claim) 지급 시점에 인식되는 출금 대금, 그리고 지갑 범위에서는 이전 작업 시점 가치로 평가한 지분 송신. 총 출금 규모가 아님). | | `pnl` | `asset` | Decimal String \| null | **당기 총순손익** = `closing.totalValue - opening.totalValue - inflows + outflows`. | | `realizedPnl` | `asset` | Decimal String \| null | **확정 실현손익** (기간 중 출금/처분으로 실현된 손익 = `처분 대가 - 안분 취득원가`). | | `unrealizedPnlChange` | `asset` | Decimal String \| null | **미실현 평가손익 변동분** = `closing.unrealizedPnl - opening.unrealizedPnl`. | | `netTransferredUnrealizedPnl` | `asset` | Decimal String \| null | **지분 이체 승계 손익** (외부 지분 전송/수신으로 장부에 들어오거나 나간 평가이익). | | `return.periodRate` | `ratio` | Decimal String | **실질 기간 수익률** (True TWR 기반 실질 성과 비율. 100을 곱해 % 표시). | | `return.apr` | `ratio` | Decimal String | **단순 연환산 수익률** (ACT/365 기준 공식 단순 연환산 = `periodRate × 365 / 기간일수`). | | `return.apy` | `ratio` | Decimal String \| null | **복리 연환산 수익률** (ACT/365 복리 연환산 = `(1 + periodRate) ^ (31,536,000 / 경과 초) - 1`. 수익률이 정의되는 모든 기간에 산출되며, 기간 수익률을 산출할 수 없거나 결과값을 표현할 수 없는 경우에만 `null`. 7일 미만은 가상의 외삽값이므로 `return.apr` 권장). | | `return.method` | - | String | 수익률 산출 알고리즘 (`time_weighted`). | | `quality` | - | Object | 온체인 증빙 완전성 상태. | ## 4대 회계 불변식 SuperEarn의 회계 데이터는 \*\*4대 회계 불변식(Audit Invariants)\*\*을 기준으로 산출됩니다. 외부 감사인 및 파트너사 재무팀은 다음 4대 항등식을 통해 원장을 독립적으로 검산하고 대사할 수 있습니다. | 영역 | 검산 항등식 (Audit Invariant) | 보증하는 회계적 실질 | | :-------------- | :---------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- | | **1. BS 자산 합산** | `totalValue = positionValue + redemptionReceivable` | 활성 운용자산과 출금 대기 채권의 합이 총자산 (`positionValue = shares × PPS`) | | **2. BS 원금 분해** | `positionValue = costBasis + unrealizedPnl` | 운용자산은 장부상 취득원가와 누적 미실현이익의 합 | | **3. PL 손익 분해** | `pnl = realizedPnl + unrealizedPnlChange - netTransferredUnrealizedPnl` | 당기순익은 실현이익, 미실현 증감 및 이전 조정의 합 | | **4. 생애 누적 총익** | `pnl = closing.totalValue + outflows - inflows` (`opening.totalValue = 0`일 때) | 생애 총순익은 현재 총자산 + 생애 `outflows` - 생애 `inflows`. 기초 잔고가 0인 기간 손익 항등식이며 독립된 별도 검산은 아님 | **생애 누적 원장 조회 방법** * `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)](#파트너-회계-faq)의 경우 이전된 지분은 수신 지갑의 `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초 이상 걸릴 수 있으므로 단독 요청으로 실행하십시오. ### 조회 범위 | 잔고·손익 범위 | 파라미터 | 집계 대상 | | ------------ | ------------------------ | ------------------------------------ | | **프로토콜 전체** | `account`, `vault` 모두 생략 | 수수료 지분을 포함한 전체 공개 root Vault의 관리 자산 | | **Vault** | `vault` | 해당 root Vault의 전체 지분 보유자 (수수료 지분 포함) | | **지갑** | `account` | 해당 지갑이 보유한 전체 root Vault 지분 | | **지갑–Vault** | `account`, `vault` 모두 지정 | 해당 지갑의 특정 root Vault 보유분 | **핵심** * `/v1/vaults`에서 chain-qualified `vault.id`를 확인하십시오. 비활성 보유분도 보존됩니다. * 각 자산은 `{chainId, address, decimals}`를 갖습니다. 동일 자산 내에서만 금액을 합산하십시오. * 지갑 범위는 온체인 주소를 따릅니다. 동일 실소유자 통합은 소유권 확인·유효일·이전 연결 증거를 갖춘 별도 파트너 원장이 필요합니다. * `account`를 생략하면 지분 보유자의 투자 성과를 집계합니다. 운영자 매출은 별도 회계 범위가 필요하며, 전략 손익은 [harvest 보고](/ko/developers/accrual-accounting#harvest-보고와-투자자-손익-연계)에서 확인합니다. ### 한 번에 조회: KST 일별 보고 9월 8일 KST 마감 조회의 경우 지갑과 Vault를 지정하고 9월 8일\~9일, 일별 interval, `Asia/Seoul`을 설정합니다. 정확한 요청은 [earnings 레퍼런스](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings)를 참고하십시오. **자산별 행 검산** * `closing.totalValue = opening.totalValue + inflows - outflows + pnl` * 원가·손익 증거가 완전한 경우: `pnl = realizedPnl + unrealizedPnlChange - netTransferredUnrealizedPnl` * 예시는 9월 9일 00:00 KST에 마감하며, 다음 날 시작은 동일한 경계를 사용합니다. `opening.block`과 `closing.block`은 해당 시점 직전의 확정 블록을 나타냅니다. ### 보고 구간 변경 | 보고서 | 파라미터 | | ---------------- | ------------------------------------------------------------------ | | 단일 전체 기간 | `interval` 생략; 하나의 통합 기간 조회 | | KST 특정일 | `start=2026-09-01T00:00:00+09:00`, `end=2026-09-02T00:00:00+09:00` | | UTC 일별 | 날짜 쌍 + `interval=day`; timezone 기본값 `UTC` | | KST 일별 | 날짜 쌍 + `interval=day&timezone=Asia/Seoul` | | KST 월별 | 날짜 쌍 + `interval=month&timezone=Asia/Seoul` | | 고정 오프셋 UTC+05:45 | 날짜 쌍 + `timezone=+05:45` | | 시간별 | 날짜 쌍 + `interval=hour` | | 커스텀 마감 시각 | 날짜 쌍 또는 calendar interval + `cutoff=HH:mm:ss` | **핵심** * KST 일별·월별 보고는 선택한 지역 달력을 따릅니다. IANA 시간대는 서머타임을 반영하며, 고정 오프셋은 일정한 시계 규칙을 유지합니다. * 일별·월별 보유액은 각 행의 `opening`과 `closing`을 확인하십시오. 시간가중 평균 보유액은 별도 산출 정책이 필요합니다. * `interval`을 생략하면 임의의 전체 기간을 조회할 수 있습니다. 동일 기준의 이웃 TWR은 기하 연결됩니다: `1 + 전체 기간 수익률 = Product(1 + 행 수익률)`. 연환산값은 전체 기간을 조회하십시오. * 보고서를 마감하기 전에 전체 페이지를 확인하고, 쿼리·응답·증거를 내보내기 파일과 함께 보존하십시오. ### 평가 기준별 수익률 제공 범위 | 선택한 평가 기준 / 자금 흐름 | 제공 결과 | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **PPS, 외부 자금 흐름 있음** | True TWR은 모든 외부 흐름 작업 전후의 검증된 포트폴리오 가치가 필요하며, 증거가 부족하면 수익률은 null | | **추정 NAV, 외부 자금 흐름 없음** | 유효한 자본이 있는 검증된 기초·기말 NAV로 지원; 검증된 내부 대체는 내부 흐름으로 유지 | | **추정 NAV, 외부 자금 흐름 있음** | 작업 시점 NAV 상태가 없어 `twr_nav_flow_state_unavailable`로 수익률은 null. 검증된 현금 흐름으로 손익(PnL)은 지원 가능 | | **추정 NAV, NAV 평가액 없는 외부 지분 이전** | `inflows`, `outflows`, `pnl`, `netTransferredUnrealizedPnl`은 null. 검증된 `costBasis`, 독립적으로 확인된 `realizedPnl`, 미실현 변화량은 제공 | 특정 증거 누락은 `quality`를 확인하십시오. 제공되지 않는 수익률은 연환산에서도 null을 유지합니다. ## 경계 평가 요청 시점 `T`의 스냅샷은 `T` 직전의 최신 온체인 확정 블록에서 측정합니다. 해당 블록에서 총 평가 자산은 활성 운용 지분과 출금 대기금의 합입니다: ```text theme={null} 총 평가 자산 (totalValue) = 활성 운용 지분 가치 (positionValue) + 출금 대기금 (redemptionReceivable) 활성 운용 지분 가치 (positionValue) = 보유 지분 수량 (shares) × PPS ``` 활성 지분 가치는 보유자의 free funds 지분율로 도출됩니다: * **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 및 보고](/ko/developers/accrual-accounting)를 참고하십시오. * 기간은 `[t_0, t_1)`로 정의됩니다: `t_0`의 이벤트는 포함되고, `t_1`의 이벤트는 다음 기간으로 넘어갑니다. ## 원가와 인식 경계 시점에서 활성 지분 가치는 취득원가와 미실현손익으로 분해됩니다: ```text theme={null} 미실현손익 = 활성 지분 가치 - 취득원가 ``` * **활성 지분 가치 (`positionValue`)**: 선택한 평가 기준에 따른 활성 지분 평가액. * **취득원가 (`costBasis`)**: 활성 지분에 배분된 검증된 잔여 취득원가 (출금 채권 제외). * **미실현손익 (`unrealizedPnl`)**: 경계 시점의 평가이익 잔액. 지분이 이전되거나 출금(소각)될 때는 원가가 비율에 따라 안분 차감됩니다: ```text theme={null} 안분 차감 원가 = floor(이전 전 원가 * 처분 지분 / 이전 전 지분) 잔여 취득원가 = 이전 전 원가 - 안분 차감 원가 실현손익 = 처분 대가 - 안분 차감 원가 ``` * 정상적인 지분 이전의 경우 안분된 원가가 수신 지갑으로 승계됩니다. * 출금(소각) 시 수령 대가와 안분된 원가의 차이가 `realizedPnl`로 인식됩니다. * **보관처 이전 (Custody Migration, 지갑 간 이전)**: 구 수탁 지갑에서 신 수탁 지갑으로의 지분 이동에는 임의의 두 지갑 간 영수증 검증된 지분 이전과 동일한 일반 규칙(`wallet-transfer-pro-rata-v1`)이 적용됩니다. SuperEarn은 주소·법인 등록부를 운영하지 않으며 실소유자에 대해 어떠한 판단도 하지 않습니다. 전량 이전은 남은 원가 전부를 승계하고, 일부 이전은 `floor(원가 × 송신 지분 / 보유 지분)`만 승계하며 나머지는 송신 지갑에 남습니다. 순수 이전은 처분이 아니므로 실현손익은 0입니다. [FAQ Q3](#파트너-회계-faq) 참조. ### 손익 분해와 대사 기간 총순손익은 확정 실현이익, 잔여 지분의 미실현이익 변동, 지분 이전에 따른 순 미실현이익 조정액으로 분해됩니다: ```text theme={null} 기간 총순손익 = 실현손익 + 미실현손익 변화량 - 순 이전 미실현손익 ``` * **미실현손익 변화량 (`unrealizedPnlChange`)**: `기말 미실현손익 - 기초 미실현손익` * **순 이전 미실현손익 (`netTransferredUnrealizedPnl`)**: 지분 이전으로 유입/유출된 내재 평가이익: ```text theme={null} 순 이전 미실현손익 = 유입 지분의 (시가 - 승계원가) 합계 - 유출 지분의 (시가 - 승계원가) 합계 ``` * **대사 잔여값 (`residual`)**: 검증된 원장에서 `총순손익 - (실현손익 + 미실현손익 변화량 - 순 이전 미실현손익) = 0`이 성립해야 합니다. ### 지분 이전 예시 원가 50, 평가액 60인 지분이 이전되는 경우 (가격 변동 없음 가정): | 지갑 / 이벤트 | `realizedPnl` | `unrealizedPnlChange` | `netTransferredUnrealizedPnl` | `pnl` | | ---------------------- | ------------: | --------------------: | ----------------------------: | ----: | | 송신 지갑 전체 지분 전송 | 0 | -10 | -10 | 0 | | 수신 지갑 지분 수신 (원가 50 승계) | 0 | +10 | +10 | 0 | | 수신 지갑 추후 60에 전액 출금 | +10 | -10 | 0 | 0 | ### 예시 기초 가치 110, 원가 100인 단일 지갑 (이후 가격 변동 없음): | 이벤트 | 활성 지분 가치 | 취득원가 | 미실현손익 | 출금 대기금 | 기간 회계 효과 | | ------------------- | -------: | ---: | ----: | -----: | ------------------------- | | 기초 상태 | 110 | 100 | 10 | 0 | 총 관리 자산 110 | | 출금 신청(소각) -> 청구권 생성 | 0 | 0 | 0 | 110 | 실현익 +10; 미실현변동 -10; 순손익 0 | | 쿨다운 완료 후 미지급 대기 | 0 | 0 | 0 | 110 | 청구권 명목 가치 유지 | | 최종 110 현금 수령 | 0 | 0 | 0 | 0 | 외부 유출 110; 추가 손익 0 | | 손실 수용 정산: 109 수령 시 | 0 | 0 | 0 | 0 | 요청 종결; 유출 109; 지급손실 1 | ## 기간 손익 기간 손익은 외부 자금 유출입을 반영하여 기초와 기말 총자산(totalValue)을 연결합니다: ```text theme={null} 기말 총자산 (closing.totalValue) = 기초 총자산 (opening.totalValue) + 외부 유입 - 외부 유출 + 기간 손익(PnL) ``` 기간 손익(PnL) 산출: ```text theme={null} 기간 손익(PnL) = 기말 총자산 - 기초 총자산 - (외부 유입 - 외부 유출) ``` | 자금 이동 유형 | 지갑 범위 | Vault 전체 범위 | | ---------------- | -------------------- | ----------- | | 외부 지갑으로부터의 신규 예치 | 유입(Inflow) | 유입(Inflow) | | 지분 보유자 간 지분 이체 | 송신자 유출; 수신자 유입 | 내부 이동 (상쇄) | | 동일 지갑의 출금 신청 확정 | 자산 재분류 (운용자산 -> 미수금) | 자산 재분류 | | 출금 대기금의 최종 지갑 수령 | 유출(Outflow) | 유출(Outflow) | ## 기간 수익률 `return.method=time_weighted`는 외부 자금 유출입 시점을 기준으로 구간을 분할하여 True Time-Weighted Return (TWR)을 계산합니다: * **자금 이동 없는 구간의 성장률**: ```text theme={null} 구간 성장률 = 구간 기말 잔고 / 구간 기초 잔고 ``` * **자금 이동 시점 경계**: 외부 자본 추가 및 인출 효과를 분리하기 위해 이동 직전과 직후의 자산을 측정합니다. * **기간 TWR**: 모든 하위 구간의 성장 배수를 기하 연쇄합니다: ```text theme={null} 1 + 기간 TWR = Product(하위 구간 성장 배수) ``` ### 연환산 지표 경과 시간을 `Elapsed Seconds`, 1년을 `Year Seconds = 31,536,000`초(`365 * 86,400`)로 정의할 때: ```text theme={null} 공식 선형 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 `/v1/apy`는 최근 7일간의 주당순자산가치(PPS) 변동을 추적합니다. ```text theme={null} PPS APY = (기말 PPS / 기초 PPS) ^ (Year Seconds / Elapsed Seconds) - 1 ``` * `기초 PPS`와 `기말 PPS`는 관측 윈도우 시작과 종료 시점의 확정 주당 가치입니다. * 지갑의 개별 자금 흐름을 반영한 포트폴리오 수익률은 `/earnings`의 `return.apr` 및 `return.apy`를 확인하십시오. ## 계약 이자 기관 전용 `/interest` 엔드포인트는 체크포인트 원금과 고정 금리 ACT/365 발생 기준을 사용합니다: ```text theme={null} 기간 이자 = 기지급 이자 + 기말 미수 이자 - 기초 미수 이자 ``` 경계 시점 `T`의 미수 발생 이자는 직전 체크포인트로부터 계산됩니다: ```text theme={null} 미수 발생 이자 = floor((체크포인트 스케일 이자 + 원금 * 이율_bps * 발생 경과 초) / (10,000 * Year Seconds)) ``` * **발생 경과 초**: `max(최근 체크포인트, 시작 시간)`부터 `min(T, 만기)`까지의 경과 초. * **원금 및 이율**: 기본 토큰 atoms 단위 원금과 베이시스 포인트(100 bps = 1%) 이율. ## 파트너 회계 FAQ **상황**: 전체 펀드 지분의 90%를 출금할 때 장부상 잔여 미실현이익이 급격히 줄어듭니다. 2026년 6월 파트너사는 `unrealizedPnlChange`가 **-\$2,750만 달러**로 표시되어 손실이 난 것이 아닌지 질의했습니다. **회계적 실질**: 대규모 출금 시 지분이 소각되면서 그동안 쌓여 있던 평가이익이 현금으로 실현됩니다. 이동평균원가 모델에 따라: * 미실현 평가이익 통에서 2,750만 달러가 빠져나가므로 `unrealizedPnlChange`는 **-\$2,750만 달러**가 됩니다. * 동시에 출금으로 확정된 실현이익이 **+\$2,750만 달러**(`realizedPnl`)로 계상됩니다. * 손익 항등식에 대입하면: ```text theme={null} PnL = realizedPnl + unrealizedPnlChange = (+2,750만) + (-2,750만) = 0 ``` 장부상 순이익은 전혀 왜곡되지 않으며, 평가이익이 실현이익으로 온전히 전환되었을 뿐입니다. **상황**: 출금 신청 완료 후 생성된 `redemptionReceivable`의 법정회계상 성격과 이자 발생 여부. **회계적 실질**: * **원금 100% 보존**: 명목 출금 청구액은 프로토콜에 의해 100% 확정 지급 보증됩니다. * **비운용 확정 채권**: 출금 신청 시점에 볼트 지분이 소각되었으므로 더 이상 볼트 자산 성장에 참여하지 않으며, 쿨다운 대기 기간 동안 추가 이자는 0%입니다. * **재무상태표 분류**: 활성 운용 지분(`positionValue`, 이자 창출 자산)과 구분하여 회수 대기 중인 '단기 미수금/현금성 확정 채권'으로 계상합니다. **상황**: 구 수탁 지갑에서 신 수탁 지갑으로 지분을 이동할 때 처분 손익 발생 여부. **회계적 실질**: * **일반 이전 규칙**: 임의의 두 지갑 간 영수증 검증된 모든 지분 이전은 송신 지갑의 안분 취득원가를 수신 지갑으로 승계합니다(정책 `wallet-transfer-pro-rata-v1`). 별도의 주소 등록이나 온보딩 절차는 없습니다. SuperEarn은 주소·법인 등록부를 운영하지 않으며, 이 규칙은 실소유자에 대해 어떠한 판단도 하지 않습니다. 무관한 제3자 지갑으로의 이전에도 동일하게 적용됩니다. * **원가 승계**: 전량 이전은 남은 원가 전부를 승계합니다. 일부 이전은 `floor(원가 × 송신 지분 / 보유 지분)`만 승계하며 나머지는 송신 지갑에 남습니다. * **실현손익 0**: 순수 이전은 처분이 아니므로 양쪽 모두 실현손익(`realizedPnl`)은 0입니다. * **`/v1/earnings`에서의 양측 표시**: 송신 지갑은 이전 가치를 `outflows`로, 음수의 `netTransferredUnrealizedPnl`(가치 - 승계 원가)을 보고합니다. 수신 지갑은 동일한 가치를 `inflows`로 보고하고, `costBasis`가 승계 원가만큼 증가하며, 같은 크기의 양수 `netTransferredUnrealizedPnl`을 보고합니다. 따라서 지갑 단위의 `inflows` / `outflows`에는 보관처 이전이 포함되며 입출금 규모와 같지 않습니다. * **실제 예시**: 가치 21,509,075.692925의 전량 이전에서 승계 원가는 21,503,019.316660, 내재 이익은 6,056.376265입니다. 송신 지갑은 `outflows = 21,509,075.692925`, `costBasis` 21,503,019.316660 → 0, `realizedPnl = 0`, `netTransferredUnrealizedPnl = -6,056.376265`을 보고하고, 수신 지갑은 `netTransferredUnrealizedPnl = +6,056.376265`을 보고합니다. * **사유 코드**: 증거가 부족하면 승계 원가 또는 손익 분해가 `null`이 되며 `quality.reasons`에 원인이 표시됩니다: * `transfer_cost_basis_unverified`: 이전된 지분에 대한 송신 지갑의 취득원가가 검증되지 않음. * `transfer_evidence_unavailable`: 이전 영수증을 검증할 수 없음. * `transfer_valuation_unavailable`: 이전 작업 시점의 가치를 확인할 수 없음. * `receiver_change_unsupported`: 해당 기간에 대기 중인 출금의 청구 수령인(receiver)이 변경됨. * `redemption_intermediary_cost_unavailable`: Router(출금 경유 컨트랙트)가 기존 지분을 보유하고 있어 경유 원가를 분리할 수 없음. * **이전 전 조치**: 대기 중인 출금은 먼저 청구하거나 정산하십시오. 이전 과정에서 대기 중인 출금의 수령인을 변경하면 영향을 받는 지갑 기간에 `receiver_change_unsupported`가 반환됩니다. * **활동 내역**: `GET /v1/accounts/{account}/activity`에는 보관처 이전이 지분 수량만 포함된 `SEND` 또는 `RECEIVE` position 행으로만 표시되며 `principal`, `value`, `earnings`, `realizedGain`은 `null`입니다. 금액 효과는 `/v1/earnings`에서 확인하십시오. **상황**: 하위 전략에서 이자가 발생해도 볼트 PPS는 7일에 걸쳐 서서히 오릅니다. 과거 레거시 프로토타입에는 하베스트 직후의 잠금이익을 즉시 손익에 반영하던 `accountedBy=harvestReport` 모드가 있었는데, 왜 v1 공식 회계에서는 제외되었으며 필요한 정보는 어떻게 조회해야 하나요? **회계적 실질**: * SuperVault 아키텍처는 하베스트로 보고된 수익을 `lockedProfit` 버퍼에 격리한 뒤 7일에 걸쳐 선형으로 해제합니다 (MEV 및 샌드위치 공격 방지 목적). * **공식 잔고/손익에서 제외되는 이유**: 1. *하베스트 시점의 청구권 및 환금성 부재 (IFRS 자산 인식 요건)*: 홀더가 하베스트 직후 출금(`redeem`)하면 컨트랙트는 잠금이익을 제외한 PPS(`freeFunds`)만 지급합니다. 출금 시점에 회수할 권리가 없는 미해제 금액을 홀더의 잔고나 손익으로 잡는 것은 회계 기준에 위배됩니다. 2. *신규 입금에 따른 지분 희석*: 7일 동안 신규 입금이 발생하면 신규 지분권자에게도 잠금이익이 안분되어 기존 홀더의 몫이 희석됩니다. 3. *원장 통산 불변식 붕괴*: 장부 잔고만 locked profit을 더해 높여 놓으면, 실제 출금 시점에 실제 현금 수령액과의 차이로 인해 대규모 허위 처분손실이 발생하여 원장 대사가 왜곡됩니다. * **v1에서의 공식 조회 방법**: 1. *감사 대사 증빙*: `GET /v1/earnings?include=reconciliation`으로 공식 PPS 장부는 유지하면서 `reportedAssets`, `lockedProfit`, `rounding` 차이 내역을 함께 수령. 2. *전략 하베스트 원천 내역*: `GET /v1/harvests`로 키퍼 보고 순수익, 부과 수수료, 보고 시점 지분율 배분액을 이벤트 원천 데이터로 확인. 3. *실시간 하위 발생 수익*: `GET /v1/earnings?valuation=estimated_nav`로 루트 볼트 보고 이전의 하위 운용처 실시간 가치를 경제적 실질로 확인. **상황**: 7일 미만 구간에서 `return.apy`보다 `return.apr`을 우선해야 하는 이유. **회계적 실질**: * 초단기 수익률(예: 1일 0.05%)을 365제곱하여 기하급수로 연환산(APY)하면 하베스트 시점에 따라 수백%로 폭등하거나 음수로 떨어지는 지수 왜곡(Compounding Blow-up)이 발생합니다. * 따라서 SuperEarn은 모든 기간에 대해 왜곡이 없는 \*\*선형 연환산(APR, ACT/365)\*\*을 공식 표준으로 제공합니다. API는 수익률이 정의되는 모든 기간에 `return.apy`를 산출하며 7일 미만이라고 해서 `null`로 처리하지 않습니다. 따라서 단기 구간의 `apy`는 가상의 외삽값으로 취급하여, `return.periodRate`와 `return.apr`을 기본으로 표시하고 `apy`는 보조 지표로만 사용하십시오. 외부 감사인 및 재무팀은 Data API에서 추출한 데이터에 대해 엑셀에서 다음 수식을 입력하여 4대 불변식을 검증할 수 있습니다: | 검증 단계 | 엑셀 검산 수식 | 기대 잔여값 | | :------------------------------------------------------------ | :--------------------------------------------------------------------------------- | :--------- | | **1. BS 자산 합산** | `=ROUND(positionValue + redemptionReceivable - totalValue, 6)` | `0.000000` | | **2. BS 원금 분해** | `=ROUND(costBasis + unrealizedPnl - positionValue, 6)` | `0.000000` | | **3. 기간 손익 검산** | `=ROUND(closing_totalValue - opening_totalValue - inflows + outflows - pnl, 6)` | `0.000000` | | **4. 손익 분해 항등식** | `=ROUND(realizedPnl + unrealizedPnlChange - netTransferredUnrealizedPnl - pnl, 6)` | `0.000000` | | **5. 생애 누적 총순익** (`opening_totalValue = 0`인 `interval=all` 행) | `=ROUND(closing_totalValue + outflows - inflows - pnl, 6)` | `0.000000` | ## 보고 근거 | 단계 | 보고 조치 | | ------ | -------------------------------- | | 정밀도 보존 | 정수·소수점 계산과 각 수식의 내림(floor) 규칙 유지 | | 범위 검토 | 결산 전 누락된 값, 품질 사유 및 대사 일치 여부 확인 | | 데이터 확정 | 쿼리, 응답, 적용 정책, 자산 식별 및 원천 증거 보존 | | 정정 처리 | 기존 발행 원본을 보존하면서 새로운 버전 및 사유 연결 | * Scalar에서 [잔고 규격](https://api.superearn.io/v1/docs#tag/balances/GET/balances), [손익 필드 및 정밀도](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings), [APY 필드](https://api.superearn.io/v1/docs#tag/apy/GET/apy)를 확인하십시오. * 별도로 지원되는 손상 및 보고 조정은 [발생주의 평가, Harvest 및 보고](/ko/developers/accrual-accounting)를 참조하십시오. * 기존 레거시 내보내기는 경로별 수식을 유지합니다. [Legacy 비교](/ko/private/data-api-migration-guide)를 확인하십시오.