مستندات API

رادار آربیتراژ کریپتو ایران — نسخه ۱ — ۳۰+ اندپوینت REST و WebSocket

بازگشت به داشبورد

همه‌ی اندپوینت‌ها زیر پیشوند /api/v1 قرار دارند. پاسخ موفق شامل فیلدهای success، data، meta، timestamp و requestId است و هدر X-Request-ID را نیز همراه دارد. پاسخ خطا شامل success: false و error.message است.

عمومی

17 اندپوینت

اندپوینت‌های عمومی و بدون نیاز به احراز هویت — سلامت سامانه، قیمت‌های زنده، اختلاف‌قیمت‌ها، دارایی‌ها، صرافی‌ها و نرخ مرجع.

GET/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_..."
}
GET/api/v1/stats
آمار درخواست‌های API و معیارهای سامانه — شامل تعداد تیکرها، اختلاف‌قیمت‌های معتبر، تعداد آربیتراژها و وضعیت فچر.

نمونه پاسخ

{
  "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 }
  }
}
GET/api/v1/spreads
فهرست اختلاف‌قیمت‌ها به‌صورت صفحه‌بندی‌شده با امکان فیلتر بر اساس صرافی، دارایی، نوع بازار و حداقل اختلاف/حجم و مرتب‌سازی.

پارامترها

نامنوعاجباریتوضیح
pagenumberخیرشماره صفحه (پیش‌فرض ۱)
pageSizenumberخیرتعداد آیتم در صفحه (پیش‌فرض ۱۰۰، حداکثر ۵۰۰)
exchangestringخیرslug صرافی (مثلاً nobitex)
assetstringخیرنماد دارایی (مثلاً BTC)
marketTypestringخیرنوع بازار: IRT | IRR | USDT
minSpreadPercentnumberخیرحداقل قدرمطلق اختلاف (٪)
minVolumeTomannumberخیرحداقل حجم ۲۴ساعته (تومان)
sortBystringخیرspreadPercent | netProfitPercent | volumeToman24h | ageSeconds
sortDirstringخیر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 }
}
GET/api/v1/spreads/top
بالاترین اختلاف‌قیمت‌ها (Top-N) — قابل فیلتر بر اساس جهت (مطلق/مثبت/منفی) و حداقل حجم. فقط رکوردهای معتبر برگردانده می‌شوند.

پارامترها

نامنوعاجباریتوضیح
limitnumberخیرتعداد آیتم (پیش‌فرض ۲۰، حداکثر ۱۰۰)
directionstringخیرabs | positive | negative (پیش‌فرض abs)
exchangestringخیرslug صرافی
minVolumeTomannumberخیرحداقل حجم ۲۴ساعته (تومان)

نمونه پاسخ

{
  "success": true,
  "data": [
    { "assetSymbol": "SHIB", "exchange": "ramzinex", "spreadPercent": 8.2, "volumeToman24h": 5400000000 }
  ],
  "meta": { "referenceRate": { "valueToman": 58000 }, "total": 23 }
}
GET/api/v1/prices/live
تیکرهای زنده‌ی نرمالایز شده — قیمت Bid/Ask/Last، حجم، تازگی و کیفیت داده به‌صورت صفحه‌بندی‌شده با فیلتر.

پارامترها

نامنوعاجباریتوضیح
exchangestringخیرslug صرافی
assetstringخیرنماد دارایی
marketTypestringخیرIRT | IRR | USDT
validbooleanخیرفقط تیکرهای معتبر (پیش‌فرض true)
minVolumeTomannumberخیرحداقل حجم ۲۴ساعته
pagenumberخیرشماره صفحه
pageSizenumberخیرتعداد آیتم

نمونه پاسخ

{
  "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 }
}
GET/api/v1/prices/{symbol}
قیمت یک دارایی مشخص در همه‌ی صرافی‌ها به‌همراه قیمت جهانی و اختلاف‌قیمت محاسبه‌شده.

پارامترها

