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

# 토큰 분석 프레임워크

> 펀더멘털부터 온체인 지표까지, 체계적인 토큰 분석 방법론

본 문서에서는 ChainStream을 활용한 포괄적인 토큰 분석 프레임워크를 소개합니다. 기본 데이터, 온체인 지표, 홀더 분석, 리스크 평가를 다룹니다.

***

## 프레임워크 개요

<CardGroup cols={4}>
  <Card title="기본 정보" icon="circle-info">
    이름/심볼, 소수점 자릿수, 컨트랙트 주소, 생성 시간
  </Card>

  <Card title="시장 데이터" icon="chart-line">
    가격, 시가총액, 유동성, 거래량
  </Card>

  <Card title="홀더 분석" icon="users">
    홀더 수, 상위 10/100 보유 비율, 생성자 보유량
  </Card>

  <Card title="거래 통계" icon="arrow-right-arrow-left">
    매수/매도 횟수, 거래량, 가격 변동
  </Card>
</CardGroup>

***

## 1. 기본 정보

### API 엔드포인트

```bash theme={null}
GET /v2/token/{chain}/{tokenAddress}
```

### 핵심 필드

| 필드               | 타입      | 설명                       |
| ---------------- | ------- | ------------------------ |
| `chain`          | string  | 블록체인 네트워크 식별자 (예: `sol`) |
| `name`           | string  | 토큰 이름                    |
| `symbol`         | string  | 토큰 심볼                    |
| `decimals`       | integer | 토큰 소수점 자릿수               |
| `address`        | string  | 토큰 민트 주소                 |
| `imageUrl`       | string  | 토큰 이미지 URL               |
| `tokenCreatedAt` | integer | 토큰 생성 타임스탬프 (밀리초)        |
| `description`    | string  | 토큰 설명                    |
| `tokenCreators`  | array   | 토큰 생성자 주소 목록             |

### 응답 예시

```json theme={null}
{
  "chain": "sol",
  "name": "USD Coin",
  "symbol": "USDC",
  "decimals": 9,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "imageUrl": "https://raw.githubusercontent.com/.../logo.png",
  "tokenCreatedAt": 1710417600000,
  "description": "USDC is a stablecoin pegged to the US dollar",
  "tokenCreators": [
    {
      "address": "...",
      "share": 100
    }
  ]
}
```

***

## 2. 시장 데이터

시장 데이터는 토큰 상세 엔드포인트의 `marketData` 필드에 포함되어 있습니다.

### 가격 및 시가총액

| 필드               | 타입     | 설명            |
| ---------------- | ------ | ------------- |
| `priceInUsd`     | string | 토큰 가격 (USD)   |
| `priceInSol`     | string | 토큰 가격 (SOL)   |
| `marketCapInUsd` | string | 유통 시가총액 (USD) |
| `marketCapInSol` | string | 유통 시가총액 (SOL) |
| `totalSupply`    | string | 총 공급량         |

### 유동성 지표

| 필드                | 타입     | 설명                | 건전성 기준           |
| ----------------- | ------ | ----------------- | ---------------- |
| `maxPoolTvlInUsd` | string | 최대 풀 TVL (USD)    | 깊이가 클수록 슬리피지가 작음 |
| `totalTvlInUsd`   | string | 전체 풀 합계 TVL (USD) | > 시가총액의 5%       |
| `maxPoolTvlInSol` | string | 최대 풀 TVL (SOL)    | -                |
| `totalTvlInSol`   | string | 전체 풀 합계 TVL (SOL) | -                |

### 홀더 개요

| 필드                    | 타입     | 설명           | 건전성 기준       |
| --------------------- | ------ | ------------ | ------------ |
| `holders`             | string | 전체 토큰 홀더 수   | 많을수록 분산됨     |
| `top10HoldingsRatio`  | string | 상위 10 홀더 비율  | \< 0.5 (50%) |
| `top10TotalHoldings`  | string | 상위 10 보유 총량  | -            |
| `top100HoldingsRatio` | string | 상위 100 홀더 비율 | \< 0.7 (70%) |
| `top100TotalHoldings` | string | 상위 100 보유 총량 | -            |

### 응답 예시

```json theme={null}
{
  "marketData": {
    "priceInUsd": "0.00123456",
    "priceInSol": "0.0000089",
    "marketCapInUsd": "1234567.89",
    "totalSupply": "1000000000",
    "holders": "5432",
    "top10HoldingsRatio": "0.35",
    "top100HoldingsRatio": "0.58",
    "maxPoolTvlInUsd": "50000.00",
    "totalTvlInUsd": "85000.00"
  }
}
```

***

## 3. 거래 통계

거래 통계는 토큰 상세 엔드포인트의 `stats` 필드에 포함되어 있거나, 전용 엔드포인트에서 가져올 수 있습니다.

### API 엔드포인트

```bash theme={null}
GET /v2/token/{chain}/{tokenAddress}/stats
```

