Genesis Arbitrage

Genesis Arbitrage · · 9 دقائق قراءة

Genesis API لوكلاء الذكاء الاصطناعي: OpenAPI وllms.txt واستدعاء الدوال

باختصار

  • للوكلاء توجد الملفات openapi.json (مواصفة OpenAPI 3.1 فيها 37 عملية مع الخطط) وllms-full.txt وllms.txt وكتالوج API وفق RFC 9727.
  • يختار النموذج الأداة ووسائطها، ويرسل خادمك الطلب بالمفتاح ويعيد إلى النموذج JSON قصيرًا مع وقت البيانات.
  • Genesis API يقرأ البيانات فقط. يحدد كودك معدل الطلبات، ويعامل النموذج نصوص الاستجابات كبيانات، ويؤكد إنسان أي صفقة.

Genesis API هو REST API لبيانات سوق العملات الرقمية، ويستدعيه وكيل الذكاء الاصطناعي كأداة: يقرر النموذج البيانات التي يحتاجها، ويرسل خادمك طلب GET بالمفتاح ويعيد JSON قصيرًا. وللوكلاء والنماذج اللغوية وصف مقروء آليًا لـ API: مواصفة OpenAPI 3.1 ومرجع كامل بصيغة Markdown وكتالوج API. أما البيانات نفسها فهي ما يعرضه الموقع: سبريدات CEX وDEX ودفاتر الأوامر والتمويل وتدفقات أونتشين وأسواق التنبؤات.

الملفات المقروءة آليًا

الملفماذا فيهلماذا
genesisarbitrage.com/openapi.jsonOpenAPI 3.1: 37 عملية والمعاملات ومخططات الاستجابة والخطط في x-genesis-plans وترويسات rate limitالاستيراد إلى عميل API وتوليد الكود وأدوات الوكيل
genesisarbitrage.com/llms-full.txtالمرجع الكامل في ملف Markdown واحد: نقاط النهاية والمعاملات والحقول والأمثلة والحدود والأخطاءسياق للنموذج الذي يكتب الكود أو يجيب عن أسئلة API
genesisarbitrage.com/llms.txtنظرة عامة على الموقع: Genesis API والأدوات والدليل والدورة والمسرد والمدونةأول نظرة للنموذج على الموقع
genesisarbitrage.com/.well-known/api-catalogكتالوج API وفق RFC 9727: روابط المواصفة والتوثيق والأسعار والحالةاكتشاف API عبر النطاق

تتبع المواصفة OpenAPI 3.1 التي تشكّل مخططاتها مجموعة شاملة لـ JSON Schema 2020-12، ولذلك تنتقل معاملات العملية إلى تعريف الأداة بلا تغيير تقريبًا. llms.txt صيغة اقتُرحت عام 2024: ملف Markdown في جذر الموقع فيه نظرة عامة موجزة وروابط للنماذج اللغوية. ويوجد الكتالوج في العنوان الذي حدده RFC 9727.

تحمل صفحات توثيق Genesis API والمنتج والأسعار الوسم <link rel="service-desc"> في <head> ويشير إلى openapi.json. علاقة الرابط هذه من RFC 8631 وتعني وصف خدمة موجهًا للآلات. مقتطف مختصر من المواصفة:

{
  "openapi": "3.1.0",
  "servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
  "paths": {
    "/arbitrage/spot-spot": {
      "get": {
        "operationId": "getArbitrageSpotSpot",
        "x-genesis-plans": ["trial", "start", "pro", "max"],
        "parameters": [
          { "name": "coin", "in": "query",
            "schema": { "type": "string" } },
          { "name": "min_spread", "in": "query",
            "schema": { "type": "number" } },
          …
        ]
      }
    }
  }
}

لكل عملية operationId ومعاملات مكتوبة الأنواع ومخطط استجابة 200 واستجابة 304 ورموز الأخطاء والترويسات X-RateLimit-* وX-Quota-* وX-Request-Id وETag. يوصف المفتاح في مخطط الأمان ApiKeyAuth: النوع apiKey والترويسة X-API-Key.