نامنوعاجباریتوضیح
symbolstringبلهنماد دارایی در URL (مثلاً BTC)

نمونه پاسخ

{
  "success": true,
  "data": {
    "asset": { "symbol": "BTC", "nameFa": "بیت‌کوین", "rank": 1 },
    "global": { "priceUsd": 68250.5, "source": "coingecko" },
    "referenceRate": { "valueToman": 58000 },
    "tickers": [ /* ... */ ],
    "spreads": [ /* ... */ ]
  }
}
GET/api/v1/assets
فهرست دارایی‌های پشتیبانی‌شده با قابلیت جستجو و فیلتر بر اساس دسته‌بندی.

پارامترها

نامنوعاجباریتوضیح
searchstringخیرعبارت جستجو در نماد/نام فارسی/انگلیسی
categorystringخیردسته‌بندی دارایی
pagenumberخیرشماره صفحه
pageSizenumberخیرتعداد آیتم (پیش‌فرض ۲۰۰)

نمونه پاسخ

{
  "success": true,
  "data": [
    { "symbol": "BTC", "nameFa": "بیت‌کوین", "nameEn": "Bitcoin", "rank": 1, "category": "currency" }
  ],
  "meta": { "page": 1, "pageSize": 200, "total": 24, "totalPages": 1 }
}
GET/api/v1/assets/{symbol}
جزئیات کامل یک دارایی — متادیتا، قیمت جهانی، نرخ مرجع، تیکرها، اختلاف‌قیمت‌ها، آربیتراژ و بهترین خرید/فروش.

پارامترها

نامنوعاجباریتوضیح
symbolstringبلهنماد دارایی در 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 }
  }
}
GET/api/v1/assets/{symbol}/status
وضعیت واریز/برداشت تقریبی یک دارایی — شبکه‌های پشتیبانی‌شده از داده‌ی ثابت استخراج می‌شوند؛ برای وضعیت لحظه‌ای به پنل صرافی مراجعه کنید.

پارامترها

نامنوعاجباریتوضیح
symbolstringبلهنماد دارایی در URL

نمونه پاسخ

{
  "success": true,
  "data": {
    "asset": "USDT",
    "networks": ["ERC20", "TRC20", "BSC", "Matic", "TON", "Solana"],
    "depositEnabled": null,
    "withdrawEnabled": null,
    "note": "وضعیت دقیق از API عمومی قابل‌دسترسی نیست.",
    "lastChecked": 1694790180300
  }
}
GET/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 }
    }
  ]
}
GET/api/v1/exchanges/{slug}/status
وضعیت سلامت یک صرافی خاص به‌همراه همه‌ی تیکرهای آن صرافی.

پارامترها

نامنوعاجباریتوضیح
slugstringبلهشناسه صرافی در URL (مثلاً wallex)

نمونه پاسخ

{
  "success": true,
  "data": {
    "health": {
      "exchangeSlug": "wallex",
      "status": "online",
      "latencyMs": 98,
      "marketsCount": 22,
      "lastSuccessAt": 1694790175000,
      "rateLimited": false
    },
    "tickersCount": 22,
    "tickers": [ /* ... */ ]
  }
}
GET/api/v1/orderbook/{slug}
دفتر سفارشات زنده‌ی یک صرافی برای نماد داده‌شده. نماد کانونی (مثل BTC) به‌صورت خودکار به نماد بومی صرافی تبدیل می‌شود.

پارامترها

نامنوعاجباریتوضیح
slugstringبلهشناسه صرافی در URL
symbolstringبلهنماد کانونی دارایی (مثلاً BTC)
quotestringخیرIRT (پیش‌فرض) | USDT
depthnumberخیرتعداد سطح دفتر (پیش‌فرض ۵۰، حداکثر ۱۰۰)

نمونه پاسخ

{
  "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]]
  }
}
GET/api/v1/reference-rates/usdt
نرخ مرجع لحظه‌ای تتر (USDT) بر حسب تومان — محاسبه‌شده از چندین منبع.