### 통계 필드 (기간별)

지원 기간: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `24h`

| 필드 패턴                           | 설명           | 필드 예시                           |
| ------------------------------- | ------------ | ------------------------------- |
| `price{period}`                 | 기간 내 가격      | `price1m`, `price5m`, `price1h` |
| `buys{period}`                  | 기간 내 매수 횟수   | `buys1m`, `buys5m`, `buys1h`    |
| `sells{period}`                 | 기간 내 매도 횟수   | `sells1m`, `sells5m`, `sells1h` |
| `buyVolumesInUsd{period}`       | 매수 거래량 (USD) | `buyVolumesInUsd1m`             |
| `sellVolumesInUsd{period}`      | 매도 거래량 (USD) | `sellVolumesInUsd1m`            |
| `volumesInUsd{period}`          | 총 거래량 (USD)  | `volumesInUsd1m`                |
| `priceChangeRatioInUsd{period}` | 가격 변동률       | `priceChangeRatioInUsd1h`       |

### 응답 예시

```json theme={null}
{
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "price1m": "1.234",
  "buys1m": "150",
  "sells1m": "120",
  "buyVolumesInUsd1m": "50000.45",
  "sellVolumesInUsd1m": "45000.32",
  "volumesInUsd1m": "95000.77",
  "buys1h": "2500",
  "sells1h": "2100",
  "volumesInUsd1h": "1500000.00",
  "priceChangeRatioInUsd1h": "0.025"
}
```

***

## 4. 홀더 분석

### API 엔드포인트

```bash theme={null}
GET /v2/token/{chain}/{tokenAddress}/holders
```

### 쿼리 파라미터

| 파라미터        | 타입     | 필수  | 설명                           |
| ----------- | ------ | --- | ---------------------------- |
| `cursor`    | string | 아니오 | 페이지네이션 커서                    |
| `limit`     | number | 아니오 | 페이지당 결과 수 (1-100, 기본값 20)    |
| `direction` | string | 아니오 | 페이지네이션 방향 (`next` 또는 `prev`) |

### 홀더 필드

| 필드              | 타입     | 설명          |
| --------------- | ------ | ----------- |
| `walletAddress` | string | 지갑 주소       |
| `amount`        | string | 보유량         |
| `amountInUsd`   | string | 보유 가치 (USD) |
| `percentage`    | string | 보유 비율       |

### 응답 예시

```json theme={null}
{
  "hasNext": true,
  "hasPrev": false,
  "startCursor": "abc123",
  "endCursor": "xyz789",
  "data": [
    {
      "walletAddress": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
      "amount": "1000000000000000000",
      "amountInUsd": "12345.67",
      "percentage": "10.5"
    }
  ]
}
```

### 홀더 분포 평가

<Tabs>
  <Tab title="건전한 분포">
    **특징**:

    * 상위 10 비율 \< 50%
    * 상위 100 비율 \< 70%
    * 홀더 수가 많음
    * 고르게 분산, 탈중앙화됨

    **리스크 레벨**: 🟢 저위험
  </Tab>

  <Tab title="위험한 분포">
    **특징**:

    * 상위 10 비율 > 80%
    * 소수 주소가 대부분의 공급량을 지배
    * 홀더 수가 적음
    * 고도로 집중, 조작 위험

    **리스크 레벨**: 🔴 고위험
  </Tab>
</Tabs>

### 홀더 유형 식별

| 유형         | 식별 방법                         | 중요성     |
| ---------- | ----------------------------- | ------- |
| **팀/프로젝트** | 컨트랙트 배포자, `tokenCreators`의 주소 | 언락 리스크  |
| **고래**     | 보유량 > 1%                      | 시장 영향력  |
| **스마트 머니** | 높은 승률의 트레이더 (지갑 분석 필요)        | 정보 우위   |
| **CEX**    | 거래소 핫월렛                       | 유동성 공급원 |

***

## 5. 리스크 평가

### 리스크 평가 차원

| 차원            | 가중치 | 지표                                          |
| ------------- | --- | ------------------------------------------- |
| **집중 리스크**    | 30% | `top10HoldingsRatio`, `top100HoldingsRatio` |
| **유동성 리스크**   | 25% | `totalTvlInUsd`, TVL/시가총액 비율                |
| **신규 토큰 리스크** | 20% | `tokenCreatedAt` (생성 시간)                    |
| **거래 활성도**    | 15% | `holders`, 거래량, 매수/매도 횟수                    |
| **생성자 보유량**   | 10% | 생성자 주소 보유 비율                                |

### 리스크 지표

| 지표     | 레벨 | 트리거 조건                                                    |
| ------ | -- | --------------------------------------------------------- |
| 🔴 고위험 | 위험 | `top10HoldingsRatio` > 0.8, TVL \< 시가총액의 1%, 생성 후 24시간 미만 |
| 🟡 중위험 | 경고 | `top10HoldingsRatio` > 0.5, 생성 후 7일 미만                    |
| 🟢 저위험 | 안전 | 모든 지표가 건전                                                 |

