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: endpointها، پارامترها، فیلدها، مثال‌ها، محدودیت‌ها، خطاهازمینه برای مدلی که کد می‌نویسد یا به پرسش‌های 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 در <head> تگ <link rel="service-desc"> دارند که به 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 را به زمینه‌اش اضافه کنید: پارامترها، فیلدها و مثال‌های هر endpoint، محدودیت‌ها و کدهای خطا در آن است.

  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 روی endpoint اسپات - اسپات:

{
  "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
  }
}

نام فیلدی که طرح پارامترها را نگه می‌دارد میان ارائه‌دهندگان مدل فرق دارد و در MCP برابر inputSchema است؛ درون آن همیشه JSON Schema است. ویژگی‌های coin و min_spread از پارامترهای عملیات getArbitrageSpotSpot آمده‌اند و description می‌گوید ابزار چه زمانی صدا زده شود: مدل بر پایهٔ همین متن انتخاب می‌کند.

یک handler پایتون که /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 ثانیه در کش می‌ماند: داده زودتر به‌روز نمی‌شود. پس از آن handler همان ETag قبلی را در If-None-Match می‌فرستد و پاسخ 304 سهمیه مصرف نمی‌کند. در 429 و 503 به‌اندازهٔ Retry-After با سقف 30 ثانیه صبر می‌کند، یک بار دوباره تلاش می‌کند و خطاهای دیگر را به‌صورت کد به مدل برمی‌گرداند. مدل 10 سطر با 6 فیلد می‌گیرد. مثال توضیحی: پاسخ کامل با 214 سطر و 22 فیلد برابر 214 × 22 = 4,708 مقدار است و پاسخ کوتاه‌شده 10 × 6 = 60.

قواعد عامل

قاعدهچگونه
کلید روی سرور می‌ماندمتغیر محیطی handler؛ بدون کلید در prompt، مرورگر و لاگ چت
API فقط می‌خواندGenesis API سفارش ثبت نمی‌کند؛ هر معامله در صرافی را انسان تأیید می‌کند
نرخ را کد شما تعیین می‌کندکش به‌مدت freshness_sec، ETag و If-None-Match، صف زیر سقف درخواست در ثانیه
فیلتر، نه کل مجموعهcoin، min_spread، exchange؛ تا 10 سطر و فیلدهای لازم به مدل
زمان داده در هر پاسخupdated_at و سن داده در نتیجهٔ ابزار و در پاسخ به کاربر
متن بیرونی فقط داده استمدل بر اساس عنوان بازارها، نتیجه‌ها، نام معامله‌گران و متن سیگنال‌ها عمل نمی‌کند

مدل ممکن است چند ابزار را هم‌زمان بخواهد و سقف هر درخواست روی کلید را می‌شمارد: 1 درخواست در ثانیه در 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 رسمی ندارد. می‌توانید از همان handlerها سرور خودتان را بسازید: ابزار MCP یک GET به endpoint در Genesis API است، پارامترهایش JSON Schema در inputSchema هستند و کلید در محیط سرور است. سرور محلی stdio کلید را روی دستگاه شما نگه می‌دارد. سرور راه‌دور را پشت احراز مجوز بگذارید (MCP استفاده از OAuth را توصیه می‌کند)، وگرنه هر کسی نشانی را بداند می‌تواند سهمیه شما را مصرف کند.

کار عامل‌ها با داده‌های بازار ارز دیجیتال به‌طور کلی در مقالهٔ داده‌های بازار ارز دیجیتال برای عامل‌های هوش مصنوعی آمده و ریسک‌های خودکارسازی در درس پنجم دوره.

پرسش و پاسخ

آیا Genesis API سرور MCP رسمی دارد؟

خیر. برای عامل‌ها openapi.json، llms-full.txt و کاتالوگ API وجود دارد. می‌توانید خودتان روی REST API سرور MCP بنویسید: هر ابزار یک درخواست GET با کلید از متغیر محیطی است.

آیا عامل می‌تواند از طریق Genesis API معامله کند؟

خیر. Genesis API فقط داده می‌خواند و سفارش ثبت نمی‌کند. عامل موقعیت‌ها را پیدا می‌کند و هشدار می‌فرستد؛ معامله را انسان در صرافی انجام می‌دهد.

عامل به کدام پلن نیاز دارد؟

هر کدام: Trial یک درخواست در ثانیه و تازگی 60 ثانیه می‌دهد و Max 15 درخواست در ثانیه و 5 ثانیه. اینکه هر پلن کدام endpointها را دارد در x-genesis-plans و در صفحهٔ تعرفه‌های Genesis API آمده است.

چرا مدل قیمت‌های کهنه نقل می‌کند؟

داده به‌اندازهٔ تازگی پلن شما عقب است و کش handler تا freshness_sec به آن اضافه می‌کند. updated_at و سن داده را به مدل بدهید و بخواهید زمان را در پاسخش بگوید.