نمونه پاسخ

{
  "success": true,
  "data": {
    "valueToman": 58000,
    "sourceCount": 5,
    "sources": ["nobitex", "wallex", "bitpin", "ramzinex", "abantether"],
    "calculationMethod": "median",
    "confidenceScore": 0.96,
    "warning": null,
    "timestamp": 1694790180000
  }
}
GET/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
    }
  ]
}
GET/api/v1/history/{symbol}
تاریخچه‌ی اختلاف‌قیمت یک دارایی از پایگاه‌داده (تا ۵۰۰ رکورد اخیر).

پارامترها

نامنوعاجباریتوضیح
symbolstringبلهنماد دارایی در URL
limitnumberخیرتعداد رکورد (پیش‌فرض ۱۰۰، حداکثر ۵۰۰)

نمونه پاسخ

{
  "success": true,
  "data": {
    "asset": { "symbol": "BTC", "nameFa": "بیت‌کوین" },
    "history": [
      {
        "timestamp": 1694790180000,
        "exchange": "nobitex",
        "fairPrice": 3960000000,
        "localPrice": 4060000000,
        "spreadToman": 100000000,
        "spreadPercent": 2.4,
        "netProfitPercent": 1.6
      }
    ]
  }
}
GET/api/v1/arbitrage/opportunities
فرصت‌های آربیتراژ بین صرافی‌ها — شامل سود ناخالص/خالص، کارمزدها، حجم قابل‌معامله و زمان انتقال.

پارامترها

نامنوعاجباریتوضیح
limitnumberخیرتعداد آیتم (پیش‌فرض ۵۰، حداکثر ۲۰۰)
assetstringخیرنماد دارایی
minNetProfitPercentnumberخیرحداقل سود خالص (٪، پیش‌فرض ۰.۳)
minVolumeTomannumberخیرحداقل حجم قابل‌معامله (تومان)

نمونه پاسخ

{
  "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 }
}
GET/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 و …).

GET/api/v1/alerts
فهرست همه‌ی هشدارهای پیکربندی‌شده با صفحه‌بندی.

پارامترها

نامنوعاجباریتوضیح
pagenumberخیرشماره صفحه
pageSizenumberخیرتعداد آیتم (پیش‌فرض ۱۰۰)

نمونه پاسخ

{
  "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 }
}
POST/api/v1/alerts
ایجاد هشدار جدید. بدنه‌ی JSON شامل نوع شرط، آستانه، کانال ارسال و زمان خنک‌شدن است.

پارامترها

نامنوعاجباریتوضیح
assetSymbolstringخیرنماد دارایی (یا null برای همه)
exchangeSlugstringخیرslug صرافی (یا null)
conditionTypestringبلهنوع شرط (مثلاً spread_above)
thresholdnumberخیرآستانه‌ی شرط
channelstringبلهکانال ارسال: telegram | webhook
telegramChatIdstringخیرشناسه چت تلگرام (اختیاری)
enabledbooleanخیرفعال/غیرفعال (پیش‌فرض true)
cooldownSecondsnumberخیرزمان خنک‌شدن (ثانیه)
notestringخیریادداشت (اختیاری)

نمونه پاسخ

// POST /api/v1/alerts
{ "assetSymbol": "BTC", "conditionType": "spread_above", "threshold": 5, "channel": "telegram" }

// 200 OK
{ "success": true, "data": { "id": "cm1abc...", "createdAt": 1694790000000 } }
PATCH/api/v1/alerts/{id}
ویرایش هشدار موجود. هر فیلد اختیاری است؛ فقط فیلدهای ارسالی به‌روزرسانی می‌شوند.

پارامترها

نامنوعاجباریتوضیح
idstringبلهشناسه هشدار در URL

نمونه پاسخ

// PATCH /api/v1/alerts/cm1abc...
{ "enabled": false, "threshold": 7 }

