용도별 연동 패턴
패턴 1: 볼트 목록 및 시장 금리 탐색
사용 가능한 투자 상품 목록과 현재 운용 성과를 표시하는 방법:- 전체 볼트 목록 조회:
GET /v1/vaults를 호출하여 배포된 SuperVault 목록을 조회합니다. 현재 신규 입금이 가능한 상품은status: "active"로 필터링하고, 과거 이력이 있는 비활성 볼트는 포트폴리오 조회를 위해 보존합니다. - 볼트 메타데이터 확인:
GET /v1/vaults/{vault}로 컨트랙트 주소, 기초 자산, 소수점 자릿수(decimals) 및 운영 상태를 확인합니다. - 최근 수익률 확인:
GET /v1/apy?vault={vault}를 호출하여 공식 직전 7일 주당순자산가치 기반 연환산 수익률(pps_apy)을 가져옵니다. - 시장 벤치마크 금리 비교:
GET /v1/market-rates를 조회하여 Morpho, Aave 및 Kaia 생태계 기준 금리와 볼트 수익률을 비교 표시합니다.
패턴 2: 지갑 포트폴리오 화면 구성
연결된 사용자 지갑의 자산 현황을 완전하게 렌더링하는 방법:- 현재 잔고 조회:
GET /v1/balances?account={walletAddress}&at={timestamp}를 호출합니다.at은 필수이며(예:at=2026-09-01T00:00:00Z), 현재 시각 또는 특정 과거 기준 시점을 전달하여 해당 시점의 잔고를 가져옵니다.at이 없는 요청은400을 반환합니다. - 총자산 및 지분 분해 표시:
- 총 관리 자산 평가액 (
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에 포함됩니다. - 총 평가 자산 항등식:
- 총 관리 자산 평가액 (
- 투자 원금 및 미실현 손익 표시:
costBasis: 이동평균원가법으로 계산된 장부상 잔여 순투자원금 ([Unit: asset]).unrealizedPnl:positionValue - costBasis로 산출되는 미실현 평가손익 ([Unit: asset]).
- 품질 상태 확인:
quality.status를 점검합니다. 과거 취득 시점 온체인 데이터가 인덱싱 중인 경우costBasis및unrealizedPnl이null로 반환될 수 있습니다. 이 경우 0으로 대체하지 말고null상태를 유지하십시오.
패턴 3: 거래 및 활동 내역 피드
계정의 거래 타임라인을 표시하는 방법:-
계정 활동 내역 호출:
GET /v1/accounts/{account}/activity를 호출합니다. 선택 필터로type(position,redemption,balance)과vault를 사용할 수 있으며,limit(1~100)과cursor로 페이지를 순회합니다. 이 엔드포인트는start/end시간 필터를 지원하지 않으며, 전달하면400을 반환합니다. -
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을 오류 없이 처리하십시오. - 트랜잭션 순흐름 원칙: 단일 트랜잭션 내에서 복수의 작업이 발생한 경우, 순자금 변동(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파라미터를 사용하십시오.
- 타임스탬프는 ISO-8601 표준을 완벽히 지원합니다 (예:
패턴 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. 지원되는 볼트의 시점 잔고
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) 정밀도를 유지하고 화면 표시 직전에만 자산 소수점(:
USDT/EarnUSDT, :JPYC/EarnJPYC및 고정이율BoringVault지분)으로 나누는가? - 응답의
quality.status와quality.reasons를 검사하고, 미완료 필드의null값을 임의로 0으로 바꾸지 않고 유지하는가? -
page.hasMore가false가 될 때까지page.nextCursor를 따라 페이지네이션을 끝까지 순회하는가? - 예치 및 출금 시 볼트 유형에 맞는 공식 라우터/큐(
EarnUSDT는SuperEarnRouter, 고정이율 볼트는Router및AtomicQueue)를 거치도록 구현했는가?