مراقب الفروق والتمويل بلغة Python
باختصار
- المراقب برنامج طرفية: كل
meta.freshness_secثانية يسحب مجموعتي/arbitrage/spot-spotو/funding/spreadكاملتين، ويرشّح الصفوف بالعتبات، ويطبع الجداول ويضيفها إلى ملف CSV. - تُطلب المجموعتان بلا مرشحات، فتأتيان مع
ETag: الإعادة بـIf-None-Matchقبل اللقطة التالية تعيد304دون استهلاك الحصة. عند429و503ينتظر العميلRetry-Afterثانية. - ما يتبقى بعد رسوم taker المفترضة 0.1% لكل ساق هو الفرق ناقص 0.2 نقطة مئوية. على Pro وMax يعيد المراقب فحص أفضل ثلاثة أزواج بدفتر أوامر بقيمة 1,000 دولار.
- الحد الأعلى 86,400 استدعاء لكل 30 يوماً على Trial، أي 17.28% من الحصة، و1,296,000 على Pro مع فحص الدفاتر، أي 25.92%.
مراقب الفروق والتمويل برنامج يسحب في حلقة الفروق بين المنصات وفروق التمويل، ويُبقي الصفوف فوق عتباتك ويطبعها جدولاً في الطرفية. المراقب في هذا الدرس نحو 170 سطراً بلغة Python: بياناته من Genesis API، وسجله في ملف CSV، ولا يفتح صفقات. ولا يرسل تنبيهات أيضاً؛ البوت الذي يرسل رسائل Telegram مشروح في بوت أربيتراج العملات الرقمية بلغة Python.
خطة الاستطلاع: نقاط النهاية والتواتر واستهلاك الاستدعاءات
| الطلب | ماذا يعطي | متى |
|---|---|---|
/account/usage | الخطة وfreshness_sec وrps_limit | عند البدء، لا يستهلك الحصة |
/arbitrage/spot-spot | أزواج Spot – Spot | في كل دورة، المجموعة كاملة |
/funding/spread | أفضل أزواج المنصات بالتمويل | في كل دورة، المجموعة كاملة |
/orderbooks/spreads/spot-spot | Order-book Δ لـ 1,000 دولار | Pro وMax، ثلاثة أزواج في الدورة |
يحدد meta.freshness_sec التواتر: تحصل خطتك على لقطة جديدة كل 60 ثانية على Trial، و30 على Start، و10 على Pro، و5 على Max. الاستطلاع الأسرع يعيد اللقطة نفسها بالـ meta.updated_at نفسه. حقول المجموعتين في وثائق Spot — Spot وفرق التمويل.
| الخطة والحصة | الفاصل | الطلبات في الدورة | الاستدعاءات لكل 30 يوماً |
|---|---|---|---|
| Trial، 500K | 60 ث | 2 | 86,400 |
| Start، 2M | 30 ث | 2 | 172,800 |
| Pro، 5M | 10 ث | 5 | 1,296,000 |
| Max، 10M | 5 ث | 5 | 2,592,000 |
على Trial: 2 × 86,400 / 60 × 30 = 86,400 استدعاء، أي 17.28% من الحصة. على Pro تنضم ثلاثة فحوص دفاتر إلى المجموعتين: 5 × 86,400 / 10 × 30 = 1,296,000 استدعاء، أي 25.92% من 5M. قواعد الحصة في دليل حدود Genesis API.
يلتزم المراقب بحد الطلبات في الثانية بفاصل 1.1 / rps_limit ثانية بين الطلبات: 1.1 ثانية على Trial و0.22 على Pro. دورة من خمسة طلبات على Pro تستغرق نحو ثانية.
الإعدادات وعميل بـ ETag وRetry-After
تشكّل كتل الكود السبع في هذا الدرس ملف monitor.py كاملاً: احفظها واحدة بعد أخرى في ملف واحد. العتبات في الإعدادات توضيحية؛ اضبطها بحسب رسومك وأحجامك.
import csv
import os
import time
from datetime import datetime, timezone
import requests
API = "https://api.genesisarbitrage.com/v1"
MIN_SPREAD = 1.0 # الفرق في الصف من 1%
MIN_VOLUME = 50_000 # حجم 24 ساعة على المنصتين من 50,000 دولار
MIN_FUNDING = 0.05 # فرق التمويل من 0.05%
FEE = 0.1 # رسوم taker المفترضة لكل ساق، %
TOP = 10 # عدد الصفوف في كل جدول
BOOK_TOP = 3 # أزواج تُفحص بالدفاتر في كل دورة، Pro/Max
BOOK_USD = 1000 # حجم فحص دفتر الأوامر، دولار
CSV_FILE = "monitor.csv"
api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # الطلب -> (ETag، جسم الاستجابة)
stats = {200: 0, 304: 0} # عدد استجابات 200 و304 التي وصلت
pace = {"gap": 1.1, "last": 0.0} # الفاصل بين الطلبات، ث
المفتاح يأتي من متغير البيئة GENESIS_API_KEY ويُرسل في ترويسة X-API-Key مع كل طلب، ولا يوضع في الرابط أبداً. يحفظ cache الـ ETag وجسم آخر استجابة لكل طلب، ويعدّ stats استجابات 200 و304، ويتذكر pace وقت إرسال آخر طلب.
def get(path, params=None):
"""GET إلى Genesis API: ضبط الوتيرة وETag وإعادة المحاولة بحسب Retry-After."""
key = (path, tuple(sorted((params or {}).items())))
for _ in range(4): # طلب واحد وحتى ثلاث إعادات
wait = pace["last"] + pace["gap"] - time.monotonic()
if wait > 0:
time.sleep(wait) # لا يزيد على rps_limit طلب في الثانية
pace["last"] = time.monotonic()
hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
r = api.get(API + path, params=params, headers=hdr,
timeout=15)
if r.status_code == 304: # اللقطة لم تتغير
stats[304] += 1
return cache[key][1]
if r.status_code in (429, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 60: # هكذا تبدو الحصة المستنفدة
raise SystemExit(f"الحصة مستنفدة: انتظر {wait} ث")
time.sleep(wait)
continue
r.raise_for_status() # 400 و401 و403: الإعادة لن تفيد
stats[200] += 1
body = r.json()
if "ETag" in r.headers: # فقط مجموعات البيانات الكاملة تحمله
cache[key] = (r.headers["ETag"], body)
return body
raise RuntimeError("API مشغول، سنعيد المحاولة في الدورة التالية")
ETag هو وسم إصدار للّقطة. ترسله get في ترويسة If-None-Match، وما دامت اللقطة لم تتغير يردّ الخادم بـ 304 بلا جسم: لا تُستهلك الحصة، وتعيد الدالة الجسم السابق. عند 429 و503 تنتظر Retry-After ثانية ثم تعيد المحاولة، والانتظار الأطول من دقيقة يعني أن حصة الفترة نفدت، فيتوقف المراقب. رموز الأخطاء وقواعد الإعادة في دليل استجابات Genesis API وأخطاؤه.
الفروق والتمويل: التحميل والعتبات والفرز
def spot_rows():
"""أزواج Spot – Spot فوق العتبات، ويمكن تحويل العملة."""
body = get("/arbitrage/spot-spot") # بلا مرشحات: لها ETag
rows = []
for x in body["data"]:
vol = min(x["volume_24h_buy"] or 0, x["volume_24h_sell"] or 0)
if (x["spread_pct"] >= MIN_SPREAD and vol >= MIN_VOLUME
and x["withdraw_enabled_buy"]
and x["deposit_enabled_sell"]):
rows.append({**x, "net": net(x["spread_pct"])})
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
return rows[:TOP], body["meta"]
def funding_rows():
"""العملات ذات أوسع فرق تمويل."""
body = get("/funding/spread") # بلا مرشحات: لها ETag
rows = [x for x in body["data"] if x["spread_pct"] >= MIN_FUNDING]
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
return rows[:TOP], body["meta"]
تُطلب مجموعتا البيانات بلا معاملات: الاستجابة لطلب فيه min_spread أو coin أو مرشح آخر تُبنى لذلك الطلب وتأتي بلا ETag. يطبّق المراقب العتبات بنفسه: فرق لا يقل عن MIN_SPREAD، وحجم 24 ساعة لا يقل عن MIN_VOLUME على المنصتين، والسحب مفتوح على منصة الشراء والإيداع مفتوح على منصة البيع. الحجم null يُحتسب صفراً، فلا يمرّ هذا الصف.
تُفرز الصفوف حسب spread_pct تنازلياً، وأول TOP منها تدخل الجدول. في /funding/spread تُقارن عتبة MIN_FUNDING مع spread_pct لأفضل زوج.
ما يتبقى بعد الرسوم وفحص دفتر الأوامر
def net(spread_pct):
"""ما يتبقى بعد رسمي taker، تقريباً، %"""
return round(spread_pct - 2 * FEE, 4)
def book_net(row):
"""ما يتبقى بعد BOOK_USD من الدفتر والرسوم. Pro وMax."""
body = get("/orderbooks/spreads/spot-spot",
{"coin": row["coin"], "volume": BOOK_USD})
pair = (row["exchange_buy"], row["exchange_sell"])
for x in body["data"]:
if (x["exchange_buy"], x["exchange_sell"]) != pair:
continue
od = x["order_delta"]
if od["status"] != "ok":
return od["status"] # no_book أو exhausted
return net(od["spread_pct"])
return "gone" # الزوج خرج من مجموعة البيانات
رسوم taker المفترضة 0.1% على الشراء و0.1% على البيع تخفض الفرق بنحو 0.2 نقطة مئوية: زوج بفرق 1.62% يترك 1.62 − 2 × 0.1 = 1.42%. ضع رسوم منصاتك في FEE (maker وtaker). رسوم السحب غير موجودة في استجابات API، والمراقب لا يحتسبها.
على Pro وMax تعيد book_net فحص أفضل ثلاثة أزواج بدفاتر الأوامر: الطلب /orderbooks/spreads/spot-spot مع عملة الزوج وvolume=1000 يعيد صفوف تلك العملة مع كائن order_delta، وتأخذ الدالة الصف الذي له زوج المنصات نفسه (Order-book Δ). إن لم يوجد دفتر أو نفد، تحصل بدل الرقم على الحالة no_book أو exhausted. الطلب مع coin بلا ETag ويكلّف استدعاءً دائماً، ولهذا تجري الدورة ثلاثة طلبات فقط، يحددها BOOK_TOP.
جدول الطرفية
def show(spot, s_meta, fund, f_meta):
now = time.time()
s_age = now - s_meta["updated_at"]
f_age = now - f_meta["updated_at"]
print(f"\nSpot – Spot، عمر اللقطة {s_age:.0f} ث")
print(f"{'العملة':<8}{'شراء → بيع':<20}"
f"{'الفرق':>7}{'-الرسوم':>9}{'الدفتر':>11}")
for x in spot:
pair = f'{x["exchange_buy"]} → {x["exchange_sell"]}'
book = x.get("book", "—")
if isinstance(book, float):
book = f"{book:.2f}"
print(f'{x["coin"]:<8}{pair:<20}{x["spread_pct"]:>7.2f}'
f'{x["net"]:>9.2f}{book:>11}')
print(f"\nالتمويل، عمر اللقطة {f_age:.0f} ث")
for x in fund:
b = x["best"]
legs = (f'{b["exchange_1"]} {b["interval_1"] or "?"} / '
f'{b["exchange_2"]} {b["interval_2"] or "?"}')
print(f'{x["coin"]:<8}{legs:<27}{x["spread_pct"]:>8.4f} %')
print(f"استجابات 200: {stats[200]}، و304: {stats[304]}")
يعرض الجدول الأول العملة وزوج المنصات وspread_pct وما يتبقى بعد الرسوم وما يتبقى بعد الدفتر؛ والشرطة تعني أن الدفتر لم يُفحص. يعرض الثاني أفضل زوج منصات بالتمويل مع فواصل التمويل وspread_pct. فوق الجدولين عمر اللقطة، أي الوقت الحالي ناقص meta.updated_at، وتحتهما عدد استجابات 200 و304 منذ البدء.
سجل CSV
def save(spot, fund):
"""يضيف الدورة إلى CSV: الوقت ومجموعة البيانات والزوج والفروق."""
new = not os.path.exists(CSV_FILE)
ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
with open(CSV_FILE, "a", newline="", encoding="utf-8") as f:
w = csv.writer(f)
if new:
w.writerow(["time_utc", "dataset", "coin", "leg_1",
"leg_2", "spread_pct", "net_pct", "book"])
for x in spot:
w.writerow([ts, "spot-spot", x["coin"], x["exchange_buy"],
x["exchange_sell"], x["spread_pct"], x["net"],
x.get("book")]) # None تصبح خلية فارغة
for x in fund:
b = x["best"]
w.writerow([ts, "funding", x["coin"], b["exchange_1"],
b["exchange_2"], x["spread_pct"], None, None])
جدول الطرفية يبقى حتى الدورة التالية، أما monitor.csv فيحفظ كل دورة: ترى منه كم يدوم الزوج وفي أي ساعات يظهر. وحدة csv جزء من المكتبة القياسية في Python. افتح الملف بـ newline="" كما تشترط وثائق الوحدة، وإلا ظهر \r زائد في الملف على الأنظمة التي تستخدم نهايات الأسطر \r\n.
عمود book يحمل ما يتبقى بعد الدفتر بالنسبة المئوية أو الحالة exhausted أو no_book. تكتب الوحدة None خلية فارغة، فيبقى العمود فارغاً لصفوف التمويل والأزواج التي لم تُفحص. الأوقات بتوقيت UTC.
الحلقة الرئيسية
def main():
usage = get("/account/usage")["data"] # لا يستهلك الحصة
books = usage["plan"] in ("pro", "max")
pace["gap"] = 1.1 / usage["rps_limit"]
print("الخطة", usage["plan"], "| لقطة كل",
usage["freshness_sec"], "ث | دفاتر الأوامر:",
"نعم" if books else "لا")
pause = usage["freshness_sec"]
while True:
try:
spot, s_meta = spot_rows()
fund, f_meta = funding_rows()
if books:
for x in spot[:BOOK_TOP]:
x["book"] = book_net(x)
show(spot, s_meta, fund, f_meta)
save(spot, fund)
pause = s_meta.get("freshness_sec", pause)
except requests.HTTPError as e:
if e.response.status_code < 500:
raise # المفتاح أو الخطة أو المعاملات: الإعادة لن تفيد
print("خطأ في الخادم، سنعيد المحاولة:", e)
except (requests.RequestException, RuntimeError) as e:
print("لا استجابة، سنعيد المحاولة:", e)
time.sleep(pause) # أسرع من freshness_sec = اللقطة نفسها
if __name__ == "__main__":
try:
main()
except KeyboardInterrupt:
print("\nتوقف المراقب، السجل في", CSV_FILE)
عند البدء يستدعي المراقب /account/usage: الطلب لا يستهلك الحصة ويعيد الخطة وfreshness_sec وrps_limit (الاستخدام). تحدد الخطة هل تُفحص دفاتر الأوامر، ويحدد rps_limit الفاصل بين الطلبات. يتحمل المراقب أعطال الشبكة وأخطاء 5xx حتى الدورة التالية، بينما توقفه أخطاء 4xx (مفتاح خاطئ أو اشتراك منتهٍ أو خطة بلا نقطة النهاية).
كيف تشغّله وتقرأ المخرجات
python3 --version # مطلوب Python 3.10 أو أحدث
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
python3 monitor.py
مخرجات الخطة Pro، مثال توضيحي:
الخطة pro | لقطة كل 10 ث | دفاتر الأوامر: نعم
Spot – Spot، عمر اللقطة 4 ث
العملة شراء → بيع الفرق -الرسوم الدفتر
KLM ByBit → Gate 1.62 1.42 0.86
XYZ MEXC → Gate 1.24 1.04 exhausted
ABC BingX → HTX 1.12 0.92 0.31
QRS Gate → OKX 1.05 0.85 —
التمويل، عمر اللقطة 4 ث
XYZ MEXC 4h / Bitget 8h 0.0600 %
ABC Hyper 1h / CoinEx 8h 0.0500 %
استجابات 200: 6، و304: 0
KLM: فرق الصف 1.62%، وبعد الرسمين 1.42%، وبعد 1,000 دولار من دفتر الأوامر مع الرسوم 0.86%. نفد دفتر XYZ عند 1,000 دولار: مع زوج كهذا تقلّل الحجم أو تتجاوزه. QRS هو الصف الرابع، فلم يُطلب دفتره. يبيّن جدول التمويل كم مرة تسوّي كل منصة: Hyper (اسم Hyperliquid في الاستجابات) كل ساعة وCoinEx كل 8 ساعات. اضغط Ctrl+C لإيقاف المراقب.
من فحوص الأزواج الأربعة في الدرس 3 ينفّذ المراقب فجوة السعر والتحويل بنفسه، ودفتر الأوامر على Pro وMax، ويعرض الحداثة فوق الجدول. أما العقد ورسم السحب فتتحقق منهما أنت.
تدرّب
شغّل المراقب
يعرض أول سطر في المخرجات الخطة وخطوة اللقطة وهل تُفحص الدفاتر؛ قارنها بملفك الشخصي.
حرّك العتبة
اضبط
MIN_SPREAD = 0.5وانظر كم من الصفوف الجديدة يبقى فيها عمود «الرسوم» فوق الصفر.أضف مجموعة بيانات
انسخ
spot_rowsلـ/arbitrage/futures-futures: صيغة الصفوف نفسها. احذف فحص الإيداع والسحب للعقود، فلا عملة تنتقل بين المنصات هناك.افحص الاستخدام
بعد ساعة استدعِ
/account/usageوقارنcalls_usedبالتقدير: على Trial هذا حتى 2 × 60 = 120 استدعاءً في الساعة.ابحث عن الأزواج الدائمة
افتح
monitor.csvفي جدول بيانات وعُدّ كم دورة متتالية دام كل زوج منصات.
مخاطر الأتمتة، من البيانات القديمة والأخطاء إلى المفاتيح ووكلاء AI، في الدرس 5، والاستطلاع الاقتصادي بالمرشحات والضغط وETag في مقال استطلاع API دون بلوغ الحدود.
أسئلة وأجوبة
بماذا يختلف المراقب عن بوت المراجحة؟
المراقب يطبع جدولاً ويحفظ السجل؛ أما البوت فيرسل تنبيهات عن الأزواج الجديدة ويصمت عن المكررة. يشتركان في كود الطلب والتصفية، وبوت Telegram مشروح في «بوت أربيتراج العملات الرقمية بلغة Python».
هل يمكنني الاستطلاع أسرع من freshness_sec؟
لن تحصل على بيانات جديدة: خطتك تتلقى لقطة كل freshness_sec ثانية. الطلب بلا مرشحات قبل اللقطة التالية يعيد 304 مجاناً، بينما الطلب المرشَّح يستهلك استدعاءً لنفس البيانات.
لماذا يعرض عمود «الدفتر» شرطة؟
Order-book Δ متاح على Pro وMax فقط، ويطلبه المراقب لأفضل ثلاثة أزواج (BOOK_TOP). على Trial وStart تعيد نقطة النهاية 403 plan_restricted، فلا يستدعيها المراقب.