دادههای بازار ارز دیجیتال برای عاملهای هوش مصنوعی: 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 ارز دیجیتال: انواع API دادههای بازار و چگونگی انتخاب را ببینید.
چرا مدل قیمتهای فعلی را نمیداند
مدل زبانی روی متنهایی آموزش میبیند که تا تاریخ مشخصی جمع شدهاند، یعنی تاریخ قطع دانش آن. از لیستشدنها، نرخها و قیمتهای پس از آن تاریخ چیزی نمیداند و قیمت BTC که از حافظه میگوید عددی از متن آموزشی با تاریخ نامعلوم است. مدل زمان فعلی را هم نمیداند، مگر آن را در درخواست بدهید.
برای آربیتراژ پاسخ از حافظه بیفایده است: اسپرد بین صرافیها چند دقیقه عمر میکند و نرخ فاندینگ در هر دوره تسویه، هر 8، 4 یا 1 ساعت، تغییر میکند. اعداد زنده فقط از ابزار میآیند: مرجع 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 فیلد برای هر یک از 8 صرافی دیگر در others. کل پاسخ 1,000 × 52 = 52,000 مقدار است، در حالی که پاسخ درباره بهترین جفتها به 5 ردیف 8 مقداری نیاز دارد: 5 × 8 = 40.
تعریف ابزارها و نتایج در هر گام وارد زمینه میشوند: Claude API آنها را بهعنوان توکن ورودی حساب میکند.
زمان داده و تازگی
هندلر updated_at را، یعنی زمان ساخت داده از meta.updated_at به ثانیه یونیکس، و 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 یعنی ۰.۰۵%"
},
"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 استانداردی برای توصیف ماشینخوانِ APIهای HTTP است: عملیات با operationId، یک summary کوتاه و پارامترهایی با طرح توصیف میشود. در نسخه 3.1 شیء Schema ابرمجموعه JSON Schema 2020-12 است (مشخصات OpenAPI 3.1) و MCP بهطور پیشفرض inputSchema را JSON Schema 2020-12 میخواند. پس پارامترها بدون تبدیل به ابزار منتقل میشوند.
اسکریپت ابزارها را از مشخصات Genesis API میسازد: عملیات موردنظر را برمیدارد، آنهایی را که بر اساس x-genesis-plans خارج از پلن شما هستند رد میکند و پارامترهای query و path را منتقل میکند. هدرها کار هندلر است.
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 از 37 عملیات 11 تا را نگه میدارد و 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 را پشت احراز هویت بگذارید، وگرنه هر کس نشانی را بداند سهمیه شما را مصرف میکند.
SDKهای رسمی MCP برای 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 ارز دیجیتال آمده است.
هزینهها و محدودیتها
فقط پاسخ 200 از سهمیه Genesis API مصرف میکند؛ 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، دفترهای سفارش، فاندینگ، اوپن اینترست، کراسچین، جریانهای آنچین، بازارهای پیشبینی، آربیتراژ شرطبندی (surebet) ورزشی و سیگنالهای هوش مصنوعی. درخواستها 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 واژهنامه است.