- 데이터 API: 볼트 탐색, 지갑 포트폴리오 화면 표시, 활동 내역 스트림 및 출금 생애주기 추적을 위한 실무 개발 연동 패턴.
- 파트너 회계 및 보고: 기관 파트너 및 감사인을 위한 기업 법정회계(IFRS) 기준의 4대 회계 불변식, 이동평균 취득원가, 손익 인식 및 기말 결산 대사 체계.
환경 및 기본 URL
모든 Data API 엔드포인트는 표준 HTTP GET 메서드를 사용하며 ISO-8601 타임스탬프가 포함된 JSON 형태로 응답합니다.
연동 경로 비교
애플리케이션에 필요한 작업(공개 조회, 대화형 견적, 사용자 트랜잭션, 자동 정산)에 따라 적절한 연동 경로를 선택하십시오:토큰 단위 및 소수점 정밀도
Data API의 모든 금액은 컨트랙트 정수 단위(Atoms) 또는 표준 소수점 단위로 표현됩니다. 연산 및 화면 표시 시 정확한 정밀도를 유지하십시오:
필수 계산 원칙
- EarnUSDT 가치 평가: EarnUSDT 지분은 최상위 루트 볼트 지분을 나타냅니다. 루트 볼트 지분 가치 산식에 따라 seCDV로 먼저 환산된 후, seCDV가 다시 USDT로 환산됩니다. 매 컨트랙트 단계마다 정수 내림(Integer Floor)을 유지한 후 1,000,000(10^6)으로 나누어야 합니다.
- 소수점 정밀도 연산: 금융 및 회계 연산 시 부동소수점(Float)을 절대 사용하지 마십시오. 임의 정밀도 십진 라이브러리(Decimal)나 정수 연산을 사용하여 반올림 오차를 방지해야 합니다.
- 슬리피지 설정: Router를 통해 트랜잭션을 제출할 때는 반드시 0보다 큰 명시적 최소 수령액(
minAmountOut)을 지정하십시오.
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모두 지정): 특정 지갑이 특정 볼트 내에서 보유한 자산 집계.