메인 콘텐츠로 건너뛰기
Scalar API 레퍼런스 · 보고 TL;DR: 보유 잔고·원가·손익·수익률 · 데이터 API 개요 본 문서는 SuperEarn Data API를 활용하여 애플리케이션, 클라이언트 대시보드 및 지갑 인터페이스를 구축할 때 필요한 표준 연동 패턴을 안내합니다. 기관 파트너 회계, IFRS 기준 재무제표 작성 및 감사 검산 체계는 잔고, 원가 및 수익 회계 문서를 참고하십시오.

용도별 연동 패턴

패턴 1: 볼트 목록 및 시장 금리 탐색

사용 가능한 투자 상품 목록과 현재 운용 성과를 표시하는 방법:
  1. 전체 볼트 목록 조회: GET /v1/vaults를 호출하여 배포된 SuperVault 목록을 조회합니다. 현재 신규 입금이 가능한 상품은 status: "active"로 필터링하고, 과거 이력이 있는 비활성 볼트는 포트폴리오 조회를 위해 보존합니다.
  2. 볼트 메타데이터 확인: GET /v1/vaults/{vault}로 컨트랙트 주소, 기초 자산, 소수점 자릿수(decimals) 및 운영 상태를 확인합니다.
  3. 최근 수익률 확인: GET /v1/apy?vault={vault}를 호출하여 공식 직전 7일 주당순자산가치 기반 연환산 수익률(pps_apy)을 가져옵니다.
  4. 시장 벤치마크 금리 비교: GET /v1/market-rates를 조회하여 Morpho, Aave 및 Kaia 생태계 기준 금리와 볼트 수익률을 비교 표시합니다.

패턴 2: 지갑 포트폴리오 화면 구성

연결된 사용자 지갑의 자산 현황을 완전하게 렌더링하는 방법:
  1. 현재 잔고 조회: GET /v1/balances?account={walletAddress}&at={timestamp}를 호출합니다. at은 필수이며(예: at=2026-09-01T00:00:00Z), 현재 시각 또는 특정 과거 기준 시점을 전달하여 해당 시점의 잔고를 가져옵니다. at이 없는 요청은 400을 반환합니다.
  2. 총자산 및 지분 분해 표시:
    • 총 관리 자산 평가액 (totalValue): 활성 운용 지분 평가액과 출금 대기금의 합산 (positionValue + redemptionReceivable, [Unit: asset]).
    • 지분 토큰 수량 (shares): 사용자가 보유한 볼트 LP 토큰의 원시 수량 ([Unit: shareToken], 메타데이터는 shareToken 객체 참조).
    • 활성 운용 지분 평가액 (positionValue): 볼트 내에서 매일 이자가 창출되고 있는 실제 운용 자산 (shares * PPS, [Unit: asset]).
    • 출금 대기금 (redemptionReceivable): CooldownVault(EarnUSDT)에서 출금 신청 완료 후 쿨다운 중이거나 클레임 대기 중인 원금 확정 채권("0"이 아님, 추가 이자 미발생). 반면 고정이율 BoringVault(EarnJPYC)는 AtomicQueue 체결(redeemSolve) 전까지 지분이 지갑에 유지되어 이자가 계속 발생하므로 redemptionReceivable = "0"이며 평가액이 positionValue에 포함됩니다.
    • 총 평가 자산 항등식:
  3. 투자 원금 및 미실현 손익 표시:
    • costBasis: 이동평균원가법으로 계산된 장부상 잔여 순투자원금 ([Unit: asset]).
    • unrealizedPnl: positionValue - costBasis로 산출되는 미실현 평가손익 ([Unit: asset]).
  4. 품질 상태 확인: quality.status를 점검합니다. 과거 취득 시점 온체인 데이터가 인덱싱 중인 경우 costBasis 및 unrealizedPnl이 null로 반환될 수 있습니다. 이 경우 0으로 대체하지 말고 null 상태를 유지하십시오.
정확한 지분 가치 평가 및 정수 내림 수식은 경계 평가 수식을 참조하십시오.

패턴 3: 거래 및 활동 내역 피드