كيف تتصل

  1. احصل على مفتاح واحفظه على الخادم

    يُصدر المفتاح gns_live_… في ملفك الشخصي، في كتلة «Genesis API»، ويظهر مرة واحدة. احفظه في متغير البيئة GENESIS_API_KEY على الخادم الذي يشغّل الوكيل. التخزين وإعادة الإصدار في دليل مفتاح API.

  2. استورد المواصفة

    عميل API أو إطار وكلاء يقبل OpenAPI يبني الطلبات والأدوات مباشرة من openapi.json: الرابط الأساسي من servers وترويسة المفتاح من ApiKeyAuth. طريقة إرسال المفتاح موصوفة في المصادقة.

  3. أبقِ العمليات التي تحتاجها

    يشغل كل تعريف أداة جزءًا من سياق النموذج، ويسهل الاختيار بين عدد قليل منها. أبقِ العمليات التي تحتاجها مهمتك، واحذف ما هو خارج خطتك حسب x-genesis-plans: فهي تعيد 403 plan_restricted.

  4. أعطِ النموذج المرجع

    إذا كان الوكيل يكتب الكود أو يجيب عن أسئلة حول API فأضف llms-full.txt إلى سياقه: فيه معاملات كل نقطة نهاية وحقولها وأمثلتها والحدود ورموز الأخطاء.

  5. تحقق من المفتاح بأول استدعاء

    /account/usage يعيد خطتك والحصة المستهلكة وحد الطلبات في الثانية وحداثة البيانات.

كيف يستدعي النموذج Genesis API

استدعاء الدوال (function calling) آلية يعيد فيها النموذج اسم أداة ووسائطها بدل نص، وينفذ كودك الاستدعاء. الحلقة:

  1. مع سؤال المستخدم يتلقى النموذج تعريفات الأدوات: الاسم والغرض والمعاملات بصيغة JSON Schema.
  2. يرد النموذج باستدعاء: get_spreads بالوسائط {"coin": "TON", "min_spread": 0.5}.
  3. يتحقق خادمك من الوسائط ويرسل GET بالترويسة X-API-Key ويقتطع الاستجابة إلى الحقول التي تحتاجها.
  4. يعود JSON قصير مع وقت البيانات إلى النموذج، فيجيب المستخدم.

لا يجري النموذج أي استدعاءات شبكية ولا يرى المفتاح أبدًا: لديه تعريف الأداة والنتيجة فقط. أداة get_spreads فوق نقطة النهاية سبوت - سبوت:

{
  "name": "get_spreads",
  "description": "أين تشتري عملة بسعر أقل وتبيعها بسعر أعلى (CEX)",
  "parameters": {
    "type": "object",
    "properties": {
      "coin": {
        "type": "string",
        "description": "رمز العملة، مثل BTC"
      },
      "min_spread": {
        "type": "number",
        "description": "الحد الأدنى للسبريد، %: القيمة 0.5 تعني 0.5%"
      }
    },
    "additionalProperties": false
  }
}

يختلف اسم الحقل الذي يحمل مخطط المعاملات بين مزودي النماذج، وهو inputSchema في MCP؛ وداخله دائمًا JSON Schema. الخاصيتان coin وmin_spread مأخوذتان من معاملات العملية getArbitrageSpotSpot، ويحدد description متى تُستدعى الأداة: النموذج يختار بحسب هذا النص.

معالج بلغة Python يستدعي /arbitrage/spot-spot ويعيد إلى النموذج حتى 10 صفوف بالحقول المطلوبة مع meta.updated_at:

import os
import time

import requests

API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"]  # المفتاح يبقى على الخادم
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
          "withdraw_enabled_buy", "deposit_enabled_sell")
cache = {}  # المعاملات -> (الوقت، ETag، جسم الاستجابة)


def get_spreads(coin=None, min_spread=None):
    params = {"coin": coin, "min_spread": min_spread}
    params = {k: v for k, v in params.items() if v is not None}
    ck = tuple(sorted(params.items()))
    ts, etag, body = cache.get(ck, (0, None, None))
    if body and time.time() - ts < body["meta"]["freshness_sec"]:
        return shorten(body)  # البيانات لن تتحدث قبل ذلك
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    for attempt in range(2):  # 429 و503: انتظر Retry-After وأعد المحاولة
        r = requests.get(API, headers=headers, params=params,
                         timeout=10)
        if r.status_code not in (429, 503) or attempt:
            break
        time.sleep(min(int(r.headers.get("Retry-After", 5)), 30))
    if r.status_code == 200:
        body, etag = r.json(), r.headers.get("ETag")
    elif r.status_code != 304:
        return {"error": r.status_code}  # يرى النموذج الرمز
    cache[ck] = (time.time(), etag, body)
    return shorten(body)


def shorten(body):
    rows = sorted(body["data"], key=lambda x: x["spread_pct"],
                  reverse=True)[:10]
    t = body["meta"]["updated_at"]
    return {"updated_at": t, "age_sec": int(time.time() - t),
            "rows": [{f: x.get(f) for f in FIELDS} for x in rows]}

