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 에이전트 기반 자동 매매 실행

동작 흐름:

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

요청:

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 설정 가능

라이선스

기여하기

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

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.claude		.claude
.codetracker		.codetracker
.venv		.venv
__pycache__		__pycache__
systemd		systemd
DEPLOYMENT.md		DEPLOYMENT.md
HACKATHON_PROOF.md		HACKATHON_PROOF.md
README.md		README.md
main.py		main.py
nginx_example.conf		nginx_example.conf
payment.py		payment.py
requirements.txt		requirements.txt
result.txt		result.txt
telegram_bot.py		telegram_bot.py
telegram_runner.py		telegram_runner.py
test_external_connection.ipynb		test_external_connection.ipynb
verify.py		verify.py

ScoopAIthon/backend

Folders and files

Latest commit

History

Repository files navigation

Hyperliquid Wallet Scoring System

프로젝트 소개

주요 기능

시스템 아키텍처

기술 스택

Backend

주요 라이브러리

API 문서

GET /api/data

GET /api/information/{wallet_id}

POST /api/trade/auto/ai

시작하기

필수 요구사항

설치

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

실행

API 문서 확인

데이터 흐름

1. 데이터 수집 및 캐싱

2. 자동 매매 트리거

해커톤 필수 요건 충족

1. SpoonOS LLM 활용

2. Spoon-toolkit 모듈 사용

3. x402 Payment Protocol

프로젝트 구조

주요 기능 상세

캐싱 시스템

메트릭 분석

AI Agent 분석

배포

Systemd 서비스 (Linux)

Nginx 프록시 (선택사항)

라이선스

기여하기

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

`GET /api/data`

`GET /api/information/{wallet_id}`

`POST /api/trade/auto/ai`

Packages