🎯 آربان (ARBAN)

موتور هوشمند شناسایی فرصت‌های سودآوری در بازارهای پیش‌بینی

«ابزار تحلیل و شناسایی خودکار تفاوت قیمت‌ها در بازارهای پیش‌بینی»

نصب سریع • ویژگی‌ها • راهنمای استفاده • مستندات

---

📖 درباره آربان

آربان (ARBAN - Arbitrage Bot for Analysis) یک سیستم متن‌باز و رایگان است که به شما کمک می‌کند تا تفاوت قیمت‌ها بین بازارهای مختلف پیش‌بینی را شناسایی کنید.

💡 ایده اصلی

گاهی اوقات یک رویداد خاص در دو سایت مختلف، قیمت‌های متفاوتی دارد. آربان این تفاوت‌ها را پیدا می‌کند و به شما نشان می‌دهد که چگونه می‌توانید با خرید همزمان از هر دو بازار، سود قطعی کسب کنید!

🔄 گردش کار آربان:
دریافت قیمت‌ها → یکسان‌سازی داده‌ها → تطبیق رویدادها → شناسایی فرصت‌ها → محاسبه سود

⚠️ نکته مهم: آربان فقط یک ابزار تحلیلی است و هیچ معامله‌ای انجام نمی‌دهد. تمام تصمیم‌گیری‌ها بر عهده کاربر است.

---

✨ امکانات و قابلیت‌ها

✅ ویژگی‌های اصلی پشتیبانی از چندین بازار: Polymarket, Kalshi, Limitless, Crypto.com تحلیل هوشمند: تشخیص رویدادهای مشابه در پلتفرم‌های مختلف محاسبات دقیق: در نظر گرفتن کارمزدها، نقدینگی و لغزش قیمت رابط وب زیبا: داشبورد تحت وب برای مشاهده آسان فرصت‌ها API کامل: امکان اتصال برنامه‌های دیگر حالت نمایشی: داده‌های نمونه برای یادگیری و تست

🛠️ ویژگی‌های فنی تشخیص دوطرفه و چندوجهی: هم برای بازارهای ۲ حالته و هم چند حالته مدل‌سازی پیشرفته: محاسبه اثر حجم معاملات روی قیمت بررسی سلامت: مانیتورینگ لحظه‌ای وضعیت ارائه‌دهندگان داده تست خودکار: مجموعه کامل تست‌های واحد و یکپارچگی پشتیبانی از Docker: نصب و اجرا در کمتر از ۵ دقیقه مستندات کامل: راهنماهای گام‌به‌گام برای همه سطوح

---

🌐 بازارهای پشتیبانی‌شده

نام بازار	وضعیت	نوع بازار
Polymarket	✅ آماده استفاده	بازار پیش‌بینی ارز دیجیتال
Kalshi	✅ آماده استفاده	بازار پیش‌بینی قانون‌مند آمریکا
Limitless	🔄 نسخه آزمایشی	مشتقات ارز دیجیتال
Crypto.com	🔄 نسخه آزمایشی	بازارهای پیش‌بینی صرافی

---

🏗️ معماری سیستم

graph TD
    A[📊 ارائه‌دهندگان داده] --> B[🔄 دریافت‌کننده داده]
    B --> C[⚙️ لایه یکسان‌سازی]
    C --> D[🔍 تطبیق‌دهنده رویدادها]
    D --> E[✔️ بررسی‌کننده قوانین]
    E --> F[🧮 موتور شناسایی آربیتراژ]
    F --> G[💾 ذخیره‌سازی فرصت‌ها]
    G --> H[🌐 API وب]
    G --> I[📱 داشبورد]
    G --> J[💻 رابط خط فرمان]
    K[🗄️ PostgreSQL] <--> G
    L[⚡ Redis] <--> G

Loading

📦 اجزای اصلی

جزء	وظیفه	توضیح
Providers	دریافت داده	اتصال به سایت‌های مختلف و دریافت قیمت‌ها
Normalization	یکسان‌سازی	تبدیل فرمت‌های مختلف به یک فرمت استاندارد
Matcher	تطبیق	پیدا کردن رویدادهای مشابه در سایت‌های مختلف
Arbitrage Engine	محاسبه سود	تشخیص فرصت‌های سودآوری و محاسبه میزان سود
Storage	ذخیره‌سازی	پایگاه داده برای نگهداری اطلاعات
API	سرویس وب	ارائه اطلاعات به داشبورد و برنامه‌های دیگر

---

📐 ریاضیات آربیتراژ

🔢 آربیتراژ دوحالته (Binary)

در بازارهایی که فقط دو نتیجه دارند (مثلاً بله/خیر):

شرط سودآوری: قیمت بله + قیمت خیر < 1.00 دلار

