# 🌍 군자 AI - 글로벌 사용자 가이드

**버전:** 3.0
**최종 업데이트:** 2025년 10월 1일
**고객지원:** admin@starium.site
**웹사이트:** https://metaquant.club

---

## 📋 목차

1. [소개](#소개)
2. [빠른 시작 가이드](#빠른-시작-가이드)
3. [대시보드 개요](#대시보드-개요)
4. [거래 기능](#거래-기능)
5. [API 설정](#api-설정)
6. [성과 모니터링](#성과-모니터링)
7. [리스크 관리](#리스크-관리)
8. [문제 해결](#문제-해결)
9. [자주 묻는 질문](#자주-묻는-질문)

---

## 🚀 소개

**군자 AI v3.0**에 오신 것을 환영합니다 - 암호화폐 선물 거래를 위해 설계된 차세대 AI 기반 자율 거래 플랫폼입니다.

### 군자 AI란 무엇인가요?

군자 AI는 다음을 결합한 고급 거래 시스템입니다:
- **25개 이상의 기술 지표** - 종합적인 시장 분석
- **점수 랭킹 분석** (기술지표·펀딩비·뉴스) - 방향 결정
- **Peak Tracker** - 페어별 최대 수익 지점 기록
- **계정별 독립 사이클** - 실측 약 49초 주기
- **자동화 거래** - Bitget 선물 시장에서 자동 거래

### 주요 기능

✨ **자율 거래**: 24/7 완전 자동화 거래
🧠 **AI 기반**: 여러 AI 모델이 조화롭게 작동
📊 **고급 분석**: 25개 핵심 + 21개 확장 기술 지표
🔄 **기록**: Peak Tracker 가 놓친 수익을 데이터로 남긴다
🛡️ **리스크 관리**: 동적 포지션 크기 조정 및 손절매
📈 **실시간 대시보드**: 라이브 거래 성과 모니터링

---

## ⚡ 빠른 시작 가이드

### 1단계: 플랫폼 접속

1. 웹사이트 방문: https://metaquant.club
2. 선호하는 언어 선택 (English, 한국어, 日本語, 中文)
3. **"무료로 시작하기"** 또는 **"로그인"** 클릭

### 2단계: 계정 생성

1. 홈페이지에서 **"회원가입"** 클릭
2. 이메일 주소 입력
3. 안전한 비밀번호 생성
4. 이메일 인증 (스팸 폴더 확인)
5. 계정 로그인

### 3단계: API 키 설정

**중요:** 군자 AI는 거래를 실행하기 위해 Bitget API 자격 증명이 필요합니다.

1. [Bitget API 관리](https://www.bitget.com/api-doc)로 이동
2. 다음 권한으로 새 API 키 생성:
   - ✅ **읽기** (필수)
   - ✅ **거래** (필수)
   - ❌ **출금** (불필요, 보안을 위해 비활성화)
3. 복사:
   - API 키
   - 시크릿 키
   - 패스프레이즈
4. 군자 AI 대시보드 → **설정** → **API 설정**
5. 자격 증명 붙여넣기 및 **"저장 및 연결 테스트"** 클릭

### 4단계: 거래 시작

1. 대시보드 검토
2. 시스템 상태 확인 ("✅ 모든 시스템 정상 작동" 표시되어야 함)
3. 라이브 포지션 및 신호 모니터링
4. 필요시 리스크 설정 조정 (설정 → 리스크 관리)

**🎉 축하합니다!** 이제 군자 AI 시스템이 활성화되어 자동으로 거래하고 있습니다.

---

## 📊 대시보드 개요

### 메인 대시보드 구성요소

#### 1. **라이브 거래 상태**
- **시스템 상태**: 실시간 운영 상태
- **활성 포지션**: 현재 열린 거래
- **24시간 성과**: 일일 손익 요약
- **성공률**: 승률 백분율

#### 2. **거래 페어 히트맵**
14개 주요 거래 페어의 실시간 시각화:
- BTCUSDT, ETHUSDT, BNBUSDT, XRPUSDT
- SOLUSDT, DOGEUSDT, ADAUSDT, DOTUSDT
- MATICUSDT, LINKUSDT, UNIUSDT, LTCUSDT
- AVAXUSDT, ATOMUSDT

**색상 코드:**
- 🟢 **녹색**: 강세 신호
- 🔴 **빨강**: 약세 신호
- 🟡 **노랑**: 중립/대기

#### 3. **AI 분석 패널**
4개의 AI 모델이 동시에 시장 분석:
- **기술지표(tech)**: 추세·모멘텀 성분
- **펀딩비(funding)**: 포지션 쏠림 성분
- **뉴스(news)**: 언어모델이 사건을 요약·채점
- **Groq**: 빠른 실시간 분석

#### 4. **기술 지표**
25개 핵심 지표 확인:
- **추세**: EMA, SMA, MACD, ADX
- **모멘텀**: RSI, Stochastic, CCI
- **변동성**: 볼린저 밴드, ATR
- **거래량**: OBV, MFI, VWAP
- **커스텀**: TMA, 복합 지수

---

## 🎯 거래 기능

### 1. **자율 거래 모드**

**작동 원리:**
1. 계정마다 독립된 주기(실측 약 49초)로 시장 분석
2. 25개 기술 지표가 신호 생성
3. 점수 랭킹으로 방향을 정하고 상관이 낮은 짝을 고름
4. 시스템이 자동으로 거래 실행
5. Peak Tracker 가 최대 수익 지점과 실제 청산 시점을 함께 기록

**제어 가능한 설정:**
- **포지션 크기**: 고정 금액 (거래당 10 USDT)
- **레버리지**: 10배 (Strategy1에 따라 설정)
- **최대 포지션**: 최대 8개 심볼
- **거래 시간**: 24/7 (항상 활성)

### 2. **신호 시스템**

**24개 TRIGGER 유형:**
- **16개 기본 TRIGGER**: 지지/저항 레벨 (±2%)
- **5개 신뢰도 TRIGGER**: AI 선택 방향 (5분마다 재생성)
- **3개 헤지 TRIGGER**: ROE -10% 보호 시스템

**TRIGGER 작동 방식:**
1. 시스템이 주요 가격 수준 식별
2. 해당 수준에 트리거 주문 생성
3. 가격이 트리거에 도달하면 자동 실행
4. 새로운 시장 데이터로 5분마다 재생성

### 3. **동적 익절 (TP)**

**AI 기반 TP 관리:**
- **최소 TP**: 0.3% 수익 보장
- **동적 조정**: 모멘텀에 따라 AI가 TP 증가
- **스마트 종료**: 최적 수익 지점에서 포지션 종료

**예시:**
```
진입: $100,000 (BTC)
TP 목표: $100,300 (최소 0.3%)
AI가 강한 모멘텀 감지 → $100,600으로 조정 (0.6%)
종료: $100,600 (실제 수익: 0.6%)
```

### 4. **헤지 시스템**

**ROE -10% 보호:**
- 모든 열린 포지션 모니터링
- 포지션이 -10% ROE(자기자본이익률) 도달 시
- 자동으로 헤지 TRIGGER 생성
- 반대 포지션을 열어 자본 보호

**예시:**
```
$100,000에 BTC 롱 → 가격이 $90,000으로 하락 (-10% ROE)
시스템 생성: $90,000에 BTC 숏 트리거
헤지 포지션이 추가 손실 제한
```

---

## 🔧 API 설정

### 지원되는 거래소

현재 지원:
- ✅ **Bitget** (완전 통합)
- 🔄 **Binance** (곧 출시)
- 🔄 **Gate.io** (곧 출시)

### API 설정 지침

#### Bitget의 경우:

1. **Bitget 로그인**
   - https://www.bitget.com 방문
   - 계정 로그인

2. **API 관리로 이동**
   - 프로필 클릭 → API 관리
   - "API 생성" 클릭

3. **API 권한 설정**
   - "선물 거래" 모드 선택
   - 권한 활성화:
     - ✅ 읽기
     - ✅ 거래
     - ❌ 출금 (비활성화 유지)
   - IP 화이트리스트 설정 (선택사항, 권장)

4. **자격 증명 저장**
   - API 키 복사
   - 시크릿 키 복사
   - 패스프레이즈 설정 및 복사 (기억하세요!)
   - 안전하게 보관 (절대 공유하지 마세요)

5. **군자 AI에 추가**
   - 대시보드 → 설정 → API 설정
   - 거래소: "Bitget" 선택
   - API 키, 시크릿 키, 패스프레이즈 붙여넣기
   - "연결 테스트" 클릭
   - 성공하면 "저장" 클릭

### 보안 모범 사례

🔐 **API 보안:**
- API 자격 증명을 절대 공유하지 마세요
- 가능하면 IP 화이트리스트 사용
- "출금" 권한 비활성화
- 정기적으로 API 키 교체 (3개월마다)
- Bitget에서 API 활동 모니터링

⚠️ **경고 신호:**
- Bitget 계정에서 예상치 못한 거래
- 군자 AI에서 API 키 오류
- 비정상적인 포지션 크기
- 알 수 없는 IP 접근 시도

**침해 시:** 즉시 Bitget에서 API 키를 삭제하고 새로 생성하세요.

---

## 📈 성과 모니터링

### 실시간 지표

#### 1. **포지션 추적**
활성 포지션 모니터링:
- **진입 가격**: 개시 가격
- **현재 가격**: 실시간 시장 가격
- **손익**: 손익 (USDT 및 %)
- **ROE**: 자기자본이익률
- **기간**: 포지션이 열린 시간

#### 2. **과거 성과**
과거 거래 결과 보기:
- **종료된 포지션**: 완료된 모든 거래
- **승률**: 수익성 거래 백분율
- **평균 수익**: 승리 거래당 평균 수익
- **평균 손실**: 손실 거래당 평균 손실
- **총 손익**: 전체 손익

#### 3. **AI 신뢰도 점수**
각 신호는 AI 신뢰도 표시:
- **0-40%**: 낮은 신뢰도 (시스템이 건너뛸 수 있음)
- **40-70%**: 중간 신뢰도 (신중한 진입)
- **70-100%**: 높은 신뢰도 (공격적 진입)

### 성과 대시보드 (포트 8004)

상세 분석 접근:
- URL: https://app.metaquant.club
- 군자 AI 자격 증명으로 로그인
- 확인:
  - 상세 거래 기록
  - 포지션 타임라인
  - 손익 차트
  - 전략 효과성
  - AI 모델 성능 비교

---

## 🛡️ 리스크 관리

### 내장 리스크 제어

#### 1. **포지션 크기 조정**
- **고정 진입**: 트리거당 10 USDT
- **레버리지**: 10배 승수
- **유효 자본**: 포지션당 100 USDT
- **최대 리스크**: 거래당 10 USDT 손실로 제한

#### 2. **헤지 보호**
- -10% ROE에서 자동 헤지
- 포지션당 최대 손실 제한
- 반대 방향 트리거 생성
- 높은 변동성 중 자본 보호

#### 3. **동적 손절매**
- AI 관리 청산
- 하드 손절매 없음 (손절매 사냥 방지)
- 시장 상황 기반 지능적 종료
- 자본 보존 우선

### 사용자 설정 가능한 옵션

조정 가능:
- **최대 동시 포지션**: 1-8 심볼
- **거래 심볼**: 거래할 페어 선택
- **리스크 수준**: 보수적/균형적/공격적
- **알림**: 거래에 대한 텔레그램 알림

**초보자를 위한 권장 설정:**
```yaml
최대 포지션: 4
거래 심볼: BTC, ETH, XRP, SOL
리스크 수준: 보수적
레버리지: 10배 (기본값, 변경하지 마세요)
포지션 크기: 10 USDT (기본값, 변경하지 마세요)
```

---

## 🔍 문제 해결

### 일반적인 문제

#### 문제 1: "API 연결 실패"

**증상:**
- 대시보드에 "❌ API 오류" 표시
- 포지션이 열리지 않음
- 오류: "Bitget 연결 실패"

**해결 방법:**
1. API 자격 증명이 올바른지 확인
2. API 권한 확인 (읽기 + 거래 활성화)
3. Bitget 계정에 USDT 잔액이 있는지 확인
4. Bitget에서 API 키 재생성 시도
5. 문제가 지속되면 지원팀에 문의

#### 문제 2: "트리거 생성 안 됨"

**증상:**
- 대시보드에 "⏳ 신호 대기 중" 표시
- 트리거 주문이 생성되지 않음
- 시스템은 작동하지만 비활성

**해결 방법:**
1. 시장 변동성 확인 (낮은 변동성 = 적은 신호)
2. AI 신뢰도 임계값 확인 (너무 높을 수 있음)
3. 5-10분 대기 (시스템이 5분마다 재생성)
4. 선택한 거래 심볼 확인
5. 시스템 로그 검토

#### 문제 3: "포지션이 닫히지 않음"

**증상:**
- 포지션이 수익 중이지만 닫히지 않음
- TP 목표에 도달하지 않음
- 포지션이 오랜 시간 동안 열림

**해결 방법:**
1. 현재 TP 목표 확인 (대시보드 → 포지션 → TP)
2. AI가 더 높은 수익을 위해 TP를 조정 중일 수 있음
3. 시장이 아직 TP에 도달하지 않았을 수 있음
4. 수동 종료: 대시보드 → 포지션 → "지금 닫기"

#### 문제 4: "포지션 높은 손실"

**증상:**
- 포지션이 -5% 이상 손실 표시
- 지속적인 손실에 대한 우려
- 헤지가 아직 트리거되지 않음

**해결 방법:**
1. 헤지는 -10% ROE에서 자동으로 트리거됨
2. 시스템은 AI 관리 종료 사용 (하드 손절매 없음)
3. 분할 익절 단계가 순서대로 진행되도록 둔다
4. 매우 우려되면: 대시보드에서 수동 종료
5. 포지션 종료 후 리스크 설정 검토

### 도움 받기

📧 **이메일 지원:** admin@starium.site
💬 **텔레그램:** @GunjaAISupport (곧 출시)
📖 **문서:** https://metaquant.club/ko/guide
🐛 **버그 신고:** GitHub Issues (비공개 저장소)

---

## ❓ 자주 묻는 질문

### 일반 질문

**Q: 군자 AI는 완전 자동화인가요?**
A: 네, 설정이 완료되면 시스템이 수동 개입 없이 24/7 자동으로 거래합니다.

**Q: 거래 경험이 필요한가요?**
A: 아니요, 군자 AI는 초보자와 전문가 모두를 위해 설계되었습니다. AI가 모든 거래 결정을 처리합니다.

**Q: 최소 예치금은 얼마인가요?**
A: 권장 최소: 10개의 동시 포지션을 위해 Bitget에 100 USDT (10 USDT × 10 포지션).

**Q: 예치금보다 더 많이 잃을 수 있나요?**
A: 아니요, 최대 손실은 Bitget 선물 계정 잔액으로 제한됩니다. 시스템에 헤지 보호가 포함되어 있습니다.

### 거래 질문

**Q: AI는 얼마나 자주 시장을 분석하나요?**
A: 계정당 약 49초 주기입니다(실측값, 계정 수와 거래소 응답에 따라 달라집니다).

**Q: 인터넷이 끊기면 어떻게 되나요?**
A: 시스템은 클라우드 서버에서 실행되며 귀하의 컴퓨터가 아닙니다. 컴퓨터를 꺼도 거래는 계속됩니다.

**Q: 포지션을 수동으로 닫을 수 있나요?**
A: 네, 대시보드 → 포지션 → 포지션 선택 → "지금 닫기" 버튼.

**Q: 시스템이 기록한 학습 데이터는 어떻게 쓰이나요?**
A: 시스템은 모든 거래에서 학습하여 현재 시장 조건에서 가장 잘 작동하는 것을 기반으로 전략을 조정합니다.

### 기술 질문

**Q: 군자는 어떤 AI 모델을 사용하나요?**
A: 방향 점수는 기술지표·펀딩비·뉴스 세 성분으로 계산합니다. 뉴스 요약·채점과 거래 회고에 언어모델을 사용하며, 사용하는 모델은 운영 중 바뀔 수 있어 특정 모델명을 성능의 근거로 삼지 않습니다.

**Q: 25개 이상의 기술 지표는 무엇인가요?**
A: EMA, SMA, MACD, RSI, Stochastic, 볼린저 밴드, ATR, ADX, CCI, OBV, MFI, VWAP, 그리고 13개 이상의 커스텀 지표.

**Q: 내 데이터는 안전한가요?**
A: 네, API 키는 암호화되고 절대 공유되지 않으며 안전하게 저장됩니다. 우리는 자금 인출 권한이 없습니다.

**Q: 모바일에서 군자 AI를 사용할 수 있나요?**
A: 네, 웹 대시보드는 모바일 반응형입니다. https://app.metaquant.club 에서 모든 기기로 접근할 수 있습니다.

### 성능 질문

**Q: 예상 성공률은 얼마인가요?**
A: 공개 자료에 승률 수치를 적지 않습니다. 실적은 로그인 후 본인 대시보드에서 거래소 계좌 원장 기준으로 확인하십시오. 과거 성능이 미래 결과를 보장하지 않습니다.

**Q: 얼마나 수익을 낼 수 있나요?**
A: 수익은 시장 조건·자본·리스크 설정에 따라 다릅니다. 익절은 4단계 사다리로 나눠 실현하며, 청산 임계값은 변동성에 따라 동적으로 정해집니다. **손절은 사용하지 않으므로 손실 구간에서는 회복까지 자금이 묶입니다.**

**Q: 수수료가 있나요?**
A: 플랫폼 수수료는 관리자에게 문의하십시오. 거래소 수수료는 거래소 정책을 따릅니다(예: Bitget 약 0.06%/거래).

**Q: 전략을 백테스트할 수 있나요?**
A: 현재 사용자 대시보드에서는 사용할 수 없습니다. v3.1 업데이트에서 제공 예정.

---

## 🎓 다음 단계

### 초보자 경로
1. ✅ 빠른 시작 가이드 완료
2. ✅ API 키 설정
3. ✅ 2-4개 거래 심볼로 시작
4. ✅ 7일간 성과 모니터링
5. ✅ 결과에 따라 설정 조정
6. ✅ 점진적으로 포지션 증가

### 고급 경로
1. ✅ 기술 지표 대시보드 탐색
2. ✅ AI 모델 합의 패턴 분석
3. ✅ 리스크 관리 설정 미세 조정
4. ✅ 분할 익절 진행 단계 확인
5. ✅ 심볼 선택 최적화
6. ✅ 군자 AI 커뮤니티 참여 (곧 출시)

---

## 📞 연락 및 지원

**군자 AI 지원팀**
📧 이메일: admin@starium.site
🌐 웹사이트: https://metaquant.club
📊 대시보드: https://app.metaquant.club
📰 뉴스: https://app.metaquant.club (회원 대시보드 「뉴스」 탭)

**업무 시간:** 24/7 (AI 기반 지원)
**응답 시간:** 24시간 이내

---

**© 2025 군자 AI. All rights reserved.**
*전 세계 트레이더를 위해 ❤️로 제작되었습니다.*

---

## 🔄 버전 기록

**v3.0** (2025년 10월)
- 점수 랭킹 방향 엔진
- Peak Tracker 기록 시스템
- 25개 이상의 기술 지표
- 거래 페어 히트맵
- 향상된 사용자 대시보드

**v2.0** (2025년 9월)
- 다중 사용자 지원
- Strategy1 준수
- ROE -10% 헤지 시스템
- 동적 TP 관리

**v1.0** (2025년 8월)
- 초기 릴리스
- 기본 AI 거래
- Bitget 통합
- 64개 기술 지표