اندپوینتهای دفتر سفارش در Genesis API: قیمت اجرا، Δ دفتر سفارش، دفتر، تاریخچه و DEX
به طور خلاصه
- شش اندپوینت دفتر سفارش در پلنهای API Pro و Max همان دادهای را برمیگردانند که سایت در ستون «Δ بر اساس سفارشها»، پنجره «دفتر سفارش» و Genesis Charts نشان میدهد.
- قیمت اجرا میانگین قیمت یک معامله بازاری به ارزش 500، 1,000، 2,500، 5,000 یا 10,000 دلار است؛
nullیعنی دفتر برای این حجم کمعمق است. - دفترها 5 تا 20 ثانیه از صرافی عقباند:
age_secوstaleرا بررسی کنید و پیش از معامله دفتر را در ترمینال صرافی ببینید.
API دفتر سفارش در Genesis API شش اندپوینت است که نشان میدهد از یک اسپرد در معاملهای با حجم مشخص چه چیزی میماند. این اندپوینتها قیمت اجرا برای یک حجم، Δ دفتر سفارش برای ردیفهای آربیتراژ، دفتر سفارش با عمق آن، تاریخچه اسلیپیج و اسلیپیج DEX را برمیگردانند — همان دادهای که در ستون «Δ بر اساس سفارشها» و Genesis Charts سایت هست.
شش اندپوینت دفتر سفارش
| اندپوینت | چه برمیگرداند | الزامی | مستندات |
|---|---|---|---|
/orderbooks/exec | قیمت خرید و فروش برای یک حجم در هر بازار | volume | قیمتهای اجرا |
/orderbooks/spreads/{dataset} | Δ دفتر سفارش برای ردیفهای یک کوین در مجموعه داده آربیتراژ | coin | Δ دفتر سفارش |
/orderbooks/book | دفتر یک بازار: 10 سطح، دیوارها، عمق، سن | exchange، market، coin | دفتر سفارش بازار |
/orderbooks/coin/{coin} | دفترهای یک کوین در هر صرافی و بازار | کوین در مسیر | دفترهای سفارش کوین |
/orderbooks/exec-history | تاریخچه اسلیپیج، تا 8 بازار در هر درخواست | keys، interval | تاریخچه اجرا |
/orderbooks/dex-slippage | اسلیپیج، مالیاتها و پرچم honeypot برای هر قرارداد | — | اسلیپیج DEX |
هر شش مورد جزو پلنهای API Pro (100 دلار در ماه) و Max (200 دلار) هستند؛ در Trial و Start خطای 403 plan_restricted برمیگردد. در /orderbooks/exec و در پارامتر keys تاریخچه، بازار به شکل Exchange|market|COIN نوشته میشود، مثلاً Binance|spot|BTC. مثالهای پاسخ در ادامه فیلد data را کوتاهشده نشان میدهند.
برای مروری بر دادههای دفتر سفارش، مقاله API دفتر سفارش را ببینید.
قیمت اجرا برای یک حجم
قیمت اجرا میانگین قیمتی است که یک سفارش بازاری با حجم مشخص هنگام عبور از دفتر میگیرد: خرید askها را برمیدارد و فروش به bidها میخورد، پس همان VWAP سفارشهایی است که معامله مصرف میکند. /orderbooks/exec آن را برای هر بازار در یک حجم از شبکه برمیگرداند.
| پارامتر | نوع | کاربرد |
|---|---|---|
volume | عدد | حجم به دلار: 500، 1000، 2500، 5000 یا 10000، الزامی |
exchange | رشته | فیلتر بر اساس صرافی؛ برای چند صرافی با کاما جدا کنید |
market | رشته | spot یا futures |
coin | رشته | نماد کوین، مثلاً BTC |
curl "https://api.genesisarbitrage.com/v1/orderbooks/exec?volume=1000" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"volume": 1000,
"markets": {
"Binance|spot|BTC": [96021.5, 96010.2],
"ByBit|futures|BTC": [96030.1, 96018.7],
"Ourbit|spot|SHELL": [0.10418, null],
…
}
}
مقدار هر کلید بازار [قیمت خرید, قیمت فروش] است. null بهجای قیمت یعنی دفتر برای آن حجم کمعمق است: در مثال، bidهای SHELL در Ourbit فروشی به ارزش 1,000 دلار را جذب نمیکنند. بدون فیلتر، پاسخ همه بازارها را دارد؛ پس وقتی یک کوین میخواهید coin بدهید.
Δ دفتر سفارش: اسپرد پس از عبور از دفتر
Δ دفتر سفارش اسپرد یک ردیف آربیتراژ است که برای یک حجم مشخص از روی دفترهای سفارش دوباره محاسبه شده است. /orderbooks/spreads/{dataset} همه ردیفهای یک کوین را در مجموعه داده انتخابی میگیرد و به هر کدام شیء order_delta را اضافه میکند، با همان فرمولهای ستون سایت.
| پارامتر | نوع | کاربرد |
|---|---|---|
{dataset} | رشته، در مسیر | spot-spot، spot-futures، futures-futures، dex-spot یا dex-futures |
coin | رشته | نماد کوین، الزامی |
volume | عدد | پیشفرض 0 — بهترین قیمتهای دفتر؛ یا 500، 1000، 2500، 5000، 10000 |
در جفتهای CEX خرید از askهای exchange_buy عبور میکند و فروش به bidهای exchange_sell میرسد. order_delta شامل buy_price و sell_price است و نتیجه هرگز از spread_pct ردیف بیشتر نمیشود.
در ردیفهای DEX علامت اسپرد سمت CEX را تعیین میکند: وقتی spread_pct ≥ 0 باشد توکن به bidهای CEX فروخته میشود و وقتی منفی باشد از askها خریده میشود. order_delta شامل side و cex_price یعنی قیمت اجرا در CEX است؛ اگر پس از عبور از دفتر علامت برگردد، Δ برابر 0 است.
فیلد status: ok — محاسبه شد، no_book — دفتر نیست، exhausted — دفتر حجم را پر نکرد.
یک مثال فرضی: کوین XYZ، خرید در MEXC به قیمت 2.000 و فروش در Gate به قیمت 2.016، اسپرد ردیف 0.8%. درخواست Δ دفتر سفارش برای 5,000 دلار:
curl -G \
"https://api.genesisarbitrage.com/v1/orderbooks/spreads/spot-spot" \
-d coin=XYZ -d volume=5000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"coin": "XYZ",
"exchange_buy": "MEXC",
"exchange_sell": "Gate",
"market_buy": "spot",
"market_sell": "spot",
"price_buy": 2.0,
"price_sell": 2.016,
"ask_buy": 2.001,
"bid_sell": 2.015,
"spread_pct": 0.8,
"order_delta": {
"volume": 5000,
"buy_price": 2.004,
"sell_price": 2.01,
"spread_pct": 0.2994,
"status": "ok"
}
}
بقیه فیلدهای ردیف مانند /arbitrage/spot-spot است. اسپرد ردیف: (2.016 − 2.000) / 2.000 × 100 = 0.8%.
برای 5,000 دلار، خرید از دفتر MEXC بهطور میانگین 2.004 تمام میشود و فروش به دفتر Gate قیمت 2.010 میگیرد: (2.010 − 2.004) / 2.004 × 100 ≈ 0.2994%. از 0.8% در این حجم حدود 0.3% میماند — تقریباً 15 دلار پیش از کارمزدها و انتقال: 5,000 × 0.002994 ≈ 14.97.
نمونه Python: اسپرد پیش از دفتر و پس از آن
اسکریپت برای BTC در مجموعه Spot – Spot و 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"]}
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):
# محدودیت درخواست یا بازسازی داده
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
return r.json()["data"]
raise RuntimeError("API شلوغ است، بعداً دوباره تلاش کنید")
rows = get("/orderbooks/spreads/spot-spot",
{"coin": "BTC", "volume": 5000})
for row in rows:
od = row["order_delta"]
if od["status"] == "ok":
after = f'{od["spread_pct"]:.4f}%'
else:
after = od["status"] # no_book یا exhausted
print(f'{row["exchange_buy"]} → {row["exchange_sell"]}: '
f'{row["spread_pct"]}% → {after}')
در حلقه، بیش از یک بار در هر meta.freshness_sec ثانیه نظرسنجی نکنید: 10 ثانیه در Pro و 5 ثانیه در Max. سهمیه و محدودیتها در راهنمای محدودیتهای Genesis API آمده است.
دفتر سفارش بازار و دفترهای سفارش کوین
/orderbooks/book دفتر یک بازار را برمیگرداند، مانند پنجره «دفتر سفارش» سایت. سه پارامتر الزامی بازار را مشخص میکنند: exchange (بدون حساسیت به حروف)، market (spot یا futures) و coin. /orderbooks/coin/{coin} آرایهای از همین اشیاء را برای هر صرافی و بازار آن کوین برمیگرداند.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/book" \
-d exchange=Binance -d market=spot -d coin=BTC \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"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,
"best_bid": 96015.9,
"best_ask": 96016,
"bids": [[96015.9, 412300.5], [96015.8, 51020.3], …],
"asks": [[96016, 388120.2], [96016.1, 20410.7], …],
"walls_bid": [[95900, 2410000]],
"walls_ask": [[96500, 1980000]],
"depth_bid_usd": 61234567,
"depth_ask_usd": 58765432
}
| فیلد | معنی |
|---|---|
best_bid، best_ask | بهترین bid و ask |
bids، asks | 10 سطح برتر: [قیمت, مبلغ به دلار] |
walls_bid، walls_ask | بزرگترین دیوارها: [قیمت, مبلغ به دلار] |
depth_bid_usd، depth_ask_usd | عمق هر سمت در ±50% بهترین قیمت، به دلار |
book_ts، age_sec، stale | زمان دفتر و سن آن به ثانیه؛ stale — قدیمیتر از 30 ثانیه |
source، depth_limited | منبع دفتر (ws یا rest) و پرچم عمق محدود |
عمق بازار در depth_bid_usd و depth_ask_usd یعنی چند دلار سفارش در یک سمت دفتر هست: در مثال، حدود 58.8 میلیون دلار ask برای BTC در Binance تا +50% بهترین ask.
با depth_limited: true صرافی دفتر ناقص منتشر میکند و حجم بزرگ ممکن است پر نشود. اگر برای آن صرافی، بازار و کوین دفتری نباشد 404 میگیرید.
تاریخچه اجرا
/orderbooks/exec-history تاریخچه اسلیپیج از Genesis Charts است: هزینه اجرا در هر حجم شبکه، بر حسب بیسیسپوینت از میانه دفتر (1 bp = 0.01%). یک درخواست تا 8 بازار را در keys با کاما میپذیرد؛ interval الزامی است.
interval | گام نقطه | 360 نقطه پوشش میدهند |
|---|---|---|
1m | 1 دقیقه | 6 ساعت |
15m | 15 دقیقه | 3.75 روز |
1h | 1 ساعت | 15 روز |
1d | 1 روز | حدود یک سال |
داده از 6 سپتامبر 2026 جمع میشود، پس سری روزانه فقط از آن تاریخ پر است.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/exec-history" \
--data-urlencode "keys=Binance|spot|BTC,ByBit|futures|BTC" \
-d interval=1h \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"interval": "1h",
"step_sec": 3600,
"points": 360,
"volumes_usd": [500, 1000, 2500, 5000, 10000],
"last_bucket_ts": 1794672000,
"series": {
"Binance|spot|BTC": {
"buy": [[1, 1, 2, …], [1, 2, 2, …], [2, 3, 4, …],
[3, 4, 6, …], [5, 7, 9, …]],
"sell": [[-1, -1, -2, …], …]
},
"ByBit|futures|BTC": { … }
}
}
buy و sell هر کدام پنج سری دارند، یکی برای هر حجم در volumes_usd، و هر سری 360 مقدار از قدیمی به جدید. آخرین نقطه به last_bucket_ts تعلق دارد و نقطه i به last_bucket_ts − (points − 1 − i) × step_sec. مقدارهای خرید مثبت و فروش منفیاند: میانگین قیمت معامله بالا و پایین میانه دفتر است.
سری [5, 7, 9, …] خرید 10,000 دلاری است: نقطههای اولش 5 تا 9 bp هزینه دارند، یعنی 0.05 تا 0.09% بالاتر از میانه. null در سری یعنی داده نیست یا دفتر پر نشد؛ null بهجای شیء بازار یعنی کلید ناشناس.
اسلیپیج DEX
/orderbooks/dex-slippage پای DEX معامله را توصیف میکند: اسلیپیج خرید و فروش از 100 تا 100,000 دلار، مالیات توکن و پرچم honeypot برای هر قرارداد — مثل ستونهای جدول DEX در سایت. فیلترها: contract (برای چند مورد با کاما) و network.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/dex-slippage" \
-d contract=0x6982508145454ce325ddbe47a25d4ec3d2311933 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"sizes_usd": [100, 500, 1000, 2500, 5000, 10000, 20000, 50000,
100000],
"contracts": [
{
"contract": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
"network": "ETH",
"tax_buy_pct": 0,
"tax_sell_pct": 0,
"honeypot": "no",
"slippage_buy_pct": [0.31, 0.33, 0.36, 0.44, 0.58, 0.86,
1.41, 3.12, 6.05],
"slippage_sell_pct": [0.31, 0.34, 0.37, 0.46, 0.61, 0.9,
1.5, 3.3, 6.4],
"updated_at": 1794671040
}
]
}
آرایههای اسلیپیج از شبکه sizes_usd پیروی میکنند: در مثال خرید 5,000 دلاری 0.58% و خرید 100,000 دلاری 6.05% اسلیپیج دارد. null در آرایه یعنی استخر برای آن حجم نقدینگی ندارد.
tax_buy_pct و tax_sell_pct مالیات خرید و فروش توکن به درصد هستند؛ null یعنی منبعی نیست، نه 0%. honeypot: no؛ suspect — منابع همنظر نیستند؛ yes — شاید فروش ممکن نباشد.
چطور یک معامله را با دفترها بررسی کنیم
یک ردیف آربیتراژ بردارید
یک فرصت را در
/arbitrage/spot-spotیا مجموعه داده دیگر پیدا کنید — اندپوینتهای آربیتراژ را ببینید. کوین، صرافیها وspread_pctرا یادداشت کنید.اسپرد را از روی دفترها دوباره حساب کنید
/orderbooks/spreads/spot-spotرا با همان کوین و حجم معاملهتان صدا بزنید وspread_pctرا باorder_delta.spread_pctمقایسه کنید.تازگی و عمق را بررسی کنید
/orderbooks/bookرا برای هر دو پا صدا بزنید:age_sec،staleوdepth_limitedنشان میدهند به عددها اعتماد کنید یا نه و دیوارها نشان میدهند قیمت کجا ممکن است گیر کند.با تاریخچه مقایسه کنید
/orderbooks/exec-historyنشان میدهد این اسلیپیج برای بازار عادی است یا نه:1mشش ساعت و1hپانزده روز را پوشش میدهد.مالیات پای DEX را بررسی کنید
برای معاملههای DEX – Spot و DEX – Futures،
/orderbooks/dex-slippageرا برای قرارداد ردیف صدا بزنید: اسلیپیج، مالیات وhoneypot.
پرسش و پاسخ
Δ دفتر سفارش با اسپرد معمولی چه فرقی دارد؟
spread_pct ردیف از آخرین قیمت صرافیها استفاده میکند؛ Δ دفتر سفارش از میانگین قیمت معاملههای بازاری در حجم مشخص. تفاوت این دو همان چیزی است که دفتر میگیرد.
چرا بهجای قیمت null میگیرم؟
در /orderbooks/exec سفارشهای دفتر برای آن حجم کم است؛ در Δ دفتر سفارش همین حالت با وضعیت exhausted نشان داده میشود. در تاریخچه اجرا null یعنی برای آن نقطه داده نیست و در اسلیپیج DEX یعنی استخر نقدینگی ندارد.
آیا میشود اجرا را برای بیش از 10,000 دلار حساب کرد؟
شبکه /orderbooks/exec و Δ دفتر سفارش ثابت و از 500 تا 10,000 دلار است. برای حجمهای بزرگتر عمق و دیوارها را در /orderbooks/book ببینید؛ برای پای DEX، /orderbooks/dex-slippage تا 100,000 دلار میرود.