فرمول‌ها:
هزینه کل = قیمت بله + قیمت خیر
سود = 1.00 - هزینه کل
درصد سود = سود ÷ هزینه کل

📝 مثال عملی:

بازار	پیش‌بینی	قیمت
Polymarket	بله، برنده می‌شود	$0.43
Kalshi	خیر، برنده نمی‌شود	$0.51

محاسبات:

هزینه خرید هر دو = 0.43 + 0.51 = $0.94
مبلغ دریافتی قطعی = $1.00
سود خالص = 1.00 - 0.94 = $0.06
درصد سود = 0.06 ÷ 0.94 = 6.38% ✅

یعنی با سرمایه‌گذاری ۹۴ سنتی، قطعاً ۱ دلار دریافت می‌کنید و ۶ سنت سود می‌برید!

---

📥 نصب و راه‌اندازی سریع

🔰 پیش‌نیازها

نرم‌افزار	نسخه حداقل	لینک دانلود
Docker	آخرین نسخه	docker.com
Python	3.12+	python.org
Node.js	18+	nodejs.org

💡 نکته: اگر تازه‌کار هستید، پیشنهاد می‌کنیم از روش Docker استفاده کنید.

---

🐳 روش اول: نصب با Docker (توصیه‌شده)

گام ۱: دریافت کد پروژه

git clone <آدرس-مخزن-شما>
cd arban

گام ۲: اجرای برنامه

docker compose up --build

گام ۳: دسترسی به برنامه

سرویس	آدرس	توضیح
🌐 داشبورد وب	http://localhost:3000	رابط کاربری اصلی
🔌 API Backend	http://localhost:8000	سرویس اصلی برنامه
📚 مستندات API	http://localhost:8000/docs	مستندات تعاملی Swagger

---

💻 روش دوم: نصب محلی (برای توسعه‌دهندگان)

🔧 نصب Backend

cd backend
python -m venv venv
source venv/bin/activate  # در ویندوز: venv\Scripts\activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

🎨 نصب Frontend

cd frontend
npm install
npm run dev

---

⚙️ تنظیمات و پیکربندی

فایل .env را ایجاد کنید:

cp .env.example .env

سپس فایل .env را ویرایش کنید:

# 🏷️ محیط اجرایی
APP_ENV=development

# 🗄️ تنظیمات پایگاه داده
DATABASE_URL=postgresql+asyncpg://arban:arban@postgres:5432/arban
REDIS_URL=redis://redis:6379/0

# ⏱️ تنظیمات اسکن
SCAN_INTERVAL_SECONDS=5          # هر چند ثانیه قیمت‌ها بررسی شوند
MAX_QUOTE_AGE_SECONDS=5          # حداکثر سن مجاز قیمت‌ها

# 💰 حداقل سود مورد انتظار
MIN_ARBITRAGE_ROI=0.5            # حداقل درصد سود ناخالص
MIN_NET_ROI=0.25                 # حداقل درصد سود خالص

# 🔌 فعال/غیرفعال کردن بازارها
POLYMARKET_ENABLED=true
KALSHI_ENABLED=true
LIMITLESS_ENABLED=true
CRYPTO_COM_ENABLED=true

# 💸 نرخ کارمزدها
POLYMARKET_FEE_RATE=0
KALSHI_FEE_RATE=0
LIMITLESS_FEE_RATE=0
CRYPTO_COM_FEE_RATE=0
NETWORK_FEE_ESTIMATE=0

📋 توضیح تنظیمات مهم

تنظیم	مقدار پیش‌فرض	توضیح
SCAN_INTERVAL_SECONDS	5	فاصله زمانی بین هر بار بررسی قیمت‌ها
MIN_ARBITRAGE_ROI	0.5	حداقل درصد سودی که نمایش داده می‌شود
POLYMARKET_ENABLED	true	فعال یا غیرفعال کردن بازار Polymarket

---

🖥️ راهنمای استفاده

🎛️ رابط خط فرمان (CLI)

# 🔍 جستجوی فرصت‌های جدید
python -m arban scan

# 📋 نمایش لیست بازارها
python -m arban markets

# 💰 نمایش فرصت‌های سودآوری با حداقل سود 1%
python -m arban opportunities --min-roi 1.0

# 🏥 بررسی سلامت بازارها
python -m arban health

🌐 داشبورد وب

داشبورد وب آربان دارای بخش‌های مختلفی است:

• 📊 کارت‌های خلاصه وضعیت: تعداد فرصت‌های فعال، بهترین نرخ سود، وضعیت سلامت
• 📋 جدول فرصت‌ها: نام رویداد، نوع آربیتراژ، درصد سود، میزان نقدینگی
• 🔍 نمای جزئیات: جزئیات هر پایه معامله، سرمایه‌گذاری پیشنهادی، کارمزدها
• 🏥 وضعیت ارائه‌دهندگان: نمایش لحظه‌ای وضعیت اتصال به هر بازار

