API دفتر سفارش ارز دیجیتال: عمق، قیمت اجرا و اسلیپیج بین صرافیها
به طور خلاصه
- API دفتر سفارش، سطوح خرید و فروش را برمیگرداند، یعنی قیمت و حجم هر سطح را، بهصورت اسنپشات REST یا جریان WebSocket از تغییرات. بهترین قیمت خرید و فروش فقط اولین دلارهای معامله را توصیف میکنند.
- عمق قیمت سفارش بزرگ را تعیین میکند. در یک مثال فرضی، خرید 10,000 دلاری از پنج سطح میگذرد، میانگین قیمتش 25 بیسیسپوینت بالاتر از میانهٔ دفتر مینشیند و اسپرد بین دو صرافی از 1.20% به 0.70% کاهش مییابد.
- در پلنهای Pro و Max، Genesis API قیمت اجرای آمادهٔ 500 تا 10,000 دلار، Δ دفتر سفارش برای ردیفهای آربیتراژ، سن و عمق دفتر، تاریخچهٔ اسلیپیج و نردبان اسلیپیج DEX را برمیگرداند. فقط REST؛ دفترها 5 تا 20 ثانیه از صرافی عقباند.
API دفتر سفارش ارز دیجیتال سفارشهای خرید و فروش فعلی یک جفتارز را برمیگرداند، گروهبندیشده بر اساس سطح قیمت: هر سطح یک قیمت دارد و حجمی که در آن قیمت منتظر است. از این سطوح قیمت اجرای سفارشی با حجم معین، اسلیپیج آن و عمق بازار را حساب میکنید، و از دفتر دو صرافی، اینکه چه مقدار از اسپرد پس از معاملهای واقعی میماند.
صرافی دفتر خودش را بهصورت اسنپشات REST یا جریان WebSocket ارائه میدهد، اما Genesis API در پلنهای Pro و Max قیمت اجرای آماده، عمق و Δ دفتر سفارش را برای صرافیهای زیادی یکجا میدهد.
API دفتر سفارش چه چیزی برمیگرداند
دفتر سفارش فهرست سفارشهای لیمیت منتظر برای یک جفتارز است. سفارشهای خرید (bids) از بالاترین قیمت به پایین و سفارشهای فروش (asks) از پایینترین قیمت به بالا مرتب میشوند. سطح یعنی یک قیمت و مجموع حجم در آن؛ فاصلهٔ بهترین ask و بهترین bid، اسپرد دفتر است.
اسنپشات REST پاسخ یک درخواست است: سطوح در همان لحظه. اندپوینت دفتر سفارش Binance عمومی است و کلید API نمیخواهد؛ این هم درخواستی برای پنج سطح بالای BTC/USDT و پاسخ آن (اعداد فرضیاند):
curl "https://api.binance.com/api/v3/depth?symbol=BTCUSDT&limit=5"
{
"lastUpdateId": 81273645120,
"bids": [["96015.90000000", "1.25000000"], …],
"asks": [["96016.00000000", "0.84100000"], …]
}
هر سطح بهصورت جفتی از رشتهها [قیمت، مقدار] میرسد و مقدار بر حسب کوین است: بهترین bid برابر 1.25 × 96,015.9 = 120,019.88 دلار است. پارامتر limit بهطور پیشفرض 100 است و تا 5,000 سطح در هر طرف میرسد (مستندات Binance).
جریان WebSocket را صرافی از طریق اتصال پایدار میفرستد. Binance دو نوع جریان دفتر دارد: btcusdt@depth5، btcusdt@depth10 و btcusdt@depth20 5، 10 یا 20 سطح بالا را میفرستند، و btcusdt@depth فقط تغییرات را. هر دو هر 1000 میلیثانیه بهروز میشوند، یا با پسوند @100ms هر 100 میلیثانیه (جریانهای WebSocket در Binance).
دفتر محلی کامل از اسنپشات بهعلاوهٔ جریان تغییرات ساخته میشود، با تطبیق lastUpdateId اسنپشات با شناسههای بهروزرسانی رویدادها؛ اگر رویدادی از دست برود، دفتر از صفر بازسازی میشود.
| روش | چه چیزی میگیرید | کاربرد |
|---|---|---|
| اسنپشات REST | سطوح در زمان درخواست، در Binance تا 5,000 در هر طرف | بررسی یکباره، نمونهگیری کمتکرار |
| جریان WebSocket | سطوح بالا یا تغییرات هر 100 تا 1000 میلیثانیه | دفتر محلی در حافظه، ربات معامله |
| Genesis API روی REST | سطوح بهشکل [قیمت، مبلغ به دلار]، قیمت اجرا، عمق و سن دفتر | مقایسهٔ صرافیها، بررسی ستاپ |
چرا بهترین bid و ask در حجم بالا گمراه میکنند
بهترین ask فقط قیمت سطح اول است. خرید بازاری بزرگتر از آن سطح، سطوح بعدی و گرانتر را میگیرد و میانگین قیمت پر شدن بالا میرود؛ این همان اسلیپیج است.
یک مثال فرضی: توکن ABC در صرافی A، بهترین bid برابر 0.9996، بهترین ask برابر 1.0004 و میانهٔ دفتر 1.0000. خرید بازاری 10,000 دلاری از پنج سطح ask میگذرد:
| قیمت ask | در دفتر، $ | گرفتهشده، $ | کوین |
|---|---|---|---|
| 1.0004 | 1,100 | 1,100 | 1,099.56 |
| 1.0010 | 1,400 | 1,400 | 1,398.60 |
| 1.0018 | 2,600 | 2,600 | 2,595.33 |
| 1.0030 | 3,000 | 3,000 | 2,991.03 |
| 1.0050 | 6,000 | 1,900 | 1,890.55 |
سفارش در مجموع 9,975.07 کوین میخرد. میانگین قیمت اجرا همان VWAP، میانگین وزنی بر حسب حجم، است: 10,000 / 9,975.07 ≈ 1.0025.
اسلیپیج نسبت به بهترین ask: (1.0025 − 1.0004) / 1.0004 × 100 ≈ 0.21%. نسبت به میانهٔ دفتر: (1.0025 − 1.0000) / 1.0000 × 10,000 = 25 بیسیسپوینت. چهار تای آن نصف اسپرد دفتر است که هر خرید بازاری میپردازد؛ 21 تای دیگر از عمق میآید.
عمق بازار در محدودهٔ ±X% و دیوارها
عمق بازار مجموع حجم سفارشها در فاصلهای معین از بهترین قیمت است. در مثال، سفارشهای ask تا +0.2% از بهترین، یعنی تا 1.0024، مجموعاً 1,100 + 1,400 + 2,600 = 5,100 دلار میشوند و تا +0.5%، یعنی تا 1.0054، برابر 14,100 دلار.
عمق را ظرفیت بخوانید: سفارشی بزرگتر از عمق در +0.2% در سطوح فراتر از آن مرز پر میشود. در صرافی A خرید 5,000 دلاری درون آن جا میشود و خرید 10,000 دلاری نه.
دیوار سفارشی بزرگ در یک سطح است، بهوضوح بزرگتر از همسایههایش: 6,000 دلار در 1.0050 در مثال. تا وقتی دیوار هست قیمت را نگه میدارد، اما میتواند یک ثانیه پیش از رسیدن سفارش شما برداشته شود و خرید روی سطوح پشت آن پر شود.
در Genesis API عمق از /orderbooks/book، دفتر یک بازار، و /orderbooks/coin/{coin}، دفترهای یک کوین در همهٔ صرافیها و بازارها یکجا، میآید (دفتر سفارش بازار، دفترهای سفارش کوین). پاسخ 10 سطح بالای bids و asks را بهشکل [قیمت، مبلغ به دلار]، بزرگترین دیوارها را در walls_bid و walls_ask، و عمق کل هر طرف در محدودهٔ ±50% از بهترین قیمت را در depth_bid_usd و depth_ask_usd دارد. بازهٔ ±50% پهن است؛ پس برای حجمی مشخص به سطوح یا قیمت اجرای آماده نگاه کنید.
سن دفتر: دفترهای کهنه و عمق محدود
هر اسنپشات دفتر سنی دارد. اگر دفتر یک صرافی 15 ثانیه از دیگری قدیمیتر باشد، بخشی از اسپرد بین آنها ممکن است شکاف زمانی باشد: قیمت در دفتر قدیمیتر پیشتر جابهجا شده است.
در Genesis API دفترها 5 تا 20 ثانیه از صرافی عقباند و هر دفتر سن خودش را دارد. ابتدای پاسخ /orderbooks/book از مستندات:
{
"exchange": "Binance",
"market": "spot",
"coin": "BTC",
"book_ts": 1794675858,
"age_sec": 6,
"stale": false,
"source": "ws",
"depth_limited": false,
"levels_bid": 500,
"levels_ask": 500,
…
}
book_ts زمان دفتر به ثانیهٔ unix است، age_sec سن آن به ثانیه، و stale: true دفتری قدیمیتر از 30 ثانیه را نشان میدهد. source میگوید دفتر چگونه از صرافی گرفته شده: با WebSocket (ws) یا با درخواستهای REST (rest).
depth_limited: true یعنی صرافی عمق محدودی منتشر میکند: مجموعها ناقصاند و ممکن است سفارش بزرگ پر نشود. وقتی سفارشها تمام شوند، /orderbooks/exec بهجای قیمت null برمیگرداند و Δ دفتر سفارش وضعیت exhausted را.
اسپرد قابل اجرا بین صرافیها: Δ دفتر سفارش
به مثال فرضی برگردیم. در صرافی B آخرین معامله با 1.0120 ثبت شد، بهترین bid برابر 1.0116 و ask برابر 1.0124 است. bidهای B اینها را دارند: 1,100 دلار در 1.0116، 1,300 دلار در 1.0110، 2,800 دلار در 1.0102، 2,900 دلار در 1.0090 و 5,000 دلار در 1.0070.
فروش 10,000 دلار در این bidها با همان فرمول VWAP برابر 1.0095 میدهد. یعنی (1.0120 − 1.0095) / 1.0120 × 10,000 ≈ 24.7 بیسیسپوینت زیر میانهٔ دفتر B.
| اسپرد چگونه حساب شده | خرید در A ← فروش در B | اسپرد |
|---|---|---|
| آخرین معاملات، مثل ردیف جدول | 1.0000 ← 1.0120 | 1.20% |
| بهترین قیمتهای دفتر | 1.0004 ← 1.0116 | 1.12% |
| پس از اجرای 10,000 دلار | 1.0025 ← 1.0095 | 0.70% |
اسپرد ردیف: (1.0120 − 1.0000) / 1.0000 × 100 = 1.20%. پس از اجرا: (1.0095 − 1.0025) / 1.0025 × 100 ≈ 0.70%. ردیف 120 دلار روی 10,000 دلار وعده میدهد و پس از دفترها حدود 70 دلار میماند: 10,000 × 0.006983 ≈ 69.83.
از 50 بیسیسپوینت از دسترفته، 8 تا به فاصلهٔ آخرین معامله با بهترین سفارشها رفت و 42 تای دیگر به عمق دو دفتر.
Δ دفتر سفارش نامی است که Genesis Arbitrage به اسپرد ردیف میدهد وقتی از طریق دفترهای سفارش برای حجمی معین بازمحاسبه شود؛ در سایت ستون «Δ بر اساس سفارشها» در جدولهای آربیتراژ است، مثلاً اسپات – فیوچرز. در API از /orderbooks/spreads/{dataset} میآید: هر ردیف یک کوین در مجموعهدادهٔ spot-spot، spot-futures، futures-futures، dex-spot یا dex-futures یک شیء order_delta میگیرد (Δ دفتر سفارش).
order_delta شامل buy_price و sell_price برای حجم انتخابی، spread_pct پس از اجرا و status است: ok، no_book (بدون دفتر) یا exhausted (دفتر پر نشد). مقدار volume برابر 0 (بهترین قیمتهای دفتر) یا 500، 1000، 2500، 5000، 10000 است و نتیجه هرگز از اسپرد ردیف بیشتر نمیشود. ردیفهای DEX بهجای جفت قیمت، side و cex_price دارند: طرف CEX و قیمت اجرای آن.
خود قیمتهای اجرا، برای همهٔ بازارها یکجا، از /orderbooks/exec میآیند: جفت [قیمت خرید، قیمت فروش] زیر کلیدی مثل Binance|spot|BTC، و null جایی که دفتر کمعمق است (قیمتهای اجرا).
ستاپ کامل، با انتقال کوین و بررسی شبکهها، در آربیتراژ ارز دیجیتال بین صرافیها آمده است.
نمونهٔ Python: اسپرد ردیف در برابر اسپرد پس از اجرا
اسکریپت ستاپهای Spot – Spot با اسپرد دستکم 0.5% را برمیدارد، Δ دفتر سفارش را برای 5,000 دلار روی ده کوین با پهنترین اسپرد میخواهد و چاپ میکند دفترها چند بیسیسپوینت خوردهاند. کلید از متغیر محیطی GENESIS_API_KEY میآید. با 429 و 503 اسکریپت Retry-After ثانیه صبر میکند و اگر انتظار از یک دقیقه بیشتر باشد — سهمیهٔ ماهانه تمام شده — متوقف میشود.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
VOLUME = 5000 # دلار برای هر پا
MIN_SPREAD = 0.5 # اسپرد ردیف، %
def get(path, params):
for _ in range(3):
r = requests.get(BASE + path, headers=HEADERS,
params=params, timeout=15)
if r.status_code in (429, 503):
wait = int(r.headers.get("Retry-After", "5"))
if wait > 60: # سهمیهٔ ماهانه تمام شده
break
time.sleep(wait)
continue
r.raise_for_status()
return r.json()["data"]
raise RuntimeError("API پاسخ نداد، بعداً دوباره تلاش کنید")
rows = get("/arbitrage/spot-spot", {"min_spread": MIN_SPREAD})
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
coins = list(dict.fromkeys(x["coin"] for x in rows))[:10]
for coin in coins:
data = get("/orderbooks/spreads/spot-spot",
{"coin": coin, "volume": VOLUME})
for row in data:
od = row["order_delta"]
if row["spread_pct"] < MIN_SPREAD or od["status"] != "ok":
continue # no_book یا exhausted: این حجم پر نمیشود
lost = (row["spread_pct"] - od["spread_pct"]) * 100
print(f'{coin} {row["exchange_buy"]}→{row["exchange_sell"]}'
f' {row["spread_pct"]:.2f}% → {od["spread_pct"]:.2f}%,'
f' دفترها {lost:.0f} bps خوردند')
time.sleep(0.25) # تا 4 درخواست در ثانیه: Pro اجازهٔ 5 میدهد
اسکریپت تا 11 فراخوانی با مکث 0.25 ثانیه بین کوینها انجام میدهد. آن را در حلقهای نه سریعتر از meta.freshness_sec اجرا کنید: 10 ثانیه در Pro و 5 ثانیه در Max (محدودیتهای Genesis API). برای افزودن اعلان به آن، ربات آربیتراژ ارز دیجیتال با Python را ببینید.
تاریخچهٔ هزینهٔ اجرا
یک اسنپشات نمیگوید اسلیپیج فعلی برای این بازار عادی است یا دفتر نازکتر از معمول است. /orderbooks/exec-history تاریخچه را از Genesis Charts برمیگرداند: اجرای 500، 1,000، 2,500، 5,000 و 10,000 دلار چند بیسیسپوینت از میانهٔ دفتر هزینه داشته، جدا برای خرید و فروش (تاریخچهٔ اجرا).
هر بازه 360 نقطه دارد: 1m 6 ساعت، 15m 3.75 روز، 1h 15 روز و 1d حدود یک سال را پوشش میدهد، با داده از 6 سپتامبر 2026. هر درخواست تا 8 بازار را در پارامتر keys میپذیرد. مقادیر خرید مثبت و فروش منفیاند؛ null یعنی داده نیست یا دفتر پر نشد. Genesis API اسنپشاتهای گذشتهٔ خود دفتر را ارائه نمیدهد.
import os
import statistics
import requests
KEY = "Binance|spot|BTC"
r = requests.get(
"https://api.genesisarbitrage.com/v1/orderbooks/exec-history",
headers={"X-API-Key": os.environ["GENESIS_API_KEY"]},
params={"keys": KEY, "interval": "1h"}, # 360 ساعت، 15 روز
timeout=15,
)
r.raise_for_status()
data = r.json()["data"]
series = data["series"][KEY]
if series is None:
raise SystemExit("بازار پیدا نشد: " + KEY)
i = data["volumes_usd"].index(10000) # سری خرید 10,000 دلاری
buy = series["buy"][i]
known = [x for x in buy if x is not None]
if not known:
raise SystemExit("برای این بازه داده نیست")
print("میانهٔ 15 روز، bps:", statistics.median(known))
print("آخرین نقطه، bps:", buy[-1])
فرضاً اگر میانهٔ 15 روز 12 بیسیسپوینت و آخرین نقطه 25 باشد، اجرا اکنون دو برابر معمول هزینه دارد و منطقی است آستانهٔ اسپرد برای این کوین بالا برده شود.
DEX: نردبان اسلیپیج، مالیات توکن و هانیپات
استخر DEX دفتر سفارش ندارد: قیمت سواپ از فرمول استخر میآید و هر چه معامله نسبت به نقدینگی بزرگتر باشد قیمت بیشتر جابهجا میشود. برای همین پای DEX با یک نردبان سنجیده میشود — اسلیپیج در یک رشته حجم.
/orderbooks/dex-slippage برای هر قرارداد اسلیپیج خرید و فروش را در 100، 500، 1,000، 2,500، 5,000، 10,000، 20,000، 50,000 و 100,000 دلار، مالیاتهای توکن و پرچم هانیپات برمیگرداند، همان ستونهای جدول DEX در سایت (اسلیپیج DEX). در پاسخ نمونهٔ مستندات، اسلیپیج خرید در 10,000 دلار برابر 0.86%، در 50,000 دلار برابر 3.12% و در 100,000 دلار برابر 6.05% است.
این سقف ستاپ را تعیین میکند: اسپرد 2% بین DEX و CEX در 10,000 دلار از اسلیپیج استخر جان سالم به در میبرد، اما در 50,000 دلار نه، حتی پیش از کارمزدها. null در نردبان یعنی استخر برای آن حجم نقدینگی ندارد و گس شبکه در پاسخ نیست، پس جداگانه در بودجه بگنجانید.
tax_buy_pct و tax_sell_pct مالیات خرید و فروش توکن به درصداند؛ null یعنی منبعی نیست و نباید صفر خوانده شود. honeypot: no — نشانهای نیست، suspect — منابع همنظر نیستند، yes — فروش توکن شاید ناممکن باشد.
برای بررسی دستی توکن، چگونه توکن را پیش از خرید بررسی کنیم را ببینید؛ برای قیمت و نقدینگی DEX در کنار CEX، DEX API را.
دفترهای سفارش در Genesis API: اندپوینتها و پلنها
| کار | اندپوینت |
|---|---|
| قیمت اجرا برای 500 تا 10,000 دلار در هر بازار | /orderbooks/exec |
| اسپرد ردیف پس از اجرا | /orderbooks/spreads/{dataset} |
| 10 سطح، دیوارها، عمق و سن دفتر | /orderbooks/book |
| دفترهای یک کوین در همهٔ صرافیها | /orderbooks/coin/{coin} |
| تاریخچهٔ هزینهٔ اجرا | /orderbooks/exec-history |
| اسلیپیج DEX، مالیاتها و پرچم honeypot | /orderbooks/dex-slippage |
هر شش مورد جزو پلنهای API یعنی Pro و Max هستند. Pro ماهی 100 دلار است: 5 میلیون فراخوانی، 5 درخواست در ثانیه، تازگی 10 ثانیه. Max 200 دلار است: 10 میلیون فراخوانی، 15 درخواست در ثانیه، 5 ثانیه؛ در Trial و Start اندپوینتهای دفتر سفارش 403 plan_restricted برمیگردانند.
پارامترها و نمونه پاسخها در راهنمای اندپوینتهای دفتر سفارش است؛ برای مرور دادههای API، API ارز دیجیتال و درس دادههای API برای آربیتراژ را ببینید.
پرسش و پاسخ
چرا اسپرد جدول از چیزی که در معامله میگیرم بیشتر است؟
اسپرد ردیف از آخرین معاملات میآید، در حالی که سفارش بازاری با دفتر پر میشود و هر چه حجم بزرگتر باشد میانگین قیمتش بیشتر از بهترین قیمت دور میشود. کارمزدها و جابهجایی قیمت هنگام انتقال هم اضافه میشود. Δ دفتر سفارش نشان میدهد در حجم شما چه مقدار از اسپرد میماند.
دفترهای سفارش هر چند وقت بهروز میشوند؟
دفتر با هر سفارش جدید و لغو تغییر میکند؛ جریان Binance تغییرات را هر 100 یا 1000 میلیثانیه میفرستد. در Genesis API دفترها 5 تا 20 ثانیه از صرافی عقباند (سن در age_sec است) و پاسخها در Pro هر 10 ثانیه و در Max هر 5 ثانیه تازه میشوند.
آیا Genesis API برای دفترهای سفارش WebSocket دارد؟
نه. Genesis API فقط REST است: درخواست HTTP GET و پاسخ JSON. جریانهای لحظهای دفتر از WebSocket خود صرافیها میآید و ربات سفارشگذار از طریق API معاملاتی صرافی به همان نیاز دارد.
آیا API رایگان دفتر سفارش وجود دارد؟
صرافیها اندپوینت عمومی دارند: دفتر Binance در /api/v3/depth بدون کلید پاسخ میدهد، اما فقط یک صرافی را پوشش میدهد و قیمت اجرا را خودتان حساب میکنید. Genesis API پلن رایگان ندارد؛ دفترهای سفارش در Pro با ماهی 100 دلار و Max با 200 دلار گنجانده شدهاند.