***

## 분석 워크플로우

<Steps>
  <Step title="기본 정보 조회">
    `GET /v2/token/{chain}/{tokenAddress}`를 호출하여 완전한 토큰 정보 조회

    * 컨트랙트 주소 확인
    * 생성 시간 `tokenCreatedAt` 확인
  </Step>

  <Step title="시장 데이터 분석">
    `marketData` 필드 확인

    * 현재 가격 `priceInUsd`
    * 시가총액 `marketCapInUsd`
    * 유동성 `totalTvlInUsd`
  </Step>

  <Step title="홀더 분포 평가">
    `marketData` 내 홀더 데이터 확인

    * 홀더 수 `holders`
    * 상위 10 비율 `top10HoldingsRatio`
    * 상위 100 비율 `top100HoldingsRatio`
  </Step>

  <Step title="거래 활성도 확인">
    `stats` 필드 확인

    * 거래량 `volumesInUsd1h`, `volumesInUsd24h`
    * 매수/매도 비율 `buys1h` vs `sells1h`
  </Step>

  <Step title="종합 리스크 평가">
    위 데이터를 기반으로 리스크 레벨 산출

    * 높은 집중도 + 낮은 유동성 = 🔴 고위험
    * 건전한 분포 + 충분한 유동성 = 🟢 저위험
  </Step>
</Steps>

***

## 실전 예시

### 예시: 신규 상장 토큰 분석

```typescript theme={null}
import { ChainStreamClient } from '@chainstream-io/sdk';

const client = new ChainStreamClient('YOUR_ACCESS_TOKEN');

async function analyzeToken(chain: string, tokenAddress: string) {
  // 1. 완전한 토큰 정보 조회
  const token = await client.token.getToken(chain, tokenAddress);
  
  // 2. 생성 시간 확인
  const ageInDays = (Date.now() - token.tokenCreatedAt) / (1000 * 60 * 60 * 24);
  if (ageInDays < 7) {
    console.warn('⚠️ 신규 토큰 리스크: 생성 후 7일 미만');
  }
  
  // 3. 홀더 분포 분석
  const top10Ratio = parseFloat(token.marketData.top10HoldingsRatio);
  if (top10Ratio > 0.5) {
    console.warn('⚠️ 집중 리스크: 상위 10이 50% 이상 보유');
  }
  
  // 4. 유동성 확인
  const tvl = parseFloat(token.marketData.totalTvlInUsd);
  const marketCap = parseFloat(token.marketData.marketCapInUsd);
  if (tvl < marketCap * 0.05) {
    console.warn('⚠️ 유동성 리스크: TVL이 시가총액의 5% 미만');
  }
  
  // 5. 종합 평가
  const riskLevel = calculateRiskLevel(token);
  console.log(`리스크 레벨: ${riskLevel}`);
  
  return {
    token,
    ageInDays,
    top10Ratio,
    tvlRatio: tvl / marketCap,
    riskLevel
  };
}

function calculateRiskLevel(token: any): string {
  const top10Ratio = parseFloat(token.marketData.top10HoldingsRatio);
  const tvl = parseFloat(token.marketData.totalTvlInUsd);
  const marketCap = parseFloat(token.marketData.marketCapInUsd);
  
  if (top10Ratio > 0.8 || tvl < marketCap * 0.01) {
    return '🔴 고위험';
  } else if (top10Ratio > 0.5) {
    return '🟡 중위험';
  }
  return '🟢 저위험';
}
```

***

## API 엔드포인트 요약

| 분석 요구사항               | API 엔드포인트                                         |
| --------------------- | ------------------------------------------------- |
| 토큰 상세 (시장 데이터, 통계 포함) | `GET /v2/token/{chain}/{tokenAddress}`            |
| 토큰 메타데이터              | `GET /v2/token/{chain}/{tokenAddress}/metadata`   |
| 토큰 통계                 | `GET /v2/token/{chain}/{tokenAddress}/stats`      |
| 홀더 목록                 | `GET /v2/token/{chain}/{tokenAddress}/holders`    |
| 상위 홀더                 | `GET /v2/token/{chain}/{tokenAddress}/topholders` |
| 토큰 풀                  | `GET /v2/token/{chain}/{tokenAddress}/pools`      |
| 토큰 시장 데이터             | `GET /v2/token/{chain}/{tokenAddress}/marketdata` |

***

## 관련 문서

<CardGroup cols={2}>
  <Card title="스마트 머니 분석 방법론" icon="brain" href="/ko/docs/data-products/smart-money">
    스마트 머니 분석에 대해 알아보기
  </Card>

  <Card title="MCP 도구 카탈로그" icon="wrench" href="/ko/docs/ai-agents/mcp-server/tools">
    MCP 도구 전체 목록 확인
  </Card>
</CardGroup>