Hyperliquid Wallet Scoring System

AI 기반 트레이더 분석 및 자동 매매 플랫폼

---

프로젝트 소개

Hyperliquid 리더보드의 단순 PnL 순위를 넘어, AI Agent가 트레이더의 실력과 리스크 프로파일을 분석하여 보다 정확한 평가를 제공하는 시스템입니다.

주요 기능

• 다차원 지갑 분석: ROI, MDD, CAGR, Calmar Ratio 등 6가지 메트릭으로 트레이더 평가
• AI Agent 분석: SpoonOS LLM을 활용한 트레이딩 스타일 분석 및 평가
• 자동 매매 시스템: LLM 기반 거래 결정 및 x402 결제 프로토콜을 통한 API 접근 제어
• 실시간 데이터: 5분 캐싱 시스템으로 효율적인 데이터 제공
• 텔레그램 연동: 거래 결과 및 분석 리포트 자동 전송

---

시스템 아키텍처

┌─────────────┐
│   Frontend  │
└──────┬──────┘
       │ REST API
┌──────▼────────────────────────────────────┐
│         FastAPI Backend                   │
│  ┌────────────────────────────────────┐  │
│  │  /api/data                         │  │
│  │  /api/information/{wallet_id}      │  │
│  │  /api/trade/auto/ai                │  │
│  └────────────────────────────────────┘  │
│           │         │          │         │
│      ClickHouse  SpoonOS   Telegram      │
│      Database    LLM        Bot          │
└──────────────────────────────────────────┘

---

기술 스택

Backend

• FastAPI: 고성능 비동기 API 서버
• ClickHouse: 대용량 분석 데이터 저장
• SpoonOS LLM: AI 기반 트레이더 분석 및 거래 결정
• Spoon-toolkit: 크립토 데이터 조회
• x402 Payment Protocol: API 접근 제어 (결제 시뮬레이션)
• Python Telegram Bot: 알림 서비스

주요 라이브러리

• clickhouse-driver: ClickHouse 데이터베이스 연결
• eth-account: 이더리움 서명 생성/검증 (x402)
• httpx: 내부 API 호출
• python-telegram-bot: 텔레그램 봇 통신

---

API 문서

GET /api/data

지갑 데이터 목록 조회

특징:

• 5분 캐싱: 최근 5분 이내 데이터는 캐시에서 즉시 반환
• 자동 갱신: 캐시 만료 시 ClickHouse에서 새로 조회
• 상위/하위 5개: weighted_score 기준 상위 5개와 하위 5개 반환

응답 예시:

[
    {
        "wallet_id": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
        "rank": 1,
        "equityCurve": [
            { "date": "2024-01-01", "balance": 10000 },
            { "date": "2024-01-02", "balance": 10500 }
        ],
        "roi": 150.5,
        "mdd": -25.3,
        "cagr": 200.0,
        "calmar_ratio": 7.9,
        "ave_drawdown": -5.2,
        "recovery_factor": 5.9,
        "weighted_score": 86.67,
        "AI_Assistant": "Exceptional risk-adjusted performance..."
    }
]

GET /api/information/{wallet_id}

특정 지갑의 상세 정보 조회

응답 포함:

• Equity Curve (일별 잔액 히스토리)
• 6가지 메트릭 (ROI, MDD, CAGR, Calmar Ratio, Avg Drawdown, Recovery Factor)
• AI Agent 분석 텍스트
• 유사 고래 프로필 (3개, matchScore 기준 정렬)

응답 예시:

{
  "wallet_id": "0x31ca8395cf837de08b24da3f660e77761dfb974b",
  "equityCurve": [...],
  "roi": 80.0,
  "mdd": 100.0,
  "cagr": 60.0,
  "calmar_ratio": 100.0,
  "ave_drawdown": 100.0,
  "recovery_factor": 80.0,
  "weighted_score": 86.67,
  "AI_Assistant": "Exceptional risk-adjusted performance...",
  "similar_whale_profiles": [
    {
      "wallet_id": "0x...",
      "matchScore": 85,
      "pnl": 1000000
    }
  ]
}

POST /api/trade/auto/ai

AI 에이전트 기반 자동 매매 실행

동작 흐름:

1. x402 결제 요구사항 생성 및 검증
2. SpoonOS LLM을 통한 매매 결정 생성
3. Spoon-toolkit으로 크립토 데이터 조회
4. Paper trade 실행 (시뮬레이션)
5. 텔레그램으로 결과 전송

요청:

Headers:
  X-PAYMENT-SIGNATURE: 0x... (서명)

응답:

• 402 Payment Required: 결제 서명 없음
• 200 OK: 거래 실행 완료 + 텔레그램 알림

---

시작하기

필수 요구사항