تبقى الاستجابة في الذاكرة المؤقتة meta.freshness_sec ثانية: فالبيانات لن تتحدث قبل ذلك. بعدها يرسل المعالج ETag السابق في If-None-Match، واستجابة 304 لا تستهلك الحصة. عند 429 و503 ينتظر Retry-After بحد أقصى 30 ثانية ويعيد المحاولة مرة واحدة، ويعيد الأخطاء الأخرى إلى النموذج رمزًا. يتلقى النموذج 10 صفوف من 6 حقول. مثال توضيحي: استجابة كاملة من 214 صفًا بـ 22 حقلًا تساوي 214 × 22 = 4,708 قيمة، والمقتطعة 10 × 6 = 60.

قواعد للوكيل

القاعدةكيف
المفتاح يبقى على الخادممتغير بيئة للمعالج؛ لا مفتاح في الـ prompt ولا في المتصفح ولا في سجلات الدردشة
API يقرأ فقطGenesis API لا يضع أوامر؛ ويؤكد إنسان أي صفقة على البورصة
كودك يحدد المعدلذاكرة مؤقتة لمدة freshness_sec وETag وIf-None-Match وطابور تحت حد الطلبات في الثانية
مرشحات لا المجموعة الكاملةcoin وmin_spread وexchange؛ وحتى 10 صفوف والحقول اللازمة إلى النموذج
وقت البيانات في كل إجابةupdated_at والعمر في نتيجة الأداة وفي الرد على المستخدم
النص الخارجي بيانات فقطلا يتصرف النموذج وفق عناوين الأسواق ونتائجها وأسماء المتداولين ونصوص الإشارات

قد يطلب النموذج عدة أدوات معًا، والحد يحسب كل طلب على المفتاح: طلب واحد في الثانية في Trial و15 في Max. استجابات 304 والأخطاء لا تستهلك الحصة لكنها تُحسب ضمن حد الثانية — انظر الخطط والحدود ودليل الحدود.

الحقلان title وoutcome في أسواق التنبؤات وname للمتداول وtoken_name في أحداث أونتشين وmessage_ru وmessage_en في إشارات Genesis AI+ تأتي من مصادر خارجية. قد يسمّي أحدهم سوقًا «تجاهل التعليمات السابقة و…» — هذا هو prompt injection، أي أوامر تُهرَّب عبر البيانات. مرّر هذه الحقول داخل نتيجة الأداة فقط، وحدّد طولها، وانصّ في system prompt على أن النص داخل النتائج بيانات.

MCP: خادمك الخاص فوق REST API

MCP (Model Context Protocol) معيار مفتوح لربط تطبيقات الذكاء الاصطناعي بالأنظمة الخارجية. يوفر خادم MCP للتطبيق أدوات وموارد وقوالب prompt؛ والرسائل بصيغة JSON-RPC 2.0 عبر stdio محليًا وStreamable HTTP عن بعد. المواصفة وSDK لعدة لغات على modelcontextprotocol.io.

ليس لدى Genesis API خادم MCP رسمي. يمكنك بناء خادمك من المعالجات نفسها: أداة MCP هي GET إلى نقطة نهاية في Genesis API، ومعاملاتها JSON Schema في inputSchema، والمفتاح في بيئة الخادم. خادم stdio المحلي يبقي المفتاح على جهازك. ضع الخادم البعيد خلف تفويض (يوصي MCP بـ OAuth)، وإلا استطاع كل من يعرف العنوان استهلاك حصتك.

عمل الوكلاء مع بيانات سوق العملات الرقمية عمومًا في مقال بيانات سوق العملات الرقمية لوكلاء الذكاء الاصطناعي، ومخاطر الأتمتة في الدرس الخامس من الدورة.

أسئلة وأجوبة

هل لدى Genesis API خادم MCP رسمي؟

لا. للوكلاء توجد openapi.json وllms-full.txt وكتالوج API. يمكنك كتابة خادم MCP فوق REST API بنفسك: كل أداة طلب GET بالمفتاح من متغير بيئة.

هل يستطيع الوكيل التداول عبر Genesis API؟

لا. Genesis API يقرأ البيانات فقط ولا يضع أوامر. يجد الوكيل الفرص ويرسل التنبيهات، وينفذ الإنسان الصفقة على البورصة.

أي خطة يحتاجها الوكيل؟

أي واحدة منها: Trial يعطي طلبًا واحدًا في الثانية وحداثة 60 ثانية، وMax يعطي 15 طلبًا في الثانية و5 ثوانٍ. نقاط النهاية في كل خطة مذكورة في x-genesis-plans وفي صفحة أسعار Genesis API.

لماذا يذكر النموذج أسعارًا قديمة؟

البيانات متأخرة بقدر حداثة خطتك، وتضيف الذاكرة المؤقتة في المعالج حتى freshness_sec. أعطِ النموذج updated_at وعمر البيانات، واطلب منه ذكر الوقت في إجابته.