// 200 OK
{ "success": true, "data": { "id": "cm1abc...", "updatedAt": 1694790100000 } }
DELETE/api/v1/alerts/{id}
حذف هشدار با شناسه‌ی داده‌شده.

پارامترها

نامنوعاجباریتوضیح
idstringبلهشناسه هشدار در URL

نمونه پاسخ

{ "success": true, "data": { "id": "cm1abc...", "deleted": true } }
GET/api/v1/alerts/logs
لاگ رویدادهای هشدار — شامل پیام، دارایی، صرافی، مقدار و وضعیت ارسال.

پارامترها

نامنوعاجباریتوضیح
pagenumberخیرشماره صفحه
pageSizenumberخیرتعداد آیتم (پیش‌فرض ۵۰)

نمونه پاسخ

{
  "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 اندپوینت

اندپوینت‌های مدیریتی — ویرایش تنظیمات صرافی‌ها، کارمزدها، لاگ ممیزی و تحریک سیکل فچ. برخی اندپوینت‌ها به توکن مدیریت نیاز دارند.

GET/api/v1/admin/exchanges
فهرست همه‌ی صرافی‌ها با جزئیات کامل مدیریتی — شامل کارمزدها، وضعیت سلامت زنده، آخرین خطا و تنظیمات بازنویسی‌شده از DB.

نمونه پاسخ

{
  "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 }
}
PATCH/api/v1/admin/exchanges/{slug}
ویرایش تنظیمات یک صرافی — فعال/غیرفعال‌سازی، آدرس API، کارمزدها و زمان انتقال. نیاز به هدر Authorization با توکن مدیریت دارد. در صورت فعال‌سازی مجدد یا تغییر آدرس، یک سیکل فچ فوری تحریک می‌شود.

پارامترها

نامنوعاجباریتوضیح
slugstringبلهشناسه صرافی در URL
AuthorizationheaderبلهBearer <ADMIN_TOKEN>
enabledbooleanخیرفعال‌سازی/غیرفعال‌سازی
apiBaseUrlstringخیرآدرس جدید API صرافی
makerFeePercentnumberخیرکارمزد سازنده (٪)
takerFeePercentnumberخیرکارمزد برداشت‌کننده (٪)
withdrawalFeePercentnumberخیرکارمزد برداشت (٪)
networkFeeTomannumberخیرکارمزد شبکه (تومان)
minWithdrawalTomannumberخیرحداقل برداشت (تومان)
transferTimeMinutesnumberخیرزمان انتقال (دقیقه)
feesEstimatedbooleanخیرآیا کارمزدها تخمینی هستند؟

نمونه پاسخ

// 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"] } }
GET/api/v1/admin/audit-log
لاگ رویدادهای مدیریتی اخیر (نماینده‌ای از سیستم ممیزی). نیاز به توکن مدیریت.

پارامترها

نامنوعاجباریتوضیح
AuthorizationheaderبلهBearer <ADMIN_TOKEN>
pagenumberخیرشماره صفحه
pageSizenumberخیرتعداد آیتم (پیش‌فرض ۵۰)

نمونه پاسخ

{
  "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 }
}
POST/api/v1/refresh
تحریک یک سیکل فچ فوری در پس‌زمینه. داده به‌صورت غیرهمزمان به‌روز می‌شود؛ چند ثانیه بعد نتیجه در اندپوینت‌های عمومی قابل‌مشاهده است.

نمونه پاسخ

{
  "success": true,
  "data": {
    "triggered": true,
    "fetcherRunning": true,
    "sequenceIdBefore": 1240,
    "note": "دریافت داده در پس‌زمینه آغاز شد؛ چند ثانیه بعد داده به‌روز می‌شود."
  }
}
PATCH/api/v1/fees
به‌روزرسانی پیکربندی کارمزدهای یک یا چند صرافی به‌صورت گروهی. بدنه می‌تواند یک شیء یا آرایه‌ای از اشیاء باشد.

پارامترها

نامنوعاجباریتوضیح
exchangeSlugstringبلهشناسه صرافی
makerFeePercentnumberخیرکارمزد سازنده (٪)
takerFeePercentnumberخیرکارمزد برداشت‌کننده (٪)
withdrawalFeePercentnumberخیرکارمزد برداشت (٪)
networkFeeTomannumberخیرکارمزد شبکه (تومان)
minWithdrawalTomannumberخیرحداقل برداشت (تومان)
transferTimeMinutesnumberخیرزمان انتقال (دقیقه)
feesEstimatedbooleanخیرنشانگر تخمینی بودن کارمزدها

نمونه پاسخ

// 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 یا ابزارهای تحلیلی.

GET/api/v1/export/spreads
خروجی CSV از همه‌ی اختلاف‌قیمت‌های فعلی با امکان فیلتر بر اساس صرافی و حداقل اختلاف.

پارامترها

نامنوعاجباریتوضیح
exchangestringخیرslug صرافی
minSpreadnumberخیرحداقل قدرمطلق اختلاف (٪)

نمونه پاسخ

// 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
GET/api/v1/export/prices
خروجی CSV از همه‌ی تیکرهای زنده با امکان فیلتر بر اساس صرافی.

پارامترها

نامنوعاجباریتوضیح
exchangestringخیر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
GET/api/v1/export/arbitrage
خروجی CSV از همه‌ی فرصت‌های آربیتراژ فعلی — شامل صرافی خرید/فروش، سود ناخالص/خالص، کارمزدها و حجم قابل‌معامله.

نمونه پاسخ

// 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 در دسترس است.

WSwss://<host>/?XTransformPort=3003
اتصال Socket.IO به سرویس وب‌سوکت. مسیر path برابر «/» و transport برابر websocket است. اتصال با تأخیر ۲ ثانیه و حداکثر ۱۰ تلاش مجدد برقرار می‌شود.

نمونه پاسخ

// 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 });
});
WSevent: subscribe
رویداد خروجی کلاینت — اشتراک در فیلتر دلخواه. سرور تأیید را با رویداد subscribed برمی‌گرداند.

