Metadata-Version: 2.4
Name: mustache-mcp
Version: 0.1.1
Summary: Funding-rate farming MCP server for Pacifica — scan funding rates, open delta-neutral hedges, and manage positions from your AI agent
License: MIT
Keywords: mcp,pacifica,trading,funding-rate,delta-neutral,solana
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: solders>=0.19.0
Requires-Dist: base58>=2.1.1
Requires-Dist: PyYAML>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: mcp>=1.0

# Pacifica 펀딩비 파밍 봇

스팟 매수 + perp 숏으로 델타뉴트럴 포지션을 만들어 펀딩비를 수취하는 자동화 봇.
펀딩비가 높은 코인을 자동 스캔해 진입하고, 펀딩비가 떨어지면 자동 청산한다.
모든 주문에 Builder Code 첨부 지원 (수수료 수익).

## 전략 (config.yaml의 `strategy_mode`로 선택)

### hedged — 델타뉴트럴 (안전)
- 펀딩비가 **양수**면 롱이 숏에게 지급 → **스팟 매수 + 같은 수량 perp 숏** = 가격 변동 중립, 펀딩만 수취
- 대상: 스팟+perp 동시 상장 코인만 (현재 메인넷은 SOL 정도)
- 가격이 오르든 내리든 손익 없음. 펀딩 음수일 땐 기회 없음(대기)

### directional — 펀딩 방향 추종 (⚠️ 가격 위험 노출)
- 펀딩 **양수** → perp **숏** 단독 / 펀딩 **음수** → perp **롱** 단독으로 펀딩 수취
- 대상: 전체 perp (~69개), |펀딩| 큰 코인 자동 선택
- 펀딩 방향이 뒤집히거나 약해지면 자동 청산
- **주의**: 헤지가 없으므로 코인 가격 변동 손익을 그대로 떠안는다.
  펀딩 수익(연 10~수십%)보다 가격 변동(하루 ±5%)이 훨씬 클 수 있음.
  펀딩이 극단적으로 높은 코인은 대개 그만한 이유(급변동 중)가 있다는 점 유의

공통:
- 진입: 펀딩 APR ≥ `entry_threshold_apr` / 청산: 수취 기준 APR < `exit_threshold_apr`
- 참고: Pacifica 기본 펀딩비는 시간당 0.0000125 ≈ **연 10.9%** (이게 평상시 값)
- 스팟 잔고는 크로스마진 담보로 자동 인정됨 (Unified Margin — 별도 설정 불필요)

## 처음 쓰는 사람용 빠른 시작

누구나 자기 Pacifica 계정으로 이 봇을 쓸 수 있다. 필요한 것: Python 3.10+, Node.js 18+ (MCP 모드용).

1. 이 폴더를 다운로드
2. **설치.bat** 더블클릭 → 패키지 설치 + 환경 진단 자동 실행
3. `.env.example`을 복사해 `.env`로 이름 변경 → 본인 지갑 주소와 API 키 입력
   (API 키: [app.pacifica.fi/apikey](https://app.pacifica.fi/apikey)에서 발급)
4. 본인 계정에서 빌더 코드 `mustache` 승인 (이 봇의 주문에 첨부됨, 수수료율 0.01%)
5. **펀딩스캔.bat**으로 시세 확인 → **봇실행.bat**으로 가동 (기본 dry-run 안전 모드)

문제가 생기면 `python -m mustache_mcp.doctor`로 뭐가 빠졌는지 확인.

## 설치 (수동)

```bash
pip install -r requirements.txt
python -m mustache_mcp.doctor   # 환경 진단
```

MCP 모드(`api_mode: mcp`)를 쓰려면 Node.js 18+도 필요하다 (봇이 `npx -y @pacifica-fi/mcp-server`를 자동으로 띄움).

## API 연결 방식 (config.yaml의 `api_mode`)

- `mcp` — 봇이 **Pacifica 공식 MCP 서버**를 자식 프로세스로 띄우고 60개 MCP 도구를 통해 조회/주문 (기본값)
- `rest` — REST API 직접 호출 (Node.js 불필요, 의존성 최소)

두 모드는 완전히 같은 전략 로직을 공유하며 언제든 전환 가능하다.

## 설정

1. `.env.example`을 `.env`로 복사하고 값 입력:
   - `ADDRESS` — Pacifica 계정 주소 (조회/dry-run은 이것도 없이 동작)
   - `PACIFICA_API_KEY` — API 키 ([app.pacifica.fi/apikey](https://app.pacifica.fi/apikey)에서 발급). 실주문 시에만 필요. 거래 전용이라 지갑 자산은 못 건드림
   - `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` — 텔레그램 알림용 (선택)
2. `config.yaml`에서 전략 파라미터 조정 (임계값, 최대 금액, 주기 등)

## 실행

```bash
# 펀딩비 스캔만 (키 불필요)
python -m mustache_mcp.scanner

# 1사이클 테스트
python -m mustache_mcp.main --once

# 봇 상시 가동
python -m mustache_mcp.main
```

## 실거래 전환 절차 (반드시 순서대로)

1. 테스트넷 + `dry_run: true` 로 판단 로직 확인 ← **현재 상태**
2. 테스트넷 + `dry_run: false` + 소액으로 오픈→청산 1사이클 확인
3. `config.yaml`의 `base_url`을 `https://api.pacifica.fi`로 변경, 소액부터 시작

## Builder Code

1. Pacifica 팀에 빌더 등록 요청: ops@pacifica.fi / Discord / 텔레그램 @PacificaTGPortalBot
2. 발급받은 코드를 `config.yaml`의 `builder_code`에 입력 (3-16 영숫자)
3. 주의: 이 봇을 **다른 사용자**가 쓰게 하려면, 그 사용자가 먼저 해당 builder code를
   승인(`max_fee_rate` 서명)해야 주문이 통과됨

## 파일 구조

| 파일 | 역할 |
|---|---|
| `mustache_mcp/scanner.py` | 전 마켓 펀딩비 스캔 + 스팟 상장 필터 |
| `mustache_mcp/position.py` | 델타뉴트럴 오픈/클로즈 (실패 시 롤백) |
| `mustache_mcp/api_client.py` | REST 클라이언트 (서명 포함) |
| `mustache_mcp/signing.py` | Solana 키 서명 (공식 SDK 방식) |
| `mustache_mcp/notify.py` | 텔레그램 알림 |
| `mustache_mcp/state.py` | 포지션 상태 저장 (`state.json`) |
| `mustache_mcp/main.py` | 메인 루프 |

## 리스크

- 델타뉴트럴이어도 **완전 무위험이 아님**: 진입/청산 슬리피지, 수수료, 펀딩비 급변,
  스팟-perp 가격 괴리(베이시스) 리스크 존재
- 한쪽 레그만 체결되는 상황은 자동 롤백하지만, 롤백 주문도 실패하면 델타 노출 발생
  → 긴급 알림 수신 시 수동 확인 필요
- `max_notional_usd`를 감당 가능한 금액으로 유지할 것
