> ## 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. # Legacy와 v1 > 기존 QA 호환 보고와 현재 v1 회계의 차이. [데이터 API 개요](/ko/developers/data-access) · [Data API 활용](/ko/developers/data-api) · [잔고, 원가 및 수익 회계](/ko/developers/financial-data) ## API 선택 | 항목 | QA 호환 legacy | 현재 `/v1` | | ------ | -------------------------------------------- | ------------------------------------ | | 목적 | 기존 연동의 연속성 | 확정 경계 기반 투자 회계 | | 경로 | `/legacy/external/...` 및 기존 호환 경로 | `/balances`, `/earnings`, `/apy` | | 계산 | 검증된 원천 범위에서 경로별 QA 원산식 유지 | 지원 기간 전체에 공개한 평가·흐름·원가 정책 적용 | | 시간 | 기존 경로·grain 규칙; holder/PPS는 종료된 UTC 일자 | 정확한 시점 또는 현지 보고 날짜; $[start,end)$ | | 경계 | 보존한 원천 선택·과거 규칙 | 각 경계 직전의 마지막 canonical 확정 블록 | | 금액 | 과거 필드·scale 유지; `Usd` 필드의 raw 소수 6자리 USDT 포함 | 자산 식별자를 동반한 native-asset decimal 문자열 | | 수익률 계산 | 범위별 평균 자본 | 모든 외부 흐름의 평가액을 사용하는 True TWR | | APY | Legacy ACT/365·표시 규칙 | PPS APY 또는 기간 연환산값을 명시해 제공 | | 증거 누락 | 미지원·불완전 재구성은 명시적 `503` | Unavailable·partial과 영향받는 필드의 `null` | | 발행 보고서 | 원본 export 보존 | 보고서별 query·응답·정책·증거 저장 | **핵심** * 기존 소비자는 legacy 계약을 유지할 수 있습니다. 신규 연동은 현재 v1을 사용합니다. * V1은 지원 이력에 같은 공개 정책을 적용합니다. 전환일 파라미터는 필요하지 않습니다. * `/legacy/public/v1/...`은 과거 공개 금융 payload의 호환성이 필요한 소비자에게 제공합니다. * 발행 원본·재계산값을 별도로 보존하고 정정 시 새 버전·사유를 연결합니다. ## 현재 조회 | 용도 | 요청 | | ---------------- | -------------------------------------------- | | 특정 시점 잔고 | `/v1/balances?at=…` | | 한 구간 손익 | `/v1/earnings?start=…&end=…` | | 일별·월별 보고 | `interval=day` 또는 `month` 추가; `timezone` 선택 | | 시간별 시작·마감 값 | `/v1/earnings`에 `interval=hour` | | 관측 Vault APY | `/v1/apy?vault=…` | | 전략 Harvest 보고 내역 | `/v1/harvests?start=…&end=…` | | 보고 자산 및 잠금이익 대사 | `/v1/earnings`에 `include=reconciliation` 추가 | | 실시간 하위 운용처 수익 추정 | `/v1/earnings`에 `valuation=estimated_nav` 추가 | | 지갑·Vault 범위 | 잔고·손익에 `account` 및/또는 `vault` 추가 | * 달력·페이지·payload는 [Scalar 레퍼런스](https://api.superearn.io/v1/docs)을 따릅니다. * 대사 시 자산·계정 범위·시간 경계·잔고 구성요소를 일치시킵니다. ### 레거시 harvestReport 및 totalAssets 인식 방식의 전환 레거시 엔드포인트는 7일간의 선형 PPS 해제 이전에 키퍼 보고 수익을 즉시 반영하기 위해 `accountedBy=harvestReport` 및 `accountedBy=totalAssets`를 지원했습니다. v1에서는: * 공식 홀더 손익 및 잔고는 `valuation=pps` (또는 하위 운용처 실시간 발생액을 추정하는 `valuation=estimated_nav`)로만 산출됩니다. 하베스트 시점에는 즉시 출금할 권리가 없고, 이후 7일간의 신규 입금으로 이익이 희석되므로 미해제 잠금이익은 공식 PnL에서 제외됩니다. * 전략별 하베스트 보고 수익을 확인하려면 `GET /v1/harvests`를 호출하여 확정 이벤트, 순이익 및 지갑별 배분액을 조회하십시오. * 공식 PPS 잔고와 잠금이익을 포함한 컨트랙트 총자산 간의 차이를 검증하려면 `/v1/balances` 또는 `/v1/earnings`에 `include=reconciliation`을 추가하십시오. ## 평균 자본 복원된 **holder/PPS** 계산: ```text theme={null} C_bar = (1 / D) * Sum(C_j * delta_t_j) r_legacy = E_legacy / C_bar APR = r_legacy * (Y / D) g = 1 + max(r_legacy, -0.999999) APY = g^(Y / D) - 1 ``` | 변수 | 정의 | | ------------------ | ------------------------------------------------- | | `C_j`, `delta_t_j` | 원금이 일정한 각 구간의 잔여 원금·경과 초 | | `D`, `Y` | 구간 초; `Y = 365 * 86,400` | | `C_bar` | 시간가중 잔여 원금; `averageCapitalUsd` 출력은 raw 정수 단위로 절사 | | `E_legacy` | 마감 가치 − 시작 가치 − legacy로 분류한 순자금 흐름 | **계산 규칙** * 수익률에는 반올림 전 자본·손익을 사용하고 금액 출력은 0 방향으로 절사합니다. * 자본·기간은 양수여야 합니다. Legacy 연환산값의 절댓값이 50을 넘거나 유한하지 않으면 `null`을 반환합니다. * 거듭제곱은 QA 호환 계산의 기존 숫자 처리 방식을 유지합니다. * Holder/PPS 시작은 `start` 이하, 마감은 `end - 1초` 이하의 상태를 선택합니다. 흐름은 `(start, end - 1초]`입니다. 시작·마감 평균과 시간가중 잔고: ```text theme={null} B_endpoints = (B_0 + B_1) / 2 B_time = (1 / D) * Integral(B(t) dt) from t_0 to t_1 ``` * 잔고가 구간 전체에서 선형으로 변하면 두 값이 일치합니다. * 구간 중 예치·출금·평가액 급변이 있으면 시간가중 계산에 실제 경로가 필요합니다. * Holder/PPS의 분모는 잔여 원금 `C(t)`입니다. 시장 가치 `B(t)`와 구분해 사용하십시오. * 복원된 vault/PPS는 보존 checkpoint의 사다리꼴 자본을 사용합니다. 범위 선택 전 아래 원천 지원 표를 확인하십시오. ### Vault/PPS 자본 호환 Vault checkpoint의 사다리꼴 분모: ```text theme={null} V_bar = (1 / D) * Sum(((V_j + V_{j+1}) / 2) * (u_{j+1} - u_j)) ``` | 변수 | 정의 | | ----------------- | ------------------------------------------------------------ | | `u_0`, `u_n`, `D` | 기간 시작·끝·경과 초 | | `u_j` | 시작·기간 중 checkpoint 시각·끝 | | `V_j` | `u_j` 이하 마지막 호환 supply \* PPS / 10^6; 최종 경계는 `u_n - 1`초까지 선택 | | `V_bar` | 평균 raw 자본; 출력은 정수 단위로 절사 | * 최종 출력·수익률 계산까지 checkpoint 곱·가중 합의 정밀도를 유지합니다. * 호환 분모는 보존한 checkpoint 선택을 따릅니다. V1 경계 평가는 정확한 확정 블록 상태를 사용합니다. ## Legacy 원천 범위 | PPS 범위 | 지원 입력 | | ---------------- | ------------------------------------------------------ | | Holder/depositor | 명시한 Kaia USDT Vault; 기존 지분 원장·불변 QA 선택 가격 묶음 | | Vault 생략 holder | 전체 인덱싱 계정 이력이 검증된 USDT 장부에 속할 때 지원 | | Vault | 명시한 Kaia USDT Vault; 호환 Pipeline 평가 checkpoint·사다리꼴 자본 | | 프로토콜 / 기타 자산 | 과거 구성·자산 매핑 증명 전 `503` | | 기타 `accountedBy` | 기존 계산 경로 유지; 별도 검증 필요 | **주의** * Holder/PPS `endDate`를 명시합니다. 종료일 포함이므로 `2026-09-07`은 `2026-09-08T00:00:00Z`까지 증거가 필요합니다. * 오늘·미수집 기간·가격 또는 이력 누락은 수집 완료까지 `503`을 반환합니다. * 가격 묶음은 원천 ID·정수 가격을 보존합니다. 원천 갱신 후 선택 입력이 달라질 수 있습니다. * 재구성 검증은 해당 입력·기간에 적용됩니다. 발행 원본과의 동일성은 원본 증거로 확인합니다. ## Export 증거 | 헤더 | 보존 내용 | | ------------------------------------ | -------------------------- | | `Superearn-Legacy-Capital-Policy` | Holder 원금 또는 Vault 사다리꼴 정책 | | `Superearn-Legacy-Accounting-Policy` | 해당되는 복원 holder/PPS 정책 | | `Superearn-Legacy-Result` | `recalculated` 분류 | | `Superearn-Legacy-Earnings-Source` | 선택 QA 가격 또는 Pipeline PPS | | `Superearn-Legacy-Evidence` | 정책·가격 묶음·원장·관련 이벤트 증명·기간 | * Export마다 정확한 요청·응답·헤더를 보존합니다. * 가격·이력·자본·QA 증거 누락은 구체적인 `legacy_*_unavailable` 오류를 반환합니다.