پارامترها

نامنوعاجباریتوضیح
assetstringخیرنماد دارایی (اختیاری)
exchangestringخیرslug صرافی (اختیاری)
minSpreadnumberخیرحداقل قدرمطلق اختلاف (اختیاری)

نمونه پاسخ

socket.emit("subscribe", { asset: "BTC", minSpread: 2 });
// سرور پاسخ می‌دهد:
// { "filters": { "asset": "BTC", "exchange": null, "minSpread": 2 } }
WSevent: unsubscribe
رویداد خروجی کلاینت — لغو همه‌ی فیلترها. سرور با رویداد unsubscribed تأیید می‌کند.

نمونه پاسخ

socket.emit("unsubscribe");
// { success: true } (acknowledged via "unsubscribed" event)
WSevent: 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
  }
}
WSevent: spreads_update
رویداد ورودی از سرور — فهرست اختلاف‌قیمت‌های برتر، فیلترشده بر اساس اشتراک کلاینت. هر ۵ ثانیه و فقط در صورت تغییر sequence ارسال می‌شود.

نمونه پاسخ

{
  "sequence_id": 1241,
  "timestamp": 1694790200000,
  "count": 3,
  "data": [
    { "assetSymbol": "BTC", "exchange": "nobitex", "spreadPercent": 2.4, "volumeToman24h": 120000000000 }
  ]
}
WSevent: arbitrage_update
رویداد ورودی از سرور — فهرست فرصت‌های آربیتراژ برتر، فیلترشده بر اساس اشتراک کلاینت.

نمونه پاسخ

{
  "sequence_id": 1241,
  "timestamp": 1694790200000,
  "count": 2,
  "data": [
    {
      "assetSymbol": "BTC",
      "buyExchange": "wallex",
      "sellExchange": "nobitex",
      "netProfitPercent": 0.18,
      "tradeableVolumeToman": 54000000000
    }
  ]
}