계정의 거래 타임라인을 표시하는 방법:
  1. 계정 활동 내역 호출: GET /v1/accounts/{account}/activity를 호출합니다. 선택 필터로 type(position, redemption, balance)과 vault를 사용할 수 있으며, limit(1~100)과 cursor로 페이지를 순회합니다. 이 엔드포인트는 start / end 시간 필터를 지원하지 않으며, 전달하면 400을 반환합니다.
  2. type으로 행을 구분한 뒤 operation으로 분류: 모든 행에는 해당 행을 선택하는 type 필터 값과 동일한 type 구분자가 있습니다. position과 balance 행에는 대문자 operation 필드가 있고, redemption 행에는 operation이 없으며 대신 status가 있습니다. deposit, redemption_request, claim, transfer_in, transfer_out 값은 존재하지 않습니다. operation 값:
    • MINT: 계정으로 신규 수량이 발행된 내역. position 행에서는 볼트 지분이 발행된 예치입니다.
    • BURN: 계정에서 수량이 소각된 내역. position 행에서는 계정이 직접 실행한 지분 소각입니다.
    • SEND: 전송으로 계정에서 수량이 나간 내역. position 행에서는 shares가 음수입니다. 라우터를 통한 출금 요청은 라우터로의 지분 SEND와 redemption 행으로 함께 표시됩니다.
    • RECEIVE: 전송으로 계정에 수량이 들어온 내역. 보관처 이전(in-kind)도 포함됩니다.
    • LOCKUP (balance 전용): 계정의 잠금 수량 변동. amount는 부호가 있는 값이며 locked가 결과를 나타냅니다.
    • FETCH (balance 전용): 해당 토큰을 계정에 대해 처음 추적할 때 체인에서 읽은 잔고 스냅샷. 전송이 아니므로 amount는 0이고 transactionHash는 null입니다.
    redemption 행: status는 정산 전 pending, 정산 후 claimed입니다. 청구는 별도 행을 만들지 않으며, 동일한 행에 claimedAt, claimTransactionHash, receivedAssets가 채워집니다. operation은 nullable 문자열로 제공되므로, 알 수 없는 값이나 null을 오류 없이 처리하십시오.
  3. 트랜잭션 순흐름 원칙: 단일 트랜잭션 내에서 복수의 작업이 발생한 경우, 순자금 변동(Net flow)을 대조하여 지갑의 잔고 증감과 일치시킵니다.

패턴 4: 출금 생애주기 추적

EarnUSDT 출금은 CooldownVault의 신청·청구 절차를, 운영 EarnJPYC 등 고정이율 볼트 출금은 AtomicQueue의 요청·원자적 체결(redeemSolve) 절차를 사용하며 두 모델 모두 GET /v1/accounts/{account}/redemptions에서 조회할 수 있습니다. 출금 모델별 의미 구분은 GET /v1/vault-read-plans의 withdrawal.kind를 기준으로 확인하세요(AtomicQueue에서는 cooldownEndsAt이 요청 체결 기한이며, 체결 완료 후 status: "claimed" 상태에서는 온체인 슬롯이 정리되어 assets가 "0"이 되고 실제 수령액은 claim.assets에 기록됩니다):
변동이율(CooldownVault) vs 고정이율(BoringVault + AtomicQueue) 비교 및 주의사항 (EarnUSDT · EarnJPYC)

패턴 5: 페이지네이션, 시간대 및 쿼리 규칙

대량의 거래 내역이나 과거 데이터를 순회할 때의 표준 규칙:
  • 커서 기반 페이지네이션: 페이지네이션을 지원하는 모든 목록 엔드포인트(예: /v1/earnings, /v1/harvests, /v1/accounts/{account}/activity)는 page.nextCursor와 page.hasMore를 담은 page 객체를 반환합니다. 다음 페이지 요청 시 page.nextCursor 값을 cursor 쿼리 파라미터로 전달하십시오. /v1/balances는 단일 스냅샷을 반환하며 페이지네이션 대상이 아닙니다.
  • 빈 중간 페이지 처리: page.hasMore가 false가 될 때까지(이때 page.nextCursor는 null) 계속 순회하십시오. 내부 필터링 조건에 따라 중간 페이지에 데이터 배열(data[])이 비어 있더라도 다음 커서가 존재할 수 있습니다.
  • 짧은 페이지 처리: /v1/earnings의 interval 조회에서는 서버 작업 예산(work budget)으로 인해 한 페이지의 행 수가 limit보다 적을 수 있습니다. 행 수가 적다고 순회를 멈추지 말고 page.hasMore가 false가 될 때까지 항상 page.nextCursor를 따라가십시오.
  • 시간대 및 기준 시각:
    • 타임스탬프는 ISO-8601 표준을 완벽히 지원합니다 (예: start=2026-09-01T00:00:00+09:00).
    • GET /v1/harvests는 start와 end가 모두 필수이며, 오프셋을 명시한 초 단위 RFC 3339 타임스탬프여야 합니다 (예: start=2026-09-01T00:00:00Z). start=2026-09-01과 같이 날짜만 전달하면 400을 반환합니다.
    • 일별 또는 월별 달력 단위 집계 시 timezone=Asia/Seoul과 같이 지역 시간대를 명시하십시오.
    • 마감 기준 시각을 변경하려면 cutoff=HH:mm:ss 파라미터를 사용하십시오.

패턴 6: 빌링·재무 보고용 시종가, 잔고 및 입출금 이력 조회 (EarnUSDT 및 EarnJPYC)

