بيانات سوق العملات الرقمية لوكلاء الذكاء الاصطناعي: API واستدعاء الدوال وMCP وllms.txt
باختصار
- يعرف النموذج اللغوي السوق فقط حتى تاريخ انتهاء بيانات تدريبه. أما الأسعار والسبريدات ومعدلات التمويل الحالية فيحصل عليها عبر الأدوات: يختار النموذج الاستدعاء ووسائطه، وينفّذ كودك طلب API.
- تُصمَّم الأداة فوق API بيانات السوق ضيقة: نقطة نهاية واحدة، والفلاتر في الوسائط، وعدة صفوف بالحقول المهمة، ووقت البيانات في النتيجة. تُؤخذ تعريفات الأدوات من مواصفة OpenAPI، ويوصل MCP الأدوات نفسها بأي عميل متوافق.
- يبقى المفتاح على خادمك، ولا يصل نص البيانات الخارجية إلى النموذج إلا داخل نتائج الأدوات، ويؤكد إنسان كل صفقة. Genesis API للقراءة فقط وينشر openapi.json وllms-full.txt وكتالوج API للوكلاء.
يحصل وكيل الذكاء الاصطناعي على بيانات سوق العملات الرقمية عبر الأدوات: يقرر النموذج أي بيانات يحتاج، فيستدعي كودك API العملات الرقمية ويعيد إليه JSON قصيراً فيه الأسعار والسبريدات ووقت بناء البيانات. تُوصَل الأدوات إما عبر استدعاء الدوال (function calling) في API النموذج، وإما عبر خادم MCP، وكلاهما يعمل فوق REST API عادي.
الأمثلة مبنية على Genesis API، وهو REST API للقراءة فقط ببيانات CEX وDEX وأونتشين وأسواق التنبؤ. عن API العملات الرقمية عموماً وكيفية المقارنة بينها، راجع API العملات الرقمية: أنواع واجهات بيانات السوق وكيف تختار.
لماذا لا يعرف النموذج الأسعار الحالية
يُدرَّب النموذج اللغوي على نصوص جُمعت حتى تاريخ معين، وهو تاريخ انتهاء معرفته. لا يعرف شيئاً عن الإدراجات والمعدلات والأسعار بعد هذا التاريخ، وسعر BTC الذي يذكره من الذاكرة هو رقم من نص تدريب لا يُعرف تاريخه. كما لا يعرف النموذج الوقت الحالي ما لم تمرّره في الطلب.
في الأربيتراج لا قيمة لإجابة من الذاكرة: السبريد بين البورصات يعيش دقائق، ومعدل التمويل يتغير في كل فترة تسوية، كل 8 أو 4 أو ساعة واحدة. الأرقام الحيّة تأتي من الأداة فقط: مرجع API في السياق يعلّم النموذج المسارات والوسائط، لكنه لا يحتوي أسعاراً.
| ما يحتاجه النموذج | من أين يأتي | مثال |
|---|---|---|
| مسارات API ووسائطه وحقوله | مرجع في السياق | llms-full.txt, openapi.json |
| الأسعار والسبريدات والمعدلات | استدعاء أداة | GET /funding/spread?coin=TON |
| الوقت الحالي وعمر البيانات | موجّه النظام ونتيجة الأداة | updated_at, age_sec |
كيف يعمل استدعاء الدوال
استدعاء الدوال هو وضع يعيد فيه النموذج اسم أداة ووسائطها بدل النص، وينفّذ كودك الطلب. مثال توضيحي: يسأل مستخدم أين يوجد الآن أكبر فرق تمويل لعملة TON. الاستدعاء والنتيجة بشكل تخطيطي:
{
"tool_call": {
"name": "get_funding",
"arguments": { "coin": "TON" }
},
"tool_result": {
"updated_at": 1794675860,
"age_sec": 12,
"rows": [
{
"coin": "TON",
"spread_pct": 0.04,
"pair": ["Bitget", "Bybit"],
"funding_pct": [0.05, 0.01],
"interval": ["8h", "8h"]
}
]
}
}
- يرسل التطبيق إلى النموذج السؤال وتعريفات الأدوات: الاسم والغرض ومخطط الوسائط بصيغة JSON Schema.
- يعيد النموذج استدعاء
get_fundingبالوسائط{"coin": "TON"}. - يتحقق كودك من الوسائط، ويرسل
GET /funding/spread?coin=TONمع الترويسةX-API-Key، ويقتطع الاستجابة. - تعود النتيجة إلى النموذج فيجيب: Bitget وBybit، 0.05% و0.01% لكل 8 ساعات، والفرق 0.04%، وعمر البيانات 12 ثانية.
- إذا لم تكفِ البيانات، يستدعي النموذج الأداة التالية.
لا ينفّذ النموذج أي طلبات شبكة ولا يرى مفتاح API أبداً. تختلف أسماء الحقول بحسب API النموذج: في Claude API يوجد المخطط في input_schema، ويصل الاستدعاء ككتلة tool_use، وتعود النتيجة ككتلة tool_result، بينما يسمّي MCP المخطط inputSchema. وفي الحالتين هو JSON Schema.
كيف تصمّم الأدوات فوق API بيانات السوق
أداة واحدة لمهمة واحدة
يختار النموذج الأداة من وصفها، لذلك تعمل الأدوات الضيقة بموثوقية أعلى من call_api(path, params) العامة. الاختيار بين خمس وسبع أدوات مبنية لمهام الوكيل أسهل من الاختيار بين 37 عملية في المواصفة.
| الأداة | نقطة نهاية Genesis API | الخطط |
|---|---|---|
get_spreads | /arbitrage/spot-spot | الكل |
get_funding | /funding/spread | الكل |
get_prediction_arbs | /predictions/arbitrage | Start وPro وMax |
get_book | /orderbooks/book | Pro وMax |
يذكر الوصف متى تُستدعى الأداة وبأي وحدات الأرقام: في Genesis API السبريدات والمعدلات نسب مئوية، فالقيمة 0.92 تعني 0.92%.
الفلاتر كوسائط، والتحقق في الكود
تصبح فلاتر API مثل coin وexchange وmin_spread وسائط للأداة. يملؤها النموذج من السؤال، ويتحقق المعالج منها بقائمة مسموحة من الوسائط والأنواع والقيم، وتحدد enum القيم المسموحة: في /orderbooks/book يكون market إما spot أو futures فقط. لا يبني النموذج مسار الطلب أبداً، ويرفض المخطط الحقول الزائدة (additionalProperties: false).
لا تأتي الاستجابة المفلترة مع ETag، لذلك يكلّف كل استطلاع مفلتر متكرر استدعاءً: لا يوجد 304 مجاني. إذا احتاج الوكيل عشرات العملات، فالأرخص أن تحتفظ بمجموعة البيانات الكاملة غير المفلترة محلياً وتستطلعها بـ If-None-Match.
نتائج مضغوطة
مثال توضيحي: تغطي استجابة /funding/spread الكاملة غير المفلترة 1,000 عملة. لعملة على 10 بورصات يحتوي الصف الواحد على 2 + 10 + 8 × 5 = 52 قيمة: العملة والسبريد و10 حقول لأفضل زوج في best و5 حقول لكل من البورصات الثماني الأخرى في others. الاستجابة كلها 1,000 × 52 = 52,000 قيمة، بينما تحتاج الإجابة عن أفضل الأزواج إلى 5 صفوف من 8 قيم: 5 × 8 = 40.
تدخل تعريفات الأدوات ونتائجها في السياق في كل خطوة: يحاسب Claude API عليها كرموز إدخال.
وقت البيانات وحداثتها
يضع المعالج في النتيجة updated_at، وهو وقت بناء البيانات من meta.updated_at بثواني unix، وage_sec. عندها يستطيع النموذج أن يقول «عمر البيانات 12 ثانية» بدل أن يقدّم سبريد الأمس على أنه حالي.
حداثة البيانات تحددها الخطة: يتراوح meta.freshness_sec من 60 ث في Trial إلى 5 ث في Max. قبل مرور هذه الفترة يعيد API اللقطة نفسها، لذلك يخزّن المعالج الاستجابة مؤقتاً لمدة freshness_sec ثانية. لدفاتر الأوامر ساعتها الخاصة: book_ts وage_sec وعلم stale للدفاتر الأقدم من 30 ث.
مثال: أداة get_funding
التعريف أدناه بصيغة MCP؛ وفي Claude API يوضع المحتوى نفسه في input_schema. يطبّق المعالج limit بنفسه: لا يوجد مثل هذا الوسيط في API.
{
"name": "get_funding",
"description": "أين يكون التمويل أعلى أو أدنى: أفضل زوج بورصات",
"inputSchema": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "رمز العملة، مثل TON"
},
"min_spread": {
"type": "number",
"minimum": 0,
"description": "الحد الأدنى للسبريد، %: القيمة 0.05 تعني 0.05%"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "عدد الصفوف المطلوب إعادتها، 5 افتراضياً"
}
},
"additionalProperties": false
}
}
معالج Python: ذاكرة مؤقتة لمدة freshness_sec، وانتظار قصير واحد عند 429 و503، وسجل بلا المفتاح، ونتيجة مضغوطة مع وقت البيانات.
import logging
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"] # المفتاح يبقى على الخادم فقط
cache = {} # معاملات الطلب -> (وقت الاستلام، جسم الاستجابة)
def get_funding(coin=None, min_spread=None, limit=5):
p = {"coin": coin and coin.upper(), "min_spread": min_spread}
p = {k: v for k, v in p.items() if v}
ck = tuple(sorted(p.items()))
got, body = cache.get(ck, (0, None))
if not body or time.time() - got >= body["meta"]["freshness_sec"]:
for attempt in range(2): # 429 و503: انتظار قصير ومحاولة واحدة
r = requests.get(URL, params=p, timeout=10,
headers={"X-API-Key": KEY})
wait = int(r.headers.get("Retry-After", "0"))
if attempt or wait > 5 or r.status_code not in (429, 503):
break
time.sleep(wait)
logging.info("get_funding %s -> %s id=%s", p, r.status_code,
r.headers.get("X-Request-Id")) # سجل بلا المفتاح
if r.status_code != 200:
return {"error": r.status_code} # 401, 403, 429, 503
body = r.json()
cache[ck] = (time.time(), body)
t = body["meta"]["updated_at"]
top = sorted(body["data"], key=lambda x: -x["spread_pct"])
rows = [{"coin": x["coin"], "spread_pct": x["spread_pct"],
"pair": [x["best"]["exchange_1"], x["best"]["exchange_2"]],
"funding_pct": [x["best"]["funding_1_pct"],
x["best"]["funding_2_pct"]],
"interval": [x["best"]["interval_1"],
x["best"]["interval_2"]]}
for x in top[:min(max(int(limit), 1), 10)]]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": rows}
لا ينتظر المعالج فترات أطول من 5 ثوانٍ: بعد نفاد الحصة يشير Retry-After إلى موعد التصفير، وقد يكون بعد أيام. يتلقى النموذج رمز الحالة ويخبر المستخدم بما حدث: 403 تعني plan_restricted، أي نقطة نهاية خارج الخطة (أخطاء Genesis API).
OpenAPI مصدراً لتعريفات الأدوات
OpenAPI معيار لوصف واجهات HTTP بصيغة مقروءة آلياً: تُوصف العملية بـ operationId وsummary قصير ووسائط بمخططاتها. في الإصدار 3.1 يكون Schema Object مجموعة شاملة لـ JSON Schema 2020-12 (مواصفة OpenAPI 3.1)، ويقرأ MCP الحقل inputSchema على أنه JSON Schema 2020-12 افتراضياً. لذلك تنتقل الوسائط إلى الأداة دون تحويل.
يبني السكربت الأدوات من مواصفة Genesis API: يأخذ العمليات المطلوبة، ويتخطى ما هو خارج خطتك بحسب x-genesis-plans، وينقل وسائط الاستعلام والمسار. أما الترويسات فهي من مهام المعالج.
import requests
SPEC = "https://genesisarbitrage.com/openapi.json"
def tools_from_spec(wanted, plan):
"""wanted: operationId -> اسم الأداة؛ plan: trial … max."""
spec = requests.get(SPEC, timeout=15).json()
tools, routes = [], {}
for path, item in spec["paths"].items():
op = item.get("get", {})
name = wanted.get(op.get("operationId"))
if not name or plan not in op.get("x-genesis-plans", []):
continue # غير مطلوبة أو خارج الخطة: 403 plan_restricted
props, required = {}, []
for prm in op.get("parameters", []):
if "$ref" in prm or prm["in"] not in ("query", "path"):
continue # المعالج يرسل X-API-Key وIf-None-Match
props[prm["name"]] = {**prm["schema"],
"description": prm["description"]}
if prm.get("required"):
required.append(prm["name"])
tools.append({
"name": name,
"description": op["description"].split("\n\n")[0],
"inputSchema": {"type": "object", "properties": props,
"required": required,
"additionalProperties": False}})
routes[name] = path # اسم الأداة -> مسار نقطة النهاية
return tools, routes
tools, routes = tools_from_spec({"getFundingSpread": "get_funding",
"getArbitrageSpotSpot": "get_spreads"},
plan="trial")
تتحول getFundingSpread إلى أداة get_funding بالوسيطين coin وmin_spread. إذا مررت كل العمليات تحتفظ Trial بـ 11 من 37، وتحتفظ Start بـ 16. يخزّن القاموس routes مسار كل أداة.
MCP: خادمك الخاص فوق REST API
MCP (Model Context Protocol) معيار مفتوح لربط تطبيقات الذكاء الاصطناعي بالبيانات والأدوات. فتحته Anthropic مفتوح المصدر في 25 نوفمبر 2024 (إعلان Anthropic)، وفي 9 ديسمبر 2025 تبرعت به إلى Agentic AI Foundation، وهي صندوق تابع لـ Linux Foundation (مدونة MCP).
ينشئ التطبيق الذي فيه النموذج، وهو المضيف (host)، عميل MCP واحداً لكل خادم. يعرض الخادم أدوات وموارد وقوالب موجّهات عبر JSON-RPC 2.0: المحلي عبر stdio، والبعيد عبر Streamable HTTP الذي توصي MCP فيه بالحصول على الرموز عبر OAuth (بنية MCP).
| استدعاء الدوال | MCP | |
|---|---|---|
| أين تُعرَّف الأدوات | في الطلب إلى API النموذج | على الخادم؛ يجلبها العميل بـ tools/list |
| من ينفّذ الاستدعاء | كود تطبيقك | خادم MCP، عند طلب tools/call |
| أين يعمل | في التطبيق الذي كتبت فيه الحلقة | في أي عميل يدعم MCP |
يتطلب تغليف REST API بخادم MCP أربع خطوات:
اختر العمليات
خذ 3–7 عمليات لمهمة الوكيل؛ وابنِ أسماء الأدوات وأوصافها ووسائطها من OpenAPI، كما في السكربت أعلاه.
أعد القائمة عند tools/list
يعيد الخادم
nameوdescriptionوinputSchemaلكل أداة.عالج tools/call
تحقق من الوسائط، ونفّذ طلب GET بالمفتاح من بيئة الخادم، وأعد JSON مضغوطاً في كتلة
content. أعد خطأ API معisError: true: يستخدمه النموذج لتصحيح وسائطه.اختر وسيلة النقل
عبر stdio يعمل الخادم على جهازك ولا يغادره المفتاح. ضع خادم Streamable HTTP البعيد خلف مصادقة، وإلا فسيستهلك كل من يعرف الرابط حصتك.
تتوفر حزم MCP SDK الرسمية لـ 10 لغات، من Python وTypeScript إلى Go وRust (قائمة SDK).
llms.txt وllms-full.txt
llms.txt ملف Markdown في المسار /llms.txt يساعد النماذج اللغوية على استخدام موقع. اقترح Jeremy Howard الصيغة في 3 سبتمبر 2024 (llmstxt.org): الجزء الوحيد المطلوب هو H1 بالاسم، يليه ملخص في اقتباس وأقسام بروابط إلى نسخ Markdown من الصفحات.
لا يعرّف الاقتراح الملف llms-full.txt: يُستخدم الاسم لمجموعة توثيق كاملة في ملف Markdown واحد، وينشره موقع توثيق MCP مثلاً. لا يحتاج النموذج إلى اتباع الروابط، فالمرجع كله يصل إلى سياقه.
أمان الوكيل
احفظ المفتاح في متغير بيئة على الخادم: يجب ألا يظهر في الموجّهات أو المتصفحات أو السجلات. مفتاح Genesis API للقراءة فقط، فلا يستطيع تنفيذ أمر ولا سحب أموال، وتسريبه يكلّفك الحصة. استبدل المفتاح المسرَّب بـ إعادة إصدار في ملفك الشخصي (حفظ المفاتيح).
حقن الموجّه (prompt injection) تعليمات للنموذج مخبأة في البيانات. اسم الرمز يحدده من أطلقه، واسم المتداول يحدده المتداول، فقد يحتوي حقل على «تجاهل التعليمات السابقة». في Genesis API يصل النص الخارجي في الحقلين title وoutcome لأسواق التنبؤ، وفي name للمتداول، وفي token_name لأونتشين، وفي message_ru وmessage_en لإشارات Genesis AI+: اذكر في موجّه النظام أن نتائج الأدوات بيانات فقط.
تشترط مواصفة MCP أن تتحقق الخوادم من مدخلات الأدوات، وأن تحدّ معدل الاستدعاءات، وأن تنظّف المخرجات، وتنصح العملاء بتأكيد العمليات الحساسة وتسجيل استخدام الأدوات (أدوات MCP). سجّل X-Request-Id: بوجوده مع الوقت بتوقيت UTC ونقطة النهاية والحالة يستطيع الدعم العثور على الطلب.
مخاطر الأتمتة مشروحة في الدرس 5 من دورة API العملات الرقمية.
التكاليف والحدود
تستهلك حصة Genesis API استجابة 200 فقط؛ أما 304 والأخطاء فمجانية لكنها تُحتسب في حد المعدل لكل ثانية. عند تجاوز الحدود يردّ الخادم بـ 429 ولا يخصم شيئاً.
| الخطة | السعر | الحصة والمعدل | الحداثة |
|---|---|---|---|
| Trial | $20/شهر | 500,000 استدعاء، 1 طلب/ث | 60 ث |
| Start | $50/شهر | 2M استدعاء، 2 طلب/ث | 30 ث |
| Pro | $100/شهر | 5M استدعاء، 5 طلب/ث | 10 ث |
| Max | $200/شهر | 10M استدعاء، 15 طلب/ث | 5 ث |
مثال توضيحي: 500 سؤال يومياً بـ 3 استدعاءات أدوات لكل سؤال تعني 500 × 3 = 1,500 استدعاء يومياً و1,500 × 30 = 45,000 خلال 30 يوماً، أي 9% من حصة Trial. تغطي الذاكرة المؤقتة التكرارات بالمعاملات نفسها ضمن freshness_sec، وسقف لعدد استدعاءات الأدوات في الإجابة الواحدة يمنع الحلقة من استهلاك الحصة.
الاستطلاع بأكثر من meta.freshness_sec لا يجلب لقطة جديدة. الاستطلاع الرخيص بـ ETag وإعادة المحاولة مشروح في كيف تستطلع API العملات الرقمية دون بلوغ الحدود، والحدود في دليل حدود Genesis API. وإذا كان الوكيل يحتاج قواعد فقط بلا نموذج، فـبوت أربيتراج العملات الرقمية بلغة Python أبسط.
Genesis API لوكلاء الذكاء الاصطناعي
Genesis API هو REST API ببيانات Genesis Arbitrage: سبريدات CEX وDEX، ودفاتر الأوامر، والتمويل، والفائدة المفتوحة، وعبر السلاسل، وتدفقات أونتشين، وأسواق التنبؤ، وفرص المراهنات الرياضية (surebets)، وإشارات الذكاء الاصطناعي. الطلبات HTTP GET بالترويسة X-API-Key، والاستجابات JSON فيها data وmeta (صيغة الاستجابة)، ولا حاجة إلى SDK.
المنشور للوكلاء:
openapi.json— OpenAPI 3.1: 37 عملية، ومخططات الاستجابة والخطط فيx-genesis-plans؛llms-full.txt— المرجع الكامل في ملف Markdown واحد؛llms.txt— نظرة عامة على الموقع للنماذج اللغوية؛/.well-known/api-catalog— كتالوج RFC 9727 يربط بالمواصفة والتوثيق وصفحة الحالة.
لا يوجد خادم MCP رسمي ولا WebSocket ولا نقاط نهاية للتداول: يقرأ الوكيل البيانات، وتبقى الصفقات بيد الإنسان. الإعداد خطوة بخطوة في دليل Genesis API لوكلاء الذكاء الاصطناعي.
أسئلة وأجوبة
هل يستطيع وكيل الذكاء الاصطناعي تداول العملات الرقمية بنفسه؟
فقط إذا منحته API تداول بورصة، وهذا كودك ومسؤوليتك. وليس عبر Genesis API: فهو يقرأ البيانات فقط. تقول مواصفة MCP إن على الإنسان أن يستطيع دائماً رفض استدعاء أداة؛ وفي الصفقات اجعلها قاعدة أن يؤكد إنسان كل أمر.
أي خطة Genesis API يحتاجها وكيل الذكاء الاصطناعي؟
تغطي Trial بسعر $20 شهرياً سبريدات CEX والتمويل والفائدة المفتوحة. تضيف Start الأسهم وأقسام أونتشين وأربيتراج التنبؤات بوضعي exact وdutch، بينما تفتح Pro وMax كل شيء، بما في ذلك DEX ودفاتر الأوامر. تعتمد سرعة الاستجابة على حد الثانية وحداثة الخطة؛ محتوى الخطط في صفحة أسعار Genesis API.
من أين أحصل على مواصفة Genesis API للوكيل؟
OpenAPI 3.1 على genesisarbitrage.com/openapi.json، ومرجع النموذج على genesisarbitrage.com/llms-full.txt. ويستطيع الوكيل أيضاً العثور على كليهما عبر كتالوج /.well-known/api-catalog.
هل لدى Genesis API خادم MCP؟
لا يوجد خادم رسمي. تبني خادمك من المعالجات نفسها: أداة MCP هي طلب GET إلى نقطة نهاية بمفتاح من بيئة الخادم. مثال Python بسيط في مدخل MCP من المسرد.