Data API 활용 패턴

​

용도별 연동 패턴

​

패턴 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 생태계 기준 금리와 볼트 수익률을 비교 표시합니다.

# 활성 볼트 목록 조회 예시
curl -s "https://api.superearn.io/v1/vaults" | jq '.data[] | {id: .id, name: .name, status: .status}'

​

패턴 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): 출금 신청(redemption request)을 완료하여 쿨다운 중이거나 클레임 대기 중인 자금 ([Unit: asset]). 원금은 100% 온전히 보존되며, 추가 이자 발생이 중단된 확정 채권입니다.
   • 총 평가 자산 항등식:
     총 관리 자산 (totalValue) = 활성 운용 지분 가치 (positionValue) + 출금 대기금 (redemptionReceivable)
     
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 값은 존재하지 않습니다.

   type (필터 및 행)	행이 나타내는 내용	분류 필드	값
   position	계정의 볼트 지분 포지션 변동 (vault, shares)	operation	MINT, BURN, SEND, RECEIVE
   redemption	출금 요청과 그 정산 (redemptionId, assets, shares)	status	pending, claimed
   balance	추적 대상 토큰의 계정 잔고 변동 (assetId, amount, balance, locked)	operation	MINT, BURN, SEND, RECEIVE, LOCKUP, FETCH

   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: 출금 생애주기 추적

[1. 출금 신청] ──► [2. 쿨다운 대기] ──► [3. 수령 가능] ──► [4. 지급 완료]
  Router로           대기 시간 진행           볼트 가용 유동성     사용자 지갑으로
  redeem 실행        (원금 100% 보존,        충족 상태            현금 입금 완료
                     이자 미발생)

• 쿨다운 기간 중 이자 미발생: 출금 신청이 온체인에 등록되면 소각된 지분은 더 이상 볼트 주당순자산가치(PPS) 상승에 참여하지 않습니다. 원금은 100% 보존되는 확정 채권으로 고정됩니다.
• 유동성 확인: 사용자가 직접 claim 트랜잭션을 실행하기 전 GET /v1/allocations/vaults/{vault}/liquidity를 호출하여 가용 유동성을 확인하십시오. 정상 운영 환경에서는 프로토콜 키퍼가 유동성 범위 내에서 자동으로 청구를 실행해 줍니다.

​

패턴 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 파라미터를 사용하십시오.

​

연동 점검 체크리스트

• 사용자의 총자산 표시 시 totalValue (또는 positionValue + redemptionReceivable)를 사용하고 있는가?
• 정수 연산(Atoms) 정밀도를 유지하고 화면 표시 직전에만 자산 소수점(10^6)으로 나누는가?
• 응답의 quality.status와 quality.reasons를 검사하고, 미완료 필드의 null 값을 임의로 0으로 바꾸지 않고 유지하는가?
• page.hasMore가 false가 될 때까지 page.nextCursor를 따라 페이지네이션을 끝까지 순회하는가?
• 예치 및 출금 시 CooldownVault에 직접 호출하지 않고 반드시 SuperEarnRouter를 거치도록 구현했는가?

​

관련 문서