운영 EarnJPYC는 Kaia(8217)의 18-decimal 고정이율 지분 토큰 0x794B606e216c24b6675804fFa081CdDa8586FA59 (eip155:8217:0x794b606e216c24b6675804ffa081cdda8586fa59, 배포 블록 230960963)를 사용하며 운영 Data API 카탈로그(GET /v1/vaults, GET /v1/vault-read-plans)에 등록되어 있습니다. 아래 엔드포인트 매핑은 EarnUSDT와 EarnJPYC 모두에 동일하게 적용됩니다(단, 변동금리 SuperVault 전략 리포트 전용인 GET /v1/harvests는 고정이율 BoringVault에서 503 accountant_history_unavailable을 반환합니다). 재무 보고에 사용하기 전에 응답의 quality.status(및 meta.quality)를 확인하고, 조회 불가(503)나 미완료(null) 값을 잔액 0으로 처리하지 마세요. 컨트랙트 직접 호출 사양은 EarnJPYC 온체인 연동을 참고하세요.

주식형(지분 가치 평가) 정산 7대 필수 항목 및 변동·고정이율 볼트 비교 (EarnUSDT · EarnJPYC)

다음은 지분 가치 평가 정산에 필요한 7가지 항목입니다. 변동이율 볼트(EarnUSDT, CooldownVault)와 고정이율 볼트(EarnJPYC, BoringVault + AtomicQueue) 모두 아래의 동일한 엔드포인트 및 응답 필드에 대응합니다:
회계 대사 주의사항 (이중 합산 방지): 변동이율 **CooldownVault**는 출금 요청 시 지분이 소각되어 positionValue에서 redemptionReceivable로 이동합니다(totalValue = positionValue + redemptionReceivable). 반면 고정이율 **BoringVault (AtomicQueue)**는 redeemSolve 체결 전까지 지분이 지갑 shares(positionValue)에 남아 이자가 계속 발생하므로 redemptionReceivable = "0"입니다. 따라서 고정이율 볼트에서는 positionValue에 /redemptions?status=pending의 data[].assets를 별도로 합산하지 마십시오.

EarnUSDT 및 EarnJPYC 요청 및 응답 예시

1. 지원되는 볼트의 시점 잔고

EarnJPYC 응답 예시 (GET /v1/balances, valuation=pps):
EarnJPYC 기본 평가 모드(valuation=pps)는 위와 같이 quality.status: "complete"를 반환합니다. 현재 고정이율 볼트는 valuation=estimated_nav 호출 시 503 accounting_rpc_unavailable을, include=reconciliation 호출 시 reconciliation.quality.status: "unavailable"("accounting_rpc_unavailable")을 반환합니다.

2. 일별 시종가(기초·기말 평가액), 지분·자산 수량 및 기간 수익률 (GET /v1/earnings)

3. 지원되는 볼트의 입출금 이력과 출금 요청

전체 이력은 page.nextCursor를 끝까지 따라가고, 보고서에 사용하기 전에 quality.status를 확인하세요.
고정이율 EarnJPYC(AtomicQueue)에서 shares는 요청한 볼트 지분 수량, assets는 현재 미결제 대기 슬롯 평가액이며 cooldownEndsAt은 쿨다운 종료 시각이 아닌 요청 체결 기한입니다. 솔버(redeemSolve)가 요청을 원자적으로 정산하면 status가 "claimed"가 되고 온체인 대기 슬롯이 비워지므로 assets.value는 "0"으로 리셋되며, 실제 수령한 원금+이자 금액은 claim.assets.value(예: "480000")에 기록됩니다. 위의 출금 비교표와 해당 볼트의 read plan을 함께 확인하세요.

4. EarnJPYC 일별 시종가(GET /v1/earnings, 2026-11-16 KST) 응답 예시

EarnJPYC는 18 decimals(JPYC) 정밀도로 응답하며, 입출금이 없는 날(inflows: "0", outflows: "0")에도 opening.totalValue + pnl = closing.totalValue (1571386.344881141536243 + 83.067262772204247 = 1571469.41214391374049)가 정확히 일치합니다.

연동 점검 체크리스트

  • 사용자의 총자산 표시 시 totalValue (또는 positionValue + redemptionReceivable)를 사용하고 있는가?
  • 정수 연산(Atoms) 정밀도를 유지하고 화면 표시 직전에만 자산 소수점(10610^6: USDT/EarnUSDT, 101810^{18}: JPYC/EarnJPYC 및 고정이율 BoringVault 지분)으로 나누는가?
  • 응답의 quality.status와 quality.reasons를 검사하고, 미완료 필드의 null 값을 임의로 0으로 바꾸지 않고 유지하는가?
  • page.hasMore가 false가 될 때까지 page.nextCursor를 따라 페이지네이션을 끝까지 순회하는가?
  • 예치 및 출금 시 볼트 유형에 맞는 공식 라우터/큐(EarnUSDT는 SuperEarnRouter, 고정이율 볼트는 Router 및 AtomicQueue)를 거치도록 구현했는가?

관련 문서