메인 콘텐츠로 건너뛰기
SuperEarn Data API는 온체인에서 검증된 상태, 과거 잔고, 수익률, 자산 배분 및 출금 추적 데이터를 제공하는 공개 읽기 전용(Read-only) REST 서비스입니다. 개발자 문서는 다음 두 가지 주요 영역으로 명확하게 구분되어 있습니다:
  • 데이터 API: 볼트 탐색, 지갑 포트폴리오 화면 표시, 활동 내역 스트림 및 출금 생애주기 추적을 위한 실무 개발 연동 패턴.
  • 파트너 회계 및 보고: 기관 파트너 및 감사인을 위한 기업 법정회계(IFRS) 기준의 4대 회계 불변식, 이동평균 취득원가, 손익 인식 및 기말 결산 대사 체계.

환경 및 기본 URL

모든 Data API 엔드포인트는 표준 HTTP GET 메서드를 사용하며 ISO-8601 타임스탬프가 포함된 JSON 형태로 응답합니다.

연동 경로 비교

애플리케이션에 필요한 작업(공개 조회, 대화형 견적, 사용자 트랜잭션, 자동 정산)에 따라 적절한 연동 경로를 선택하십시오:

토큰 단위 및 소수점 정밀도

운영 EarnJPYC는 Kaia(8217)의 18-decimal 고정이율 지분 토큰 0x794B606e216c24b6675804fFa081CdDa8586FA59 (eip155:8217:0x794b606e216c24b6675804ffa081cdda8586fa59, 배포 블록 230960963)를 사용하며 운영 Data API 카탈로그(GET /v1/vaults, GET /v1/vault-read-plans)에 등록되어 있습니다. 재무 보고에 사용하기 전에 응답의 meta.quality를 확인하고, 조회 불가(503)나 미완료(null) 값을 잔액 0으로 처리하지 마세요. 온체인 직접 호출 사양은 EarnJPYC 온체인 연동을 참고하세요.
Data API의 모든 금액은 컨트랙트 정수 단위(Atoms) 또는 표준 소수점 단위로 표현됩니다. 연산 및 화면 표시 시 정확한 정밀도를 유지하십시오: 필수 계산 원칙
  • 변동 수익형(EarnUSDT) 가치 평가: 변동 수익형 지분은 루트 볼트 지분(valuationMethod: "yearn-free-funds", floor(shares * (totalAssets - effectiveLockedProfit) / totalSupply))을 나타냅니다. EarnUSDT는 seCDV를 거쳐 USDT(6 decimals)로 환산됩니다. 매 컨트랙트 단계마다 정수 내림(Integer Floor)을 유지한 후 10decimals10^{\text{decimals}}로 나누어야 합니다.
  • 고정이율(BoringVault, 예: EarnJPYC) 가치 평가: 고정이율 볼트 지분은 항상 18 decimals이며, Accountant.getRate()는 기초 자산(base asset)의 decimals(JPYC는 10^18, USDT는 10^6) 단위를 사용합니다. 지분 가치는 floor(shares * rate / 10^18)(valuationMethod: "accountant-rate")로 환산합니다. GET /v1/vault-read-plans를 호출해 각 볼트의 architecture("yearn" vs "boring-vault"), valuationMethod("yearn-free-funds" vs "accountant-rate"), withdrawal.kind("cooldown" vs "atomic-queue") 메타데이터를 확인하십시오.
  • 소수점 정밀도 연산: 금융 및 회계 연산 시 부동소수점(Float)을 절대 사용하지 마십시오. 임의 정밀도 십진 라이브러리(Decimal)나 정수 연산을 사용하여 반올림 오차를 방지해야 합니다.
  • 슬리피지 설정: Router를 통해 트랜잭션을 제출할 때는 반드시 0보다 큰 명시적 최소 수령액(minAmountOut 또는 minimumShares)을 지정하십시오.

API 규약 및 품질 상태

캐싱 및 수집 상태 (quality)

Data API는 등록된 볼트와 계정에 대해 검증된 온체인 증거를 사전에 지속적으로 수집하고 인덱싱합니다:
  • quality.status = complete: 모든 기초 온체인 블록, 트랜잭션, 상태 증거가 정상 수집 및 검증 완료된 상태입니다.
  • quality.status = partial: 일부 과거 증거가 현재 인덱싱 중입니다. quality.reasons에 구체적인 사유(예: *_collection_pending)가 명시됩니다.
  • null 값 보존: 수집되지 않았거나 산출 불가능한 증거에 의존하는 필드(예: 과거 취득 시점 증거 누락)는 null로 반환됩니다. 클라이언트나 결산 시스템은 이 null을 임의로 0으로 치환하지 말고 그대로 보존해야 합니다.

조회 범위 (Scope)

/v1/balances 및 /v1/earnings 엔드포인트는 다양한 조회 범위를 지원합니다:
  • 프로토콜 전체 범위 (account, vault 모두 생략): 배포된 모든 볼트의 전체 관리 자산 집계.
  • 볼트 범위 (vault 지정): 해당 볼트 내 전체 지분 보유자 집계.
  • 지갑 범위 (account 지정): 특정 지갑 주소가 보유한 모든 볼트 자산 집계.
  • 지갑–볼트 범위 (account, vault 모두 지정): 특정 지갑이 특정 볼트 내에서 보유한 자산 집계.

다음 단계