مستندات API
رادار آربیتراژ کریپتو ایران — نسخه ۱ — ۳۰+ اندپوینت REST و WebSocket
همهی اندپوینتها زیر پیشوند /api/v1 قرار دارند. پاسخ موفق شامل فیلدهای success، data، meta، timestamp و requestId است و هدر X-Request-ID را نیز همراه دارد. پاسخ خطا شامل success: false و error.message است.
عمومی
17 اندپوینتاندپوینتهای عمومی و بدون نیاز به احراز هویت — سلامت سامانه، قیمتهای زنده، اختلافقیمتها، داراییها، صرافیها و نرخ مرجع.
/api/v1/healthنمونه پاسخ
{
"success": true,
"data": {
"status": "ok",
"fetcher": { "running": true, "startedAt": 1694790000000 },
"cycleCount": 1240,
"sequenceId": 1240,
"lastUpdate": 1694790180000,
"nextUpdate": 1694790200000,
"refreshIntervalMs": 20000,
"dataAgeSeconds": 3,
"exchanges": { "online": 8, "delayed": 0, "error": 0, "total": 8 },
"assetsTracked": 24,
"referenceRate": 58000,
"spreadCount": 192,
"arbitrageCount": 17
},
"meta": {},
"timestamp": 1694790180300,
"requestId": "req_..."
}/api/v1/statsنمونه پاسخ
{
"success": true,
"data": {
"api": { "totalRequests": 15432, "errorRate": 0.012 },
"fetcher": { "running": true, "cycleCount": 1240, "sequenceId": 1240 },
"data": {
"assetsTracked": 24,
"assetsWithPrice": 23,
"totalTickers": 192,
"validTickers": 178,
"spreadCount": 192,
"arbitrageCount": 17,
"onlineExchanges": 8
},
"referenceRate": { "valueToman": 58000, "sourceCount": 5 }
}
}/api/v1/spreadsپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| page | number | خیر | شماره صفحه (پیشفرض ۱) |
| pageSize | number | خیر | تعداد آیتم در صفحه (پیشفرض ۱۰۰، حداکثر ۵۰۰) |
| exchange | string | خیر | slug صرافی (مثلاً nobitex) |
| asset | string | خیر | نماد دارایی (مثلاً BTC) |
| marketType | string | خیر | نوع بازار: IRT | IRR | USDT |
| minSpreadPercent | number | خیر | حداقل قدرمطلق اختلاف (٪) |
| minVolumeToman | number | خیر | حداقل حجم ۲۴ساعته (تومان) |
| sortBy | string | خیر | spreadPercent | netProfitPercent | volumeToman24h | ageSeconds |
| sortDir | string | خیر | asc | desc (پیشفرض desc) |
نمونه پاسخ
{
"success": true,
"data": [
{
"assetSymbol": "BTC",
"exchange": "nobitex",
"marketType": "IRT",
"spreadPercent": 2.4,
"netProfitPercent": 1.6,
"localLastToman": 4060000000,
"fairPriceToman": 3960000000,
"volumeToman24h": 120000000000,
"freshness": "fresh",
"ageSeconds": 4,
"isValid": true
}
],
"meta": { "page": 1, "pageSize": 100, "total": 192, "totalPages": 2 }
}/api/v1/spreads/topپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| limit | number | خیر | تعداد آیتم (پیشفرض ۲۰، حداکثر ۱۰۰) |
| direction | string | خیر | abs | positive | negative (پیشفرض abs) |
| exchange | string | خیر | slug صرافی |
| minVolumeToman | number | خیر | حداقل حجم ۲۴ساعته (تومان) |
نمونه پاسخ
{
"success": true,
"data": [
{ "assetSymbol": "SHIB", "exchange": "ramzinex", "spreadPercent": 8.2, "volumeToman24h": 5400000000 }
],
"meta": { "referenceRate": { "valueToman": 58000 }, "total": 23 }
}/api/v1/prices/liveپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| exchange | string | خیر | slug صرافی |
| asset | string | خیر | نماد دارایی |
| marketType | string | خیر | IRT | IRR | USDT |
| valid | boolean | خیر | فقط تیکرهای معتبر (پیشفرض true) |
| minVolumeToman | number | خیر | حداقل حجم ۲۴ساعته |
| page | number | خیر | شماره صفحه |
| pageSize | number | خیر | تعداد آیتم |
نمونه پاسخ
{
"success": true,
"data": [
{
"exchange": "nobitex",
"assetSymbol": "BTC",
"marketType": "IRT",
"bidToman": 4055000000,
"askToman": 4062000000,
"lastToman": 4060000000,
"volumeToman24h": 120000000000,
"freshness": "fresh",
"ageSeconds": 4,
"isValid": true
}
],
"meta": { "page": 1, "pageSize": 100, "total": 192, "lastUpdate": 1694790180000 }
}/api/v1/prices/{symbol}پارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| symbol | string | بله | نماد دارایی در URL (مثلاً BTC) |
نمونه پاسخ
{
"success": true,
"data": {
"asset": { "symbol": "BTC", "nameFa": "بیتکوین", "rank": 1 },
"global": { "priceUsd": 68250.5, "source": "coingecko" },
"referenceRate": { "valueToman": 58000 },
"tickers": [ /* ... */ ],
"spreads": [ /* ... */ ]
}
}/api/v1/assetsپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| search | string | خیر | عبارت جستجو در نماد/نام فارسی/انگلیسی |
| category | string | خیر | دستهبندی دارایی |
| page | number | خیر | شماره صفحه |
| pageSize | number | خیر | تعداد آیتم (پیشفرض ۲۰۰) |
نمونه پاسخ
{
"success": true,
"data": [
{ "symbol": "BTC", "nameFa": "بیتکوین", "nameEn": "Bitcoin", "rank": 1, "category": "currency" }
],
"meta": { "page": 1, "pageSize": 200, "total": 24, "totalPages": 1 }
}/api/v1/assets/{symbol}پارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| symbol | string | بله | نماد دارایی در URL |
نمونه پاسخ
{
"success": true,
"data": {
"asset": { "symbol": "BTC", "nameFa": "بیتکوین" },
"global": { "priceUsd": 68250.5 },
"referenceRate": { "valueToman": 58000 },
"fairPriceToman": 3958500000,
"bestBuy": { "exchange": "wallex", "price": 4058000000, "marketType": "IRT" },
"bestSell": { "exchange": "nobitex", "price": 4062000000, "marketType": "IRT" },
"summary": { "marketsCount": 8, "maxSpreadPercent": 2.4, "volumeToman24h": 540000000000 }
}
}/api/v1/assets/{symbol}/statusپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| symbol | string | بله | نماد دارایی در URL |
نمونه پاسخ
{
"success": true,
"data": {
"asset": "USDT",
"networks": ["ERC20", "TRC20", "BSC", "Matic", "TON", "Solana"],
"depositEnabled": null,
"withdrawEnabled": null,
"note": "وضعیت دقیق از API عمومی قابلدسترسی نیست.",
"lastChecked": 1694790180300
}
}/api/v1/exchangesنمونه پاسخ
{
"success": true,
"data": [
{
"slug": "nobitex",
"name": "Nobitex",
"nameFa": "نوبیتکس",
"enabled": true,
"implemented": true,
"supportsIrt": true,
"status": "online",
"latencyMs": 142,
"marketsCount": 24,
"uptime": { "percentage": 99.8, "totalCycles": 1240, "successCycles": 1237 }
}
]
}/api/v1/exchanges/{slug}/statusپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| slug | string | بله | شناسه صرافی در URL (مثلاً wallex) |
نمونه پاسخ
{
"success": true,
"data": {
"health": {
"exchangeSlug": "wallex",
"status": "online",
"latencyMs": 98,
"marketsCount": 22,
"lastSuccessAt": 1694790175000,
"rateLimited": false
},
"tickersCount": 22,
"tickers": [ /* ... */ ]
}
}/api/v1/orderbook/{slug}پارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| slug | string | بله | شناسه صرافی در URL |
| symbol | string | بله | نماد کانونی دارایی (مثلاً BTC) |
| quote | string | خیر | IRT (پیشفرض) | USDT |
| depth | number | خیر | تعداد سطح دفتر (پیشفرض ۵۰، حداکثر ۱۰۰) |
نمونه پاسخ
{
"success": true,
"data": {
"slug": "wallex",
"symbol": "BTC",
"nativeSymbol": "btcrls",
"supported": true,
"bestBid": 4055000000,
"bestAsk": 4062000000,
"spread": 7000000,
"spreadPercent": 0.17,
"bidVolume": 1.42,
"askVolume": 0.87,
"bids": [[4055000000, 0.32], [4054000000, 0.5]],
"asks": [[4062000000, 0.21], [4064000000, 0.4]]
}
}/api/v1/reference-rates/usdtنمونه پاسخ
{
"success": true,
"data": {
"valueToman": 58000,
"sourceCount": 5,
"sources": ["nobitex", "wallex", "bitpin", "ramzinex", "abantether"],
"calculationMethod": "median",
"confidenceScore": 0.96,
"warning": null,
"timestamp": 1694790180000
}
}/api/v1/reference-rates/historyنمونه پاسخ
{
"success": true,
"data": [
{
"timestamp": 1694790180000,
"valueToman": 58000,
"sourceCount": 5,
"sources": ["nobitex", "wallex", "bitpin", "ramzinex", "abantether"],
"calculationMethod": "median",
"confidenceScore": 0.96,
"warning": null
}
]
}/api/v1/history/{symbol}پارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| symbol | string | بله | نماد دارایی در URL |
| limit | number | خیر | تعداد رکورد (پیشفرض ۱۰۰، حداکثر ۵۰۰) |
نمونه پاسخ
{
"success": true,
"data": {
"asset": { "symbol": "BTC", "nameFa": "بیتکوین" },
"history": [
{
"timestamp": 1694790180000,
"exchange": "nobitex",
"fairPrice": 3960000000,
"localPrice": 4060000000,
"spreadToman": 100000000,
"spreadPercent": 2.4,
"netProfitPercent": 1.6
}
]
}
}/api/v1/arbitrage/opportunitiesپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| limit | number | خیر | تعداد آیتم (پیشفرض ۵۰، حداکثر ۲۰۰) |
| asset | string | خیر | نماد دارایی |
| minNetProfitPercent | number | خیر | حداقل سود خالص (٪، پیشفرض ۰.۳) |
| minVolumeToman | number | خیر | حداقل حجم قابلمعامله (تومان) |
نمونه پاسخ
{
"success": true,
"data": [
{
"assetSymbol": "BTC",
"assetNameFa": "بیتکوین",
"buyExchange": "wallex",
"sellExchange": "nobitex",
"buyAskToman": 4058000000,
"sellBidToman": 4062000000,
"grossProfitPercent": 0.41,
"netProfitPercent": 0.18,
"buyFeePercent": 0.4,
"sellFeePercent": 0.35,
"withdrawalFeePercent": 0.1,
"estimatedSlippagePercent": 0.05,
"tradeableVolumeToman": 54000000000
}
],
"meta": { "total": 17, "lastUpdate": 1694790180000 }
}/api/v1/feesنمونه پاسخ
{
"success": true,
"data": [
{
"exchangeSlug": "nobitex",
"makerFeePercent": 0.35,
"takerFeePercent": 0.4,
"withdrawalFeePercent": 0.1,
"networkFeeToman": 0,
"minWithdrawalToman": 0,
"transferTimeMinutes": 10,
"feesEstimated": true
}
]
}هشدارها
5 اندپوینتمدیریت هشدارها — ایجاد، ویرایش، حذف و مشاهدهی لاگ هشدارهای ارسالشده (Telegram و …).
/api/v1/alertsپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| page | number | خیر | شماره صفحه |
| pageSize | number | خیر | تعداد آیتم (پیشفرض ۱۰۰) |
نمونه پاسخ
{
"success": true,
"data": [
{
"id": "cm1abc...",
"assetSymbol": "BTC",
"exchangeSlug": "nobitex",
"conditionType": "spread_above",
"threshold": 5,
"channel": "telegram",
"enabled": true,
"cooldownSeconds": 300,
"lastTriggeredAt": null,
"createdAt": 1694790000000
}
],
"meta": { "page": 1, "pageSize": 100, "total": 1, "telegramConfigured": true }
}/api/v1/alertsپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| assetSymbol | string | خیر | نماد دارایی (یا null برای همه) |
| exchangeSlug | string | خیر | slug صرافی (یا null) |
| conditionType | string | بله | نوع شرط (مثلاً spread_above) |
| threshold | number | خیر | آستانهی شرط |
| channel | string | بله | کانال ارسال: telegram | webhook |
| telegramChatId | string | خیر | شناسه چت تلگرام (اختیاری) |
| enabled | boolean | خیر | فعال/غیرفعال (پیشفرض true) |
| cooldownSeconds | number | خیر | زمان خنکشدن (ثانیه) |
| note | string | خیر | یادداشت (اختیاری) |
نمونه پاسخ
// POST /api/v1/alerts
{ "assetSymbol": "BTC", "conditionType": "spread_above", "threshold": 5, "channel": "telegram" }
// 200 OK
{ "success": true, "data": { "id": "cm1abc...", "createdAt": 1694790000000 } }/api/v1/alerts/{id}پارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| id | string | بله | شناسه هشدار در URL |
نمونه پاسخ
// PATCH /api/v1/alerts/cm1abc...
{ "enabled": false, "threshold": 7 }
// 200 OK
{ "success": true, "data": { "id": "cm1abc...", "updatedAt": 1694790100000 } }/api/v1/alerts/{id}پارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| id | string | بله | شناسه هشدار در URL |
نمونه پاسخ
{ "success": true, "data": { "id": "cm1abc...", "deleted": true } }/api/v1/alerts/logsپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| page | number | خیر | شماره صفحه |
| pageSize | number | خیر | تعداد آیتم (پیشفرض ۵۰) |
نمونه پاسخ
{
"success": true,
"data": [
{
"id": "cm1log...",
"alertId": "cm1abc...",
"message": "اختلاف BTC در نوبیتکس به ۶.۲٪ رسید",
"assetSymbol": "BTC",
"exchangeSlug": "nobitex",
"value": 6.2,
"sent": true,
"timestamp": 1694790150000
}
],
"meta": { "page": 1, "pageSize": 50, "total": 12, "totalPages": 1 }
}مدیریت
5 اندپوینتاندپوینتهای مدیریتی — ویرایش تنظیمات صرافیها، کارمزدها، لاگ ممیزی و تحریک سیکل فچ. برخی اندپوینتها به توکن مدیریت نیاز دارند.
/api/v1/admin/exchangesنمونه پاسخ
{
"success": true,
"data": [
{
"slug": "nobitex",
"name": "Nobitex",
"nameFa": "نوبیتکس",
"apiBaseUrl": "https://apiv2.nobitex.ir",
"enabled": true,
"implemented": true,
"makerFeePercent": 0.35,
"takerFeePercent": 0.4,
"withdrawalFeePercent": 0.1,
"status": "online",
"latencyMs": 142,
"marketsCount": 24,
"lastSuccessAt": 1694790175000,
"lastError": null,
"rateLimited": false,
"updatedAt": 1694790100000
}
],
"meta": { "adminTokenConfigured": true }
}/api/v1/admin/exchanges/{slug}پارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| slug | string | بله | شناسه صرافی در URL |
| Authorization | header | بله | Bearer <ADMIN_TOKEN> |
| enabled | boolean | خیر | فعالسازی/غیرفعالسازی |
| apiBaseUrl | string | خیر | آدرس جدید API صرافی |
| makerFeePercent | number | خیر | کارمزد سازنده (٪) |
| takerFeePercent | number | خیر | کارمزد برداشتکننده (٪) |
| withdrawalFeePercent | number | خیر | کارمزد برداشت (٪) |
| networkFeeToman | number | خیر | کارمزد شبکه (تومان) |
| minWithdrawalToman | number | خیر | حداقل برداشت (تومان) |
| transferTimeMinutes | number | خیر | زمان انتقال (دقیقه) |
| feesEstimated | boolean | خیر | آیا کارمزدها تخمینی هستند؟ |
نمونه پاسخ
// PATCH /api/v1/admin/exchanges/nobitex
// Authorization: Bearer <ADMIN_TOKEN>
{ "enabled": true, "takerFeePercent": 0.38 }
// 200 OK
{ "success": true, "data": { "slug": "nobitex", "updatedAt": 1694790100000, "fieldsChanged": ["takerFeePercent"] } }/api/v1/admin/audit-logپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| Authorization | header | بله | Bearer <ADMIN_TOKEN> |
| page | number | خیر | شماره صفحه |
| pageSize | number | خیر | تعداد آیتم (پیشفرض ۵۰) |
نمونه پاسخ
{
"success": true,
"data": [
{
"id": "cm1log...",
"message": "تنظیمات صرافی نوبیتکس بهروزرسانی شد",
"assetSymbol": null,
"exchangeSlug": "nobitex",
"value": null,
"sent": false,
"timestamp": 1694790100000
}
],
"meta": { "page": 1, "pageSize": 50, "total": 5, "totalPages": 1 }
}/api/v1/refreshنمونه پاسخ
{
"success": true,
"data": {
"triggered": true,
"fetcherRunning": true,
"sequenceIdBefore": 1240,
"note": "دریافت داده در پسزمینه آغاز شد؛ چند ثانیه بعد داده بهروز میشود."
}
}/api/v1/feesپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| exchangeSlug | string | بله | شناسه صرافی |
| makerFeePercent | number | خیر | کارمزد سازنده (٪) |
| takerFeePercent | number | خیر | کارمزد برداشتکننده (٪) |
| withdrawalFeePercent | number | خیر | کارمزد برداشت (٪) |
| networkFeeToman | number | خیر | کارمزد شبکه (تومان) |
| minWithdrawalToman | number | خیر | حداقل برداشت (تومان) |
| transferTimeMinutes | number | خیر | زمان انتقال (دقیقه) |
| feesEstimated | boolean | خیر | نشانگر تخمینی بودن کارمزدها |
نمونه پاسخ
// PATCH /api/v1/fees
[{ "exchangeSlug": "nobitex", "takerFeePercent": 0.38 }, { "exchangeSlug": "wallex", "makerFeePercent": 0.33 }]
// 200 OK
{ "success": true, "data": { "updated": ["nobitex", "wallex"] } }خروجی (CSV)
3 اندپوینتاندپوینتهای خروجی گرفتن از دادههای فعلی بهصورت CSV — برای استفاده در Excel یا ابزارهای تحلیلی.
/api/v1/export/spreadsپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| exchange | string | خیر | slug صرافی |
| minSpread | number | خیر | حداقل قدرمطلق اختلاف (٪) |
نمونه پاسخ
// GET /api/v1/export/spreads?exchange=nobitex&minSpread=1
// 200 OK — text/csv; attachment
asset,assetNameFa,exchange,marketType,globalPriceUsd,referenceRateToman,fairPriceToman,localBidToman,localAskToman,localLastToman,spreadToman,spreadPercent,netProfitPercent,volumeToman24h,freshness,ageSeconds,dataQuality,timestamp
BTC,بیتکوین,nobitex,IRT,68250.5,58000,3960000000,4055000000,4062000000,4060000000,100000000,2.40,1.60,120000000000,fresh,4,high,2025-09-15T12:36:20.000Z/api/v1/export/pricesپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| exchange | string | خیر | slug صرافی |
نمونه پاسخ
// GET /api/v1/export/prices?exchange=wallex
// 200 OK — text/csv; attachment
asset,exchange,marketType,bidToman,askToman,lastToman,volumeToman24h,freshness,ageSeconds,qualityScore,isValid,timestamp
BTC,wallex,IRT,4055000000,4062000000,4060000000,120000000000,fresh,4,0.92,true,2025-09-15T12:36:20.000Z/api/v1/export/arbitrageنمونه پاسخ
// GET /api/v1/export/arbitrage
// 200 OK — text/csv; attachment
asset,assetNameFa,buyExchange,sellExchange,buyAskToman,sellBidToman,grossProfitPercent,netProfitPercent,buyFeePercent,sellFeePercent,withdrawalFeePercent,networkFeeToman,estimatedSlippagePercent,tradeableVolumeToman,isIndicative,transferNote,timestamp
BTC,بیتکوین,wallex,nobitex,4058000000,4062000000,0.41,0.18,0.4,0.35,0.1,0,0.05,54000000000,false,transfer_minutes=10,2025-09-15T12:36:20.000Zوبسوکت
6 اندپوینتاتصال زندهی وبسوکت برای دریافت بهروزرسانیهای لحظهای بازار از طریق Socket.IO. سرویس روی پورت ۳۰۰۳ اجرا میشود و از طریق Caddy Gateway در دسترس است.
wss://<host>/?XTransformPort=3003نمونه پاسخ
// Client (TypeScript)
import { io } from "socket.io-client";
const socket = io("/?XTransformPort=3003", {
path: "/",
transports: ["websocket"],
reconnection: true,
reconnectionDelay: 2000,
reconnectionAttempts: 10,
});
socket.on("connect", () => {
socket.emit("subscribe", { asset: "BTC", exchange: "nobitex", minSpread: 1 });
});event: subscribeپارامترها
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| asset | string | خیر | نماد دارایی (اختیاری) |
| exchange | string | خیر | slug صرافی (اختیاری) |
| minSpread | number | خیر | حداقل قدرمطلق اختلاف (اختیاری) |
نمونه پاسخ
socket.emit("subscribe", { asset: "BTC", minSpread: 2 });
// سرور پاسخ میدهد:
// { "filters": { "asset": "BTC", "exchange": null, "minSpread": 2 } }event: unsubscribeنمونه پاسخ
socket.emit("unsubscribe");
// { success: true } (acknowledged via "unsubscribed" event)event: market_updateنمونه پاسخ
{
"event_type": "market_update",
"sequence_id": 1241,
"timestamp": 1694790200000,
"summary": {
"onlineExchanges": 8,
"totalExchanges": 8,
"referenceRate": 58000,
"spreadCount": 192,
"arbitrageCount": 17,
"assetsWithPrice": 23,
"lastUpdate": 1694790180000
}
}event: spreads_updateنمونه پاسخ
{
"sequence_id": 1241,
"timestamp": 1694790200000,
"count": 3,
"data": [
{ "assetSymbol": "BTC", "exchange": "nobitex", "spreadPercent": 2.4, "volumeToman24h": 120000000000 }
]
}event: arbitrage_updateنمونه پاسخ
{
"sequence_id": 1241,
"timestamp": 1694790200000,
"count": 2,
"data": [
{
"assetSymbol": "BTC",
"buyExchange": "wallex",
"sellExchange": "nobitex",
"netProfitPercent": 0.18,
"tradeableVolumeToman": 54000000000
}
]
}