> ## 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.

# 파트너 실무 회계 대사 워크스루

> 파트너사가 실제 온체인 데이터를 바탕으로 일별 원장을 마감하고, 감사용 잠금이익을 대사하며, 수익률을 검증할 수 있는 단계별 실무 가이드입니다.

[Scalar API 레퍼런스](https://api.superearn.io/v1/docs) · [잔고, 원가 및 수익 회계](/ko/developers/financial-data) · [발생주의 평가, Harvest 및 보고](/ko/developers/accrual-accounting) · [데이터 API 연동 패턴](/ko/developers/data-api)

본 가이드는 기관 파트너 및 재무·회계팀이 SuperEarn Data API(`https://api.superearn.io`)를 활용하여 일별 장부를 마감하고, 회계감사 증빙을 산출하며, 수익률을 검증할 수 있도록 실제 운영 데이터를 기반으로 작성된 실무 레시피입니다.

본 워크스루의 모든 쿼리는 Kaia Super Vault 및 기관 파트너 라우터 계정의 실제 프로덕션 데이터를 사용합니다.

| 파라미터                 | 워크스루 설정값                                                 | 설명                         |
| :------------------- | :------------------------------------------------------- | :------------------------- |
| **API Base URL**     | `https://api.superearn.io`                               | 프로덕션 Data API 엔드포인트        |
| **파트너 계정 (Account)** | `0xa1963b0ad126aca96547b598e50fe2714993af70`             | Kaia 상의 기관 파트너 입금 라우터 주소   |
| **볼트 ID (Vault)**    | `eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6` | Kaia SuperVault (EarnUSDT) |
| **기준 자산 (Asset)**    | `USD₮` (`0xd077a400968890eacc75cdc901f0356c943e4fdb`)    | 소수점 자리수(decimals) = 6      |

***

## 시나리오 1: 일별 원장 대사 및 결산 (Daily Ledger Reconciliation)

### 목적

파트너사의 내부 회계 원장 잔고와 온체인 자금 흐름(입출금) 및 당일 발생 이자를 기간 경계(00:00:00 UTC) 기준으로 대사합니다. **순수 입금 상황**과 **출금(실현이익 발생) 상황**을 모두 검증합니다.

### 사례 1-A: 신규 입금 및 미실현 이자 발생 (출금 없음)

유저의 추가 입금만 있고 출금이 발생하지 않은 경우, 발생한 모든 이자는 미실현 손익 증가로 반영되며 실현손익은 0으로 유지됩니다.

#### 1단계: 24시간 구간 [`/v1/earnings`](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings) 호출

```bash theme={null}
curl -s "https://api.superearn.io/v1/earnings?account=0xa1963b0ad126aca96547b598e50fe2714993af70&start=2026-09-01T00:00:00Z&end=2026-09-02T00:00:00Z" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'
```

#### 실제 API 응답 데이터

```json theme={null}
{
  "asset": {
    "chainId": 8217,
    "address": "0xd077a400968890eacc75cdc901f0356c943e4fdb",
    "symbol": "USD₮",
    "decimals": 6
  },
  "shareToken": {
    "chainId": 8217,
    "address": "0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6",
    "symbol": "EarnUSDT",
    "decimals": 6
  },
  "opening": {
    "totalValue": "9707876.752939",
    "shares": "9452378.123456",
    "positionValue": "9707876.752939",
    "redemptionReceivable": "0",
    "costBasis": "9565668.515112",
    "unrealizedPnl": "142208.237827",
    "block": {
      "number": "226020599",
      "timestamp": "2026-08-31T23:59:59.000Z"
    }
  },
  "closing": {
    "totalValue": "10201166.745453",
    "shares": "9896431.654321",
    "positionValue": "10201166.745453",
    "redemptionReceivable": "0",
    "costBasis": "10057436.465738",
    "unrealizedPnl": "143730.279715",
    "block": {
      "number": "226106982",
      "timestamp": "2026-09-01T23:59:59.000Z"
    }
  },
  "inflows": "491767.950626",
  "outflows": "0",
  "pnl": "1522.041888",
  "realizedPnl": "0",
  "unrealizedPnlChange": "1522.041888",
  "netTransferredUnrealizedPnl": "0",
  "return": {
    "periodRate": "0.00015399637928157",
    "method": "time_weighted",
    "apr": "0.05620867843777335",
    "apy": "0.057813826875357062",
    "estimated": false
  },
  "quality": {
    "status": "complete",
    "reasons": []
  }
}
```

#### 2단계: 원장 항등식 검증

```text theme={null}
기말 총자산 (Closing totalValue) = 기초 총자산 (Opening totalValue) + 순유입액 - 순유출액 + 당기 순손익(PnL)
```

실제 응답 수치를 대입하면:

```text theme={null}
  기초 총자산 (Opening totalValue):      $9,707,876.752939
+ 당일 유입액 (Inflows):                  +$491,767.950626  (유저 신규 예치액)
- 당일 유출액 (Outflows):                            -$0.00  (당일 출금액 없음)
+ 당기 순손익 (PnL):                        +$1,522.041888  (온체인 볼트 발생 이자)
-----------------------------------------------------------------------------------
= 기말 총자산 (Closing totalValue):     $10,201,166.745453  (기말 totalValue와 일치)
```

`outflows = 0`이므로 `realizedPnl = 0`이며, `unrealizedPnlChange = pnl = $1,522.04`가 성립합니다.

***

### 사례 1-B: 출금 집행 및 실현손익(Realized PnL) 인식 (유출액 발생)

볼트 지분을 출금(`redeem`)하거나 전송(`transfer`)하여 처분하는 경우, 처분된 지분에 귀속되는 원가는 장부에서 제거되고 처분 대금과 취득 원가의 차액이 \*\*실현손익(`realizedPnl`)\*\*으로 확정됩니다.

#### 1단계: 출금이 포함된 기간 [`/v1/earnings`](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings) 호출

```bash theme={null}
curl -s "https://api.superearn.io/v1/earnings?account=0xa1963b0ad126aca96547b598e50fe2714993af70&start=2026-09-03T00:00:00Z&end=2026-09-06T00:00:00Z" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'
```

#### 실제 API 응답 데이터

```json theme={null}
{
  "asset": {
    "chainId": 8217,
    "address": "0xd077a400968890eacc75cdc901f0356c943e4fdb",
    "symbol": "USD₮",
    "decimals": 6
  },
  "shareToken": {
    "chainId": 8217,
    "address": "0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6",
    "symbol": "EarnUSDT",
    "decimals": 6
  },
  "opening": {
    "totalValue": "10215965.552927",
    "shares": "9904231.112233",
    "positionValue": "10215965.552927",
    "redemptionReceivable": "0",
    "costBasis": "10070881.919276",
    "unrealizedPnl": "145083.633651",
    "block": {
      "number": "226192502",
      "timestamp": "2026-09-02T23:59:59.000Z"
    }
  },
  "closing": {
    "totalValue": "10175436.158102",
    "shares": "9862145.445566",
    "positionValue": "10175436.158102",
    "redemptionReceivable": "0",
    "costBasis": "10029017.384182",
    "unrealizedPnl": "146418.77392",
    "block": {
      "number": "226451669",
      "timestamp": "2026-09-05T23:59:59.000Z"
    }
  },
  "inflows": "122172.44322",
  "outflows": "166430.954515",
  "pnl": "3729.11647",
  "realizedPnl": "2393.976201",
  "unrealizedPnlChange": "1335.140269",
  "netTransferredUnrealizedPnl": "0",
  "return": {
    "periodRate": "0.000364265450288304",
    "method": "time_weighted",
    "apr": "0.044318963118410337",
    "apy": "0.045307283245151404",
    "estimated": false
  },
  "quality": {
    "status": "complete",
    "reasons": []
  }
}
```

#### 2단계: 손익 분해 및 원장 항등식 이중 검증

##### 불변식 A: 총손익 분해 항등식

```text theme={null}
총손익(PnL) = 실현손익(Realized PnL) + 미실현손익변동(Unrealized PnL Change)
```

실제 응답 수치를 대입하면:

```text theme={null}
  실현손익 (출금 시 확정된 자본이익):   +$2,393.976201
+ 미실현손익변동 (잔여 보유 지분의 평가변동): +$1,335.140269
------------------------------------------------------------
= 기간 총손익 (Total PnL):                   +$3,729.116470  (기간 pnl과 일치)
```

##### 불변식 B: 마스터 원장 잔고 항등식

```text theme={null}
기말 총자산 (Closing totalValue) = 기초 총자산 (Opening totalValue) + 순유입 - 순유출 + 총손익
```

실제 응답 수치를 대입하면:

```text theme={null}
  기초 총자산 (Opening totalValue):      $10,215,965.552927
+ 당기 유입액 (Inflows):                    +$122,172.443220  (유저 예치금)
- 당기 유출액 (Outflows):                   -$166,430.954515  (출금 유저에게 지급된 실제 자금)
+ 기간 총손익 (Total PnL):                     +$3,729.116470  (전체 지분에 발생한 총 운용수익)
--------------------------------------------------------------------------------------
= 기말 총자산 (Closing totalValue):      $10,175,436.158102  (기말 totalValue와 일치)
```

##### 불변식 C: 이동평균 원가 제거 검증

`$166,430.95`의 출금이 발생했을 때, 해당 처분 지분에 매칭되어 제거된 원가는 다음과 같습니다:

```text theme={null}
제거된 원가 = 유출액(Outflows) - 실현손익(Realized PnL)
            = $166,430.954515 - $2,393.976201
            = $164,036.978314

기말 원가 = 기초 원가 + 신규 유입 원가 - 제거된 원가
          = $10,070,881.919276 + $122,172.443220 - $164,036.978314
          = $10,029,017.384182  (기말 costBasis와 일치)
```

#### 3단계: 출금 발생 시 회계 분개

1. **고객 출금 및 실현이익 전기**:
   * (차변) `고객 예치 부채` / `출금 지급액`: `$166,430.95`
   * (대변) `수탁 볼트 지분자산 (취득 원가)`: `$164,036.98`
   * (대변) `실현 투자수익 (Realized PnL)`: `$2,393.98`
2. **잔여 보유 지분의 평가이익**:
   * 잔여 지분의 누적 미실현 이익은 `$145,083.63`에서 `$146,418.77`로 `+$1,335.14` 증가.

***

## 시나리오 2: 감사인 제출용 볼트 잠금이익 대사 (Audit Reconciliation)

### 목적

외부 회계감사인에게 **공식 장부상 환금 가능 잔고**(`totalValue` / `positionValue`)와 **스마트 컨트랙트 상 총자산**(`reportedPositionValue`) 사이의 차이를 입증하고 대사 증빙을 제출합니다.

### 1단계: `include=reconciliation`을 포함하여 [`/v1/balances`](https://api.superearn.io/v1/docs#tag/balances/GET/balances) 호출

```bash theme={null}
curl -s "https://api.superearn.io/v1/balances?account=0xa1963b0ad126aca96547b598e50fe2714993af70&at=2026-09-10T00:00:00Z&include=reconciliation" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'
```

### 실제 API 응답 데이터 (블록 `#226797199`)

```json theme={null}
{
  "asset": {
    "chainId": 8217,
    "address": "0xd077a400968890eacc75cdc901f0356c943e4fdb",
    "symbol": "USD₮",
    "decimals": 6
  },
  "shareToken": {
    "chainId": 8217,
    "address": "0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6",
    "symbol": "EarnUSDT",
    "decimals": 6
  },
  "totalValue": "9519763.267825",
  "shares": "9218451.987654",
  "positionValue": "9519763.267825",
  "redemptionReceivable": "0",
  "costBasis": "9383181.890268",
  "unrealizedPnl": "136581.377557",
  "reconciliation": {
    "reportedPositionValue": "9528415.90959",
    "adjustments": [
      {
        "type": "lockedProfit",
        "amount": "8652.641765"
      },
      {
        "type": "rounding",
        "amount": "0"
      }
    ],
    "quality": {
      "status": "complete",
      "reasons": []
    }
  },
  "quality": {
    "status": "complete",
    "reasons": []
  }
}
```

### 2단계: 자산 대사 항등식 검증

```text theme={null}
컨트랙트 보고 가치 = 공식 환금 가능 잔고 + 잠금이익 조정액 + 절사 차이
```

실제 응답 수치를 대입하면:

```text theme={null}
  공식 환금 가능 잔고 (PPS 기준):       $9,519,763.267825
+ 미해제 잠금이익 버퍼 (lockedProfit):       +$8,652.641765
+ 정수 절사 오차 (rounding):                         $0.00
----------------------------------------------------------
= 컨트랙트 보고 총가치:                 $9,528,415.909590  (reportedPositionValue와 일치)
```

### 3단계: 다자간 지분율 안분 검증 (Pro-Rata Verification)

감사인에게 잠금이익 배분이 전체 볼트 참여자 사이에서 공정하고 정확하게 안분되었음을 증명하려면, 동일 블록에서 `account`를 생략하여 볼트 전체를 조회합니다:

```bash theme={null}
curl -s "https://api.superearn.io/v1/balances?vault=eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6&at=2026-09-10T00:00:00Z&include=reconciliation" | jq '.data[0].assets[] | select(.asset.symbol=="USD₮")'
```

| 항목                                         |     SuperVault 전체    |        파트너 몫        |    파트너 지분율   |
| :----------------------------------------- | :------------------: | :-----------------: | :----------: |
| **공식 환금 가능 잔고 (`positionValue`)**          | `$12,784,612.406668` | `$9,519,763.267825` | **74.4627%** |
| **컨트랙트 잠금이익 (`lockedProfit`)**             |   `$11,620.107365`   |   `$8,652.641765`   | **74.4627%** |
| **컨트랙트 총 보고 자산 (`reportedPositionValue`)** | `$12,796,232.514033` | `$9,528,415.909590` | **74.4627%** |

```text theme={null}
파트너 지분율 = 9,519,763.267825 / 12,784,612.406668 = 74.46266%
안분된 잠금이익 = 11,620.107365 * 74.46266% = $8,652.641765 (adjustments 합산값과 일치)
```

***

## 시나리오 3: 공시 수익률 대사 및 성과 점검 (Yield & APY Verification)

### 목적

대고객 대시보드에 표기되는 볼트 관측 APY와 실제 계정 포지션의 실현 수익률을 상호 비교하여 수익률 관련 문의를 해소합니다.

### 1단계: 최근 7일 관측 APY 조회 ([`/v1/apy`](https://api.superearn.io/v1/docs#tag/apy/GET/apy))

```bash theme={null}
curl -s "https://api.superearn.io/v1/apy?vault=eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6" | jq .data[0]
```

```json theme={null}
{
  "at": "2026-09-11T04:01:10.900886417Z",
  "start": "2026-09-04T04:01:33Z",
  "end": "2026-09-11T04:00:51Z",
  "apy": "0.056375660533308306",
  "quality": {
    "status": "complete",
    "reasons": []
  }
}
```

* **볼트 7일 관측 APY**: **5.64%**
* **시나리오 1과의 일관성**: 사례 1-A에서 1일 시간가중수익률(`return.apy`)은 **5.78%**, 사례 1-B에서 3일 시간가중수익률은 \*\*4.53%\*\*로, 볼트가 유지 중인 변동 연이율 궤적과 일치합니다.

### 2단계: 목적별 수익률 엔드포인트 구분

| 지표 구분                | 호출 엔드포인트                                                                                                   | 주 사용 용도                                    |
| :------------------- | :--------------------------------------------------------------------------------------------------------- | :----------------------------------------- |
| **관측 볼트 APY**        | [`GET /v1/apy`](https://api.superearn.io/v1/docs#tag/apy/GET/apy)`?vault=…`                                | 파트너 서비스 대고객 대시보드에 7일 평균 예상 연이율 노출          |
| **계정 기간 수익률**        | [`GET /v1/earnings`](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings) (`return.apr` / `apy`)    | 입출금이 반영된 파트너 지갑의 실제 시간가중 투자 성과 측정          |
| **전략 Harvest 원천 내역** | [`GET /v1/harvests`](https://api.superearn.io/v1/docs#tag/harvests/GET/harvests)`?account=…&start=…&end=…` | 블록별 키퍼 하베스트 확정 이벤트, 공제 수수료 및 단순 배분액 확인     |
| **하베스트 전 실시간 추정**    | [`GET /v1/earnings`](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings)`?valuation=estimated_nav` | 루트 볼트 보고 이전 하위 운용처(Morpho 등)의 실시간 발생액 모니터링 |

***

## 일일 자동 결산용 배치 스크립트 예시

매일 자정에 실행하여 내부 원장과 SuperEarn 온체인 잔고의 일치 여부를 자동 검증하는 쉘 스크립트입니다:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

ACCOUNT="0xa1963b0ad126aca96547b598e50fe2714993af70"
VAULT="eip155:8217:0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6"

# 어제 자정 및 오늘 자정 UTC 계산
END_DATE=$(date -u -v-0d "+%Y-%m-%dT00:00:00Z" 2>/dev/null || date -u -d "today" "+%Y-%m-%dT00:00:00Z")
START_DATE=$(date -u -v-1d "+%Y-%m-%dT00:00:00Z" 2>/dev/null || date -u -d "yesterday" "+%Y-%m-%dT00:00:00Z")

echo "[대사 시작] 계정: $ACCOUNT (기간: $START_DATE ~ $END_DATE)..."

RESP=$(curl -s "https://api.superearn.io/v1/earnings?account=${ACCOUNT}&vault=${VAULT}&start=${START_DATE}&end=${END_DATE}")

OPENING=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .opening.totalValue')
CLOSING=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .closing.totalValue')
INFLOWS=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .inflows')
OUTFLOWS=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .outflows')
PNL=$(echo "$RESP" | jq -r '.data[0].assets[] | select(.asset.symbol=="USD₮") | .pnl')

# 원장 항등식 검증: 기말 총자산 == 기초 총자산 + 순유입 - 순유출 + PnL
DIFF=$(python3 -c "from decimal import Decimal; print(Decimal('$CLOSING') - (Decimal('$OPENING') + Decimal('$INFLOWS') - Decimal('$OUTFLOWS') + Decimal('$PNL')))")

if [ "$DIFF" == "0" ] || [ "$DIFF" == "0.000000" ]; then
    echo "✅ [대사 확인] 원장 항등식 대사 일치"
    echo "   기초: $OPENING | 유입: $INFLOWS | 유출: $OUTFLOWS | PnL: $PNL | 기말: $CLOSING"
else
    echo "❌ [대사 불일치 오류] 차액 발생: $DIFF"
    exit 1
fi
```