> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superearn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data API 활용 패턴

> 볼트 탐색, 포트폴리오 화면, 활동 피드 및 출금 생애주기 추적 구현.

[Scalar API 레퍼런스](https://api.superearn.io/v1/docs) · [보고 TL;DR: 보유 잔고·원가·손익·수익률](/ko/developers/financial-data#tldr) · [데이터 API 개요](/ko/developers/data-access)

본 문서는 SuperEarn Data API를 활용하여 애플리케이션, 클라이언트 대시보드 및 지갑 인터페이스를 구축할 때 필요한 표준 연동 패턴을 안내합니다.

기관 파트너 회계, IFRS 기준 재무제표 작성 및 감사 검산 체계는 [잔고, 원가 및 수익 회계](/ko/developers/financial-data) 문서를 참고하십시오.

## 용도별 연동 패턴

| 사용 사례           | API 호출 순서                                                                                                                                                                                                                                                     | 결과                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| **상품 목록 및 수익률** | [vaults](https://api.superearn.io/v1/docs#tag/vaults/GET/vaults) → [vault](https://api.superearn.io/v1/docs#tag/vaults/GET/vaults/\{vault}) → [apy](https://api.superearn.io/v1/docs#tag/apy/GET/apy)                                                         | 활성 볼트 목록, 자산 메타데이터, 최근 7일 관측 APY          |
| **지갑 포트폴리오**    | [vaults](https://api.superearn.io/v1/docs#tag/vaults/GET/vaults) → [balances](https://api.superearn.io/v1/docs#tag/balances/GET/balances)                                                                                                                     | 활성 운용 자산 평가액, 잔여 취득원가, 미실현손익, 출금 대기금      |
| **활동 내역 피드**    | [activity](https://api.superearn.io/v1/docs#tag/accounts/GET/accounts/\{account}/activity)                                                                                                                                                                    | 입금, 출금 요청, 지분 이전, 청구 지급 내역 타임라인           |
| **출금 생애주기 추적**  | [redemptions](https://api.superearn.io/v1/docs#tag/accounts/GET/accounts/\{account}/redemptions) + [liquidity](https://api.superearn.io/v1/docs#tag/allocations/GET/vaults/\{vault}/liquidity)                                                                | 출금 신청 진행 단계, 쿨다운 타이머, 청구 가능 여부, 볼트 가용 유동성 |
| **투자 자산 배분 구조** | [manifest](https://api.superearn.io/v1/docs#tag/catalog/GET/manifest) → [graph](https://api.superearn.io/v1/docs#tag/allocations/GET/vaults/\{vault}/graph) + [allocations](https://api.superearn.io/v1/docs#tag/allocations/GET/vaults/\{vault}/allocations) | 하위 전략 익스포저, 프로토콜 부채 현황 및 운용처별 비중          |
| **기관 회계 결산**    | [earnings](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings)                                                                                                                                                                                        | 기간 기초·기말 잔고, 자금 유출입, 실현·미실현 손익, TWR 수익률   |

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

```bash theme={null}
# 활성 볼트 목록 조회 예시
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% 온전히 보존되며, 추가 이자 발생이 중단된 확정 채권입니다.
   * **총 평가 자산 항등식**:
     ```text theme={null}
     총 관리 자산 (totalValue) = 활성 운용 지분 가치 (positionValue) + 출금 대기금 (redemptionReceivable)
     ```
3. **투자 원금 및 미실현 손익 표시**:
   * `costBasis`: 이동평균원가법으로 계산된 장부상 잔여 순투자원금 (`[Unit: asset]`).
   * `unrealizedPnl`: `positionValue - costBasis`로 산출되는 미실현 평가손익 (`[Unit: asset]`).
4. **품질 상태 확인**: `quality.status`를 점검합니다. 과거 취득 시점 온체인 데이터가 인덱싱 중인 경우 `costBasis` 및 `unrealizedPnl`이 `null`로 반환될 수 있습니다. 이 경우 0으로 대체하지 말고 `null` 상태를 유지하십시오.

정확한 지분 가치 평가 및 정수 내림 수식은 [경계 평가 수식](/ko/developers/financial-data#경계-평가)을 참조하십시오.

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

SuperEarn의 출금은 안정적인 유동성 관리를 위해 CooldownVault를 통한 2단계(신청 및 수령) 메커니즘을 따릅니다:

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

| 단계            | 발생 조건                               | API 상태값                              | 클라이언트 권장 처리                                           |
| ------------- | ----------------------------------- | ------------------------------------ | ----------------------------------------------------- |
| **1. 출금 신청**  | 사용자가 `SuperEarnRouter`의 `redeem` 호출 | 트랜잭션 확정                              | 반환된 `requestId` 저장                                    |
| **2. 쿨다운 대기** | CooldownVault 큐에 대기열 등록             | `redemptions[].status = "pending"`   | 잔여 쿨다운 타이머 및 카운트다운 표시                                 |
| **3. 수령 가능**  | 쿨다운 시간 만료 (`cooldownEnd <= now`)    | `redemptions[].status = "claimable"` | 볼트 가용 유동성(`/allocations/.../liquidity`) 확인 후 claim 유도 |
| **4. 지급 완료**  | 키퍼 또는 사용자가 `claim` 실행               | `redemptions[].status = "claimed"`   | `redemptionReceivable`에서 차감하고 지갑 현금 잔고로 전환            |

**핵심 운영 원칙**

* **쿨다운 기간 중 이자 미발생**: 출금 신청이 온체인에 등록되면 소각된 지분은 더 이상 볼트 주당순자산가치(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`를 거치도록 구현했는가?

## 관련 문서

| 문서                                                         | 설명                                              |
| ---------------------------------------------------------- | ----------------------------------------------- |
| [데이터 API 개요](/ko/developers/data-access)                   | 기본 URL, 연동 경로, 토큰 단위 및 운영 환경                    |
| [잔고, 원가 및 수익 회계](/ko/developers/financial-data)            | 4대 회계 불변식, 이동평균 원가법, 손익 인식 및 수익률 산출 공식          |
| [발생주의 평가, Harvest 및 보고](/ko/developers/accrual-accounting) | 볼트 lockedProfit 버퍼 메커니즘, 전략 NAV 추정 및 Harvest 배분 |
| [Scalar API 레퍼런스](https://api.superearn.io/v1/docs)        | 전체 엔드포인트 대화형 명세서                                |