🎭 حالت نمایشی (Demo Mode)

python scripts/seed_demo_data.py

این اسکریپت ۳ سناریوی نمونه ایجاد می‌کند:

1. آربیتراژ دوحالته: YES=$0.43, NO=$0.51 → سود 6.38%
2. بدون آربیتراژ: YES=$0.52, NO=$0.51 → بدون فرصت سود
3. آربیتراژ سه‌حالته: برد A=$0.40, مساوی=$0.30, برد B=$0.25 → سود 5.26%

---

🔌 نقاط انتهایی API

🏥 سلامت سیستم

GET /health                # بررسی سلامت کلی
GET /health/providers      # بررسی سلامت ارائه‌دهندگان

📊 بازارها

GET /api/v1/markets        # لیست همه بازارها
GET /api/v1/markets/{id}   # جزئیات یک بازار خاص

💰 فرصت‌های آربیتراژ

GET /api/v1/opportunities                  # همه فرصت‌ها
GET /api/v1/opportunities/{id}             # جزئیات یک فرصت
?provider=polymarket&sport=football&minimum_roi=1.0&status=active

---

🧪 تست و اعتبارسنجی

# اجرای همه تست‌ها
pytest

# با گزارش پوشش کد
pytest --cov=backend/app

# فقط تست‌های واحد
pytest backend/app/tests/unit

# بررسی انواع (Type checking)
mypy backend/app

# بررسی سبک کد (Linting)
ruff check .
black --check .

---

📁 ساختار پروژه

arban/
├── 📄 README.md              # همین فایل راهنما
├── 📜 LICENSE                # مجوز استفاده
├── 🤝 CONTRIBUTING.md        # راهنمای مشارکت
├── 🔒 SECURITY.md            # نکات امنیتی
├── ⚙️ .env.example           # نمونه فایل تنظیمات
├── 🐳 docker-compose.yml     # تنظیمات Docker
├── 📦 Dockerfile             # فایل ساخت Docker
├── 🛠️ Makefile               # دستورات سریع
│
├── 🖥️ backend/               # کدهای سمت سرور
│   ├── app/
│   │   ├── main.py           # نقطه شروع برنامه
│   │   ├── config.py         # تنظیمات
│   │   ├── api/              # مسیرهای API
│   │   ├── models/           # مدل‌های داده
│   │   ├── providers/        # اتصال به بازارها
│   │   ├── matching/         # الگوریتم‌های تطبیق
│   │   ├── arbitrage/        # موتور محاسبات
│   │   └── tests/            # تست‌ها
│   └── requirements.txt      # وابستگی‌های پایتون
│
├── 🎨 frontend/              # کدهای سمت کاربر
│   ├── app/                  # صفحات Next.js
│   ├── components/           # کامپوننت‌های React
│   └── package.json          # وابستگی‌های جاوااسکریپت
│
├── 📜 scripts/               # اسکریپت‌های کمکی
│   ├── seed_demo_data.py     # ایجاد داده‌های نمونه
│   └── run_scanner.py        # اجرای اسکنر
│
└── 📚 docs/                  # مستندات
    ├── architecture.md       # معماری سیستم
    ├── arbitrage-math.md     # ریاضیات آربیتراژ
    └── glossary-fa.md        # واژه‌نامه فارسی

---

📚 مستندات بیشتر

• 🏗️ معماری سیستم - طراحی کلی سیستم
• 📐 ریاضیات آربیتراژ - فرمول‌ها و محاسبات
• 🔍 الگوریتم‌های تطبیق - روش‌های شناسایی رویدادهای مشابه
• 📖 واژه‌نامه فارسی - اصطلاحات تخصصی

---

📄 مجوز استفاده

این پروژه تحت مجوز MIT منتشر شده است. برای اطلاعات بیشتر، فایل LICENSE را مطالعه کنید.

---

⚖️ سلب مسئولیت

⚠️ هشدار مهم:

• آربان صرفاً برای اهداف آموزشی و اطلاع‌رسانی طراحی شده است و مشاوره مالی ارائه نمی‌دهد.
• تمام تصمیمات سرمایه‌گذاری بر عهده خود کاربر است.
• کاربران مسئول رعایت قوانین و مقررات کشور خود هستند.
• گذشته تضمینی برای آینده نیست و سودهای قبلی نشان‌دهنده نتایج آینده نیستند.
• همیشه قبل از هرگونه سرمایه‌گذاری، تحقیقات خود را انجام دهید (DYOR).

---

🌟 اگر از آربان خوشتان آمد، ستاره‌دار کردن پروژه ما را فراموش نکنید!

ساخته شده با ❤️ توسط جامعه متن‌باز

⭐ ستاره دادن به پروژه • 🐛 گزارش مشکل • 💡 پیشنهاد ویژگی