Polymarket LLM Agent Trading Bot

Polymarket 예측 시장에서 LLM Agent를 활용하여 자동 거래하는 트레이딩 봇입니다.

주요 기능

• 6개의 전문 LLM Agent: Research, Probability, Sentiment, Risk, Execution, Arbiter
• 데모 거래 모드: 실제 자금 없이 모의 거래 가능
• 실시간 대시보드: 포트폴리오, 포지션, 거래 내역 모니터링
• 리스크 관리: Kelly Criterion, 손실 제한, 드로우다운 관리
• 15분 간격 자동 실행: 비용 효율적인 실행 주기

아키텍처

┌─────────────────────────────────────────────────────────────┐
│                      ARBITER AGENT                          │
│              (최종 의사결정, Agent 조율)                      │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│ RESEARCH      │     │ PROBABILITY   │     │ SENTIMENT     │
│ AGENT         │     │ AGENT         │     │ AGENT         │
└───────────────┘     └───────────────┘     └───────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              ▼
                    ┌───────────────┐
                    │ RISK AGENT    │
                    └───────────────┘
                              │
                              ▼
                    ┌───────────────┐
                    │ EXECUTION     │
                    │ AGENT         │
                    └───────────────┘

프로젝트 구조

agent_trading/
├── src/
│   ├── agents/          # 6개 LLM Agent
│   ├── core/
│   │   ├── polymarket/  # Polymarket API 클라이언트
│   │   ├── llm/         # LLM Provider (OpenAI)
│   │   └── database/    # DB 모델
│   ├── strategies/      # Kelly Criterion, Edge Sizing
│   ├── risk/            # 리스크 관리
│   └── scheduler/       # 트레이딩 루프
├── dashboard/
│   ├── backend/         # FastAPI
│   └── frontend/        # Next.js
├── docker/
├── config/
└── scripts/

빠른 시작

1. 환경 설정

# 저장소 클론
cd /home/lee/decipher/agent_trading

# .env 파일 생성
cp config/.env.example .env

# .env 파일 편집 (OpenAI API 키 설정)
# OPENAI_API_KEY=your_api_key_here

2. 의존성 설치

# Python 의존성
pip install -r requirements.txt

# Frontend 의존성
cd dashboard/frontend
npm install

3. 실행

단일 트레이딩 사이클 실행

python main.py

대시보드와 함께 실행

# 터미널 1: PostgreSQL (Docker)
docker-compose -f docker/docker-compose.yml up -d postgres

# 터미널 2: Backend API
python -m uvicorn dashboard.backend.main:app --reload --port 8000

# 터미널 3: Frontend
cd dashboard/frontend
npm run dev

접속: http://localhost:3001

Docker Compose로 전체 실행

docker-compose -f docker/docker-compose.yml up --build

베팅 전략

Kelly Criterion (Fractional)

f* = (p × b - q) / b

적용: Quarter Kelly (f*/4)
- 변동성 감소
- 파산 확률 최소화

Edge-Based Sizing

edge = estimated_probability - market_price
if edge > 5%:
    position_size = base_size × (edge / 10%)

리스크 관리

제한 항목	값
단일 포지션 최대	10% of equity
동시 포지션	최대 10개
일일 손실 한도	-5%
주간 손실 한도	-10%
최대 드로우다운	-20%

비용 예상 (월간)

항목	예상 비용
GPT-4o-mini (15분 간격)	~$10-15
인프라 (로컬)	$0
총계	~$10-15/월

주의사항

• 데모 모드: 기본적으로 실제 거래 없이 시뮬레이션만 수행
• 실거래 전환: .env에서 TRADING_MODE=live 설정 및 지갑 연동 필요
• 투자 손실: 예측 시장 거래는 손실 위험이 있습니다

기술 노트 (개발자용)

Polymarket API 구조 - Event vs Market

Polymarket API는 두 가지 주요 엔티티가 있습니다:

1. Event: 상위 개념 (예: "Which CEOs will be gone in 2025?")

   • 카테고리 정보 포함 (예: "Business")
   • 여러 Market을 포함할 수 있음
   • /events 엔드포인트로 조회

2. Market: 개별 베팅 가능한 항목 (예: "Tim Cook out as Apple CEO in 2025?")

   • Event 내에 nested되어 반환됨
   • outcomePrices, clobTokenIds 등 거래 정보 포함
   • /markets/{id} 엔드포인트로 개별 조회

중요:

• client.py의 get_markets()는 /events 엔드포인트에서 Event를 가져온 후 내부의 markets를 파싱합니다.
• 카테고리 정보는 Event 레벨에만 있으므로, Market에 전달해야 합니다.
• 실거래 모드 전환 시 open_position 등의 기능이 이 구조를 참고해야 합니다.

카테고리 매핑

원본 Polymarket 카테고리 → 정규화된 카테고리:

CATEGORY_MAPPING = {
    "sports": ["Sports", "NBA Playoffs", "Olympics", "Chess", "Poker"],
    "politics": ["US-current-affairs", "Global Politics", "Ukraine & Russia"],
    "crypto": ["Crypto", "NFTs"],
    "entertainment": ["Pop-Culture", "Art"],
    "science": ["Science", "Coronavirus"],
    "business": ["Business"],
}

타임존 처리

• 백엔드: 모든 시간은 UTC로 저장/반환
• 프론트엔드: API에서 받은 시간에 'Z' suffix를 추가하여 UTC로 파싱

  const lastRunStr = status.last_run.endsWith('Z') ? status.last_run : status.last_run + 'Z';

라이선스

MIT License

참고

• Polymarket API Docs
• py-clob-client
• Alpha Arena (nof0)