• Python 3.8+
• ClickHouse 접근 권한
• SpoonOS LLM 및 Spoon-toolkit (해커톤 필수 요건)
• 텔레그램 봇 토큰 (선택사항)

설치

# 저장소 클론
git clone <repository-url>
cd gore/backend

# 가상 환경 생성
python -m venv venv

# 가상 환경 활성화
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 의존성 설치
pip install -r requirements.txt

환경 변수 설정 (선택사항)

.env 파일 생성:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
AI_WALLET_PRIVATE_KEY=your_private_key

실행

# FastAPI 서버 실행
python main.py

# 또는 uvicorn 직접 실행
uvicorn main:app --reload --host 0.0.0.0 --port 8000

텔레그램 봇은 별도 프로세스로 실행:

# 별도 터미널에서
python telegram_runner.py

API 문서 확인

서버 실행 후 다음 주소에서 API 문서를 확인할 수 있습니다:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

---

데이터 흐름

1. 데이터 수집 및 캐싱

ClickHouse (wallet_scores 테이블)
    ↓
/api/data 호출 시
    ↓
캐시 확인 (result.txt)
    ├─ 5분 이내 → 캐시에서 반환
    └─ 5분 초과 → DB 조회 → 캐시 업데이트 → 반환

2. 자동 매매 트리거

/api/data 호출 (DB에서 새로 조회한 경우)
    ↓
/api/trade/auto/ai 내부 호출
    ↓
x402 결제 검증
    ↓
SpoonOS LLM 분석 → 매매 결정
    ↓
Paper trade 실행
    ↓
텔레그램 알림 발송

---

해커톤 필수 요건 충족

1. SpoonOS LLM 활용

• /api/trade/auto/ai 엔드포인트에서 spoon_ai.llm.manager 사용
• 트레이더 데이터 분석 및 매매 결정 생성
• LLM 기반 트레이딩 스타일 분석

2. Spoon-toolkit 모듈 사용

• CryptoPowerDataCEXTool을 통한 크립토 데이터 조회
• 실시간 시장 데이터 활용

3. x402 Payment Protocol

• API 접근에 대한 결제 요구사항 생성
• 이더리움 서명을 통한 결제 검증
• 실제 결제 없이 프로토콜 시뮬레이션

---

프로젝트 구조

gore/
├── backend/
│   ├── main.py                    # FastAPI 메인 애플리케이션
│   ├── payment.py                 # x402 결제 요구사항 생성
│   ├── verify.py                  # x402 서명 검증
│   ├── telegram_bot.py            # 텔레그램 봇 로직
│   ├── telegram_runner.py         # 텔레그램 봇 실행 스크립트
│   ├── requirements.txt           # Python 의존성
│   ├── result.txt                 # 캐시된 데이터 (자동 생성)
│   ├── systemd/                   # systemd 서비스 파일
│   │   ├── myapi.service
│   │   └── mybot.service
│   └── test_external_connection.ipynb  # ClickHouse 연결 테스트
└── README.md                      # 프로젝트 문서

---

주요 기능 상세

캐싱 시스템

• 5분 캐싱: ClickHouse 조회 부하 최소화
• 자동 갱신: 캐시 만료 시 자동으로 최신 데이터 조회
• 타임스탬프 저장: 캐시 유효성 검증을 위한 저장 시간 기록

메트릭 분석

6가지 핵심 지표로 트레이더 평가:

• ROI: 총 수익률
• MDD: 최대 손실폭 (음수로 반환)
• CAGR: 연환산 수익률
• Calmar Ratio: CAGR/MDD 비율
• Avg Drawdown: 평균 손실폭
• Recovery Factor: 손실 회복 효율

각 지표는 _score 필드로 0-100 점수로 정규화되어 제공됩니다.

AI Agent 분석

SpoonOS LLM을 활용하여:

• 트레이딩 스타일 분류
• 메트릭 조합 패턴 분석
• 지속가능성 평가
• 정성적 인사이트 제공

---

배포

Systemd 서비스 (Linux)

FastAPI와 텔레그램 봇을 별도 서비스로 실행:

# 서비스 파일 복사
sudo cp backend/systemd/*.service /etc/systemd/system/

# 서비스 활성화 및 시작
sudo systemctl daemon-reload
sudo systemctl enable myapi mybot
sudo systemctl start myapi mybot

# 상태 확인
sudo systemctl status myapi
sudo systemctl status mybot

Nginx 프록시 (선택사항)

backend/nginx_example.conf를 참고하여 Nginx 설정 가능

---

라이선스

Copyright © 2024 Hyperliquid Wallet Scoring System

---

기여하기

이슈 및 개선 제안은 GitHub Issues를 통해 제출해주세요.