Arb Engine

CEX/PerpDEX 아비트라지 봇 - 실시간 데이터 수집, 기회 탐지, 시뮬레이션

개요

단일 머신(랩탑)에서 초단위로 거래소 데이터를 수집하고, 아비트라지 기회를 탐지하며, 시뮬레이션을 통해 전략을 검증하는 Python 기반 시스템입니다.

주요 기능

실시간 데이터 수집: 초단위 WebSocket 연결로 가격, L5 orderbook, funding rate 수집
멀티 거래소 지원:
- CEX: Binance, Bybit, OKX
- PerpDEX: Hyperliquid, Lighter
아비트라지 탐지: 수수료, 슬리피지, funding rate를 고려한 정교한 기회 탐지
수렴 추적: 신호 발생 후 실제 수렴 여부 추적 및 분석
빠른 UI: NiceGUI 기반 실시간 모니터링 대시보드
로컬 스토리지: DuckDB + Parquet로 빠르고 효율적인 데이터 관리

기술 스택

Runtime: Python 3.9+, asyncio
Web Framework: FastAPI (API + WebSocket)
UI: NiceGUI (Python-only, 실시간 UI)
Storage: DuckDB (쿼리) + Parquet (장기 저장)
Data Processing: pandas, numpy
Exchange APIs: ccxt (REST), websockets (WebSocket)

프로젝트 구조

arb-engine/
├── configs/              # YAML 설정 파일
│   ├── exchanges.yaml    # 거래소 목록, 심볼, 엔드포인트
│   ├── fees.yaml         # 거래 수수료
│   ├── strategy.yaml     # 탐지 임계값, 전략 파라미터
│   └── storage.yaml      # 저장소 설정
├── src/arb_engine/
│   ├── domain/           # 도메인 모델 (Pydantic)
│   │   ├── models.py     # PriceTick, OrderbookL5, ArbSignal 등
│   │   └── schema.py     # DuckDB 테이블 스키마
│   ├── core/             # 핵심 유틸리티
│   │   ├── config.py     # 설정 로딩
│   │   ├── types.py      # 타입 정의
│   │   ├── errors.py     # 예외 클래스
│   │   ├── clock.py      # 시간 동기화
│   │   └── logging.py    # 구조화 로깅
│   ├── adapters/         # 거래소 어댑터
│   │   ├── common/       # Base adapter, symbol mapper
│   │   ├── cex/          # Binance, Bybit, OKX
│   │   └── perps/        # Hyperliquid, Lighter
│   ├── services/         # 비즈니스 로직
│   │   ├── collector.py  # 데이터 수집 오케스트레이션
│   │   ├── normalizer.py # 데이터 정규화
│   │   ├── storage.py    # 저장소 서비스
│   │   ├── arb_detector.py  # 아비트라지 탐지
│   │   ├── convergence.py   # 수렴 추적
│   │   ├── simulator.py     # 백테스트/시뮬레이션
│   │   └── reporting.py     # 리포트 생성
│   ├── storage/          # 저장소 구현
│   │   ├── duckdb.py     # DuckDB 연결/쿼리
│   │   └── writers.py    # Parquet 작성
│   ├── api/              # FastAPI 엔드포인트
│   │   ├── routes/       # REST API
│   │   └── ws/           # WebSocket 스트림
│   ├── ui/               # NiceGUI 대시보드
│   │   ├── dashboard.py  # 메인 UI
│   │   └── components/   # UI 컴포넌트
│   └── app/              # 애플리케이션 진입점
│       ├── main.py       # FastAPI 앱
│       └── lifecycle.py  # 시작/종료 훅
├── data/                 # 데이터 저장
│   ├── duckdb/           # DuckDB 파일
│   └── parquet/          # Parquet 파티션
└── scripts/              # 유틸리티 스크립트
    ├── run_collector.py  # 데이터 수집 실행
    ├── run_report.py     # 리포트 생성
    └── run_simulation.py # 시뮬레이션 실행

설치

1. 저장소 클론 및 의존성 설치

cd /path/to/arb-engine

# 가상환경 생성 (권장)
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -e .

# 개발 도구 설치 (선택)
pip install -e ".[dev]"

2. 환경 설정

# .env 파일 편집 (API 키 입력)
cp .env.example .env
# 편집기로 .env 열어서 API 키 입력
nano .env

3. 데이터 디렉토리 초기화

mkdir -p data/duckdb data/parquet data/raw

사용법

Phase 0: 데이터 수집 (현재 구현 중)

# 데이터 수집기 실행
python -m arb_engine.scripts.run_collector

# 또는
arb-collector

Phase 1: 아비트라지 탐지

# 아비트라지 탐지 + 수렴 추적
# (구현 예정)

Phase 2: 리포트 및 시뮬레이션

# 하루 리포트 생성
python -m arb_engine.scripts.run_report

# 시뮬레이션 실행
python -m arb_engine.scripts.run_simulation

개발 로드맵

✅ Phase 0: 프로젝트 설정 및 기본 구조

🚧 Phase 1: 아비트라지 탐지 및 수렴 추적

📋 Phase 2: 리포트 및 시뮬레이션

🚀 Phase 3: 프로덕션 준비

설정 파일 설명

exchanges.yaml

거래소별 WebSocket/REST 엔드포인트, 수집할 심볼, 수집 주기 정의

fees.yaml

거래소별 maker/taker fee, withdrawal fee 정의

strategy.yaml

아비트라지 탐지 임계값 (minimum spread, slippage)
포지션 사이징 규칙
수렴 추적 파라미터
Funding rate 고려 여부

storage.yaml

DuckDB 설정 (경로, 성능 튜닝)
Parquet 파티셔닝 전략
데이터 보관 기간 (retention)
자동 정리 설정

아키텍처 개요

┌─────────────────────────────────────────────┐
│         거래소 (CEX + PerpDEX)                │
│  Binance, Bybit, OKX, Hyperliquid, Lighter  │
└─────────────────┬───────────────────────────┘
                  │ WebSocket
                  ▼
┌─────────────────────────────────────────────┐
│           Adapters (거래소별)                 │
│  - 연결 관리, 재연결                           │
│  - 메시지 파싱                                 │
│  - 최신 데이터 캐시                            │
└─────────────────┬───────────────────────────┘
                  │ 원천 데이터
                  ▼
┌─────────────────────────────────────────────┐
│         Collector (수집 오케스트레이션)         │
│  - 1초 스냅샷 정책 강제                        │
│  - 여러 adapter 관리                          │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│            Normalizer (정규화)               │
│  - 심볼 표준화                                │
│  - Timestamp 정규화                          │
│  - PriceTick, OrderbookL5, FundingRate       │
└─────────────────┬───────────────────────────┘
                  │
            ┌─────┴─────┐
            │           │
            ▼           ▼
    ┌────────────┐  ┌──────────────┐
    │  Storage   │  │ Arb Detector │
    │  (DuckDB/  │  │              │
    │  Parquet)  │  │ - 기회 탐지   │
    └────────────┘  │ - 수렴 추적   │
                    └───────┬──────┘
                            │
                            ▼
                    ┌──────────────┐
                    │   Simulator  │
                    │   Reporting  │
                    └───────┬──────┘
                            │
                            ▼
                    ┌──────────────┐
                    │   UI / API   │
                    │  (NiceGUI/   │
                    │   FastAPI)   │
                    └──────────────┘

데이터 모델

PriceTick

exchange, symbol, price, volume_24h
exchange_timestamp, received_timestamp

OrderbookL5

exchange, symbol
bids[5], asks[5] (price, size)
best_bid, best_ask, mid_price, spread

FundingRate

exchange, symbol, funding_rate
next_funding_time, predicted_rate

ArbSignal

buy_exchange, sell_exchange
buy_price, sell_price
gross_spread, net_spread (after fees)
estimated_size, estimated_slippage
status (detected, in_progress, converged, failed)

기여

이 프로젝트는 개인 프로젝트입니다.

라이선스

MIT License

참고

Binance API: https://binance-docs.github.io/apidocs/
Bybit API: https://bybit-exchange.github.io/docs/
OKX API: https://www.okx.com/docs-v5/
Hyperliquid API: https://hyperliquid.gitbook.io/
Lighter: https://lighter.xyz/docs

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
configs		configs
scripts		scripts
src/arb_engine		src/arb_engine
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml

energyGiver/arb-engine

Folders and files

Latest commit

History

Repository files navigation