آربی‌کوین
مستندات توسعه‌دهنده v1 ۲۱+ اندپوینت

راهنمای API رادار آربیتراژ

رادار آربیتراژ یک API استراحتی (REST) برای دسترسی برنامه‌نویسی به داده‌های زنده‌ی بازار رمزارز ایران ارائه می‌دهد. این API برای ساخت ربات‌های معاملاتی، داشبورد سفارشی، تحلیل داده و ادغام با سیستم‌های دیگر مناسب است. در این صفحه، تمام اندپوینت‌ها با مثال‌های عملی در curl، Python و JavaScript توضیح داده شده‌اند.

شروع سریع

تمام اندپوینت‌ها از مسیر /api/v1/ قابل دسترسی هستند. پایه‌ی URL:

https://arbradar.ir/api/v1/

اندپوینت‌های عمومی (قیمت، اسپرد، فرصت‌ها) بدون احراز هویت قابل دسترسی هستند. اندپوینت‌های مربوط به هشدار و تنظیمات شخصی نیاز به API Key دارند.

احراز هویت

برای اندپوینت‌های نیازمند احراز هویت، API Key خود را در هدرX-API-Keyارسال کنید. API Key را می‌توانید از داشبورد کاربری خود دریافت کنید.

هدر مورد نیاز

X-API-Key: your_api_key_here

هشدار امنیتی: هرگز API Key خود را در کد سمت‌کلاینت (مرورگر) قرار ندهید. همیشه از سرور استفاده کنید و کلید را در متغیر محیطی نگه دارید.

فهرست اندپوینت‌ها

GET/api/v1/health
وضعیت سامانه
بررسی وضعیت کلی سامانه، تعداد صرافی‌های آنلاین، نرخ مرجع تتر و زمان آخرین به‌روزرسانی.
GET/api/v1/assets
فهرست رمزارزها
دریافت فهرست کامل رمزارزهای پشتیبانی‌شده شامل نماد، نام فارسی و انگلیسی، رتبه و دسته‌بندی. قابل فیلتر با search و category.
GET/api/v1/exchanges
فهرست صرافی‌ها
دریافت فهرست صرافی‌های پشتیبانی‌شده (ایرانی و بین‌المللی) شامل نام، وب‌سایت، کارمزدها و وضعیت.
GET/api/v1/spreads
اسپردها
دریافت اسپردهای زنده بین صرافی‌ها. قابل فیلتر با exchange، asset، minSpreadPercent و sortBy.
GET/api/v1/spreads/top
بهترین اسپردها
دریافت N اسپرد برتر بر اساس درصد سود خالص.
GET/api/v1/arbitrage/opportunities
فرصت‌های آربیتراژ
دریافت فرصت‌های آربیتراژ محاسبه‌شده با در نظر گرفتن کارمزدها و هزینه‌ی انتقال.
GET/api/v1/prices/live
قیمت‌های زنده
دریافت قیمت‌های زنده‌ی تمام رمزارزها در تمام صرافی‌ها. مناسب برای مانیتورینگ بلادرنگ.
GET/api/v1/prices/{symbol}
قیمت یک رمزارز
دریافت قیمت‌های زنده‌ی یک رمزارز مشخص در تمام صرافی‌های پشتیبانی‌شده.
GET/api/v1/reference-rates/usdt
نرخ مرجع تتر
دریافت نرخ مرجع تتر/تومان محاسبه‌شده از میانگین صرافی‌های معتبر.
GET/api/v1/reference-rates/history
تاریخچه‌ی نرخ تتر
دریافت تاریخچه‌ی نرخ تتر برای رسم نمودار و تحلیل روند.
GET/api/v1/orderbook/{slug}
دفتر سفارش صرافی
دریافت عمق دفتر سفارش (Order Book) یک صرافی مشخص برای جفت‌ارز دل‌خواه.
GET/api/v1/history/{symbol}
تاریخچه‌ی قیمت رمزارز
دریافت تاریخچه‌ی قیمت یک رمزارز در یک صرافی مشخص برای تحلیل فنی.
GET/api/v1/fees
کارمزدها
دریافت کارمزدهای maker، taker و برداشت برای تمام صرافی‌ها.
GET/api/v1/stats
آمار سامانه
دریافت آمار کلی سامانه شامل تعداد درخواست‌ها، آپتایم و غیره.
GET/api/v1/top-volume
بیشترین حجم معاملات
دریافت رمزارزها و صرافی‌هایی با بیشترین حجم معاملات ۲۴ ساعته.
GET/api/v1/leveraged
بازارهای اهرم‌دار
دریافت اطلاعات بازارهای اهرم‌دار (فیوچرز) پشتیبانی‌شده توسط صرافی‌های ایرانی.
GET/api/v1/export/spreads
خروجی CSV اسپردها
دانلود اسپردهای زنده به‌صورت فایل CSV برای تحلیل در Excel.
GET/api/v1/export/prices
خروجی CSV قیمت‌ها
دانلود قیمت‌های زنده به‌صورت فایل CSV.
GET/api/v1/export/arbitrage
خروجی CSV آربیتراژ
دانلود فرصت‌های آربیتراژ به‌صورت فایل CSV.
GET/api/v1/alerts
هشدارها
دریافت لیست هشدارهای تنظیم‌شده‌ی کاربر. نیاز به API Key.
POST/api/v1/alerts
ایجاد هشدار
ایجاد هشدار جدید برای فرصت‌های آربیتراژ. نیاز به API Key.
DELETE/api/v1/alerts/{id}
حذف هشدار
حذف یک هشدار با شناسه. نیاز به API Key.

مثال ۱: دریافت قیمت‌های زنده

این مثال نحوه‌ی دریافت قیمت‌های زنده‌ی همه‌ی رمزارزها در تمام صرافی‌ها را نشان می‌دهد.

curl

curl -X GET "https://arbradar.ir/api/v1/prices/live" \
  -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://arbradar.ir/api/v1/prices/live",
    headers={"Accept": "application/json"},
)
data = response.json()

if data["success"]:
    for ticker in data["data"][:5]:
        print(f"{ticker['assetSymbol']}/{ticker['exchangeSlug']}: {ticker['priceToman']} Toman")

JavaScript (Node.js)

const response = await fetch("https://arbradar.ir/api/v1/prices/live", {
  headers: { Accept: "application/json" },
});
const data = await response.json();

if (data.success) {
  data.data.slice(0, 5).forEach((ticker) => {
    console.log(`${ticker.assetSymbol}/${ticker.exchangeSlug}: ${ticker.priceToman} Toman`);
  });
}

نمونه پاسخ

{
  "success": true,
  "data": [
    {
      "assetSymbol": "BTC",
      "exchangeSlug": "nobitex",
      "priceToman": 6500000000,
      "priceUsd": 65000,
      "bid": 6495000000,
      "ask": 6505000000,
      "volumeToman24h": 50000000000,
      "ageSeconds": 5
    }
  ],
  "meta": { "total": 348, "page": 1, "pageSize": 100 },
  "timestamp": 1717990200000,
  "requestId": "req_xyz123"
}

مثال ۲: دریافت فرصت‌های آربیتراژ

این مثال نحوه‌ی دریافت فرصت‌های آربیتراژ سودآور را نشان می‌دهد. می‌توانید با پارامتر minSpreadPercent فقط فرصت‌های با سود بالا را دریافت کنید.

curl

curl -X GET "https://arbradar.ir/api/v1/arbitrage/opportunities?minSpreadPercent=1.5&sortBy=netProfitPercent" \
  -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://arbradar.ir/api/v1/arbitrage/opportunities",
    params={
        "minSpreadPercent": 1.5,
        "sortBy": "netProfitPercent",
    },
    headers={"Accept": "application/json"},
)
data = response.json()

if data["success"]:
    print(f"Found {len(data['data'])} opportunities")
    for opp in data["data"][:5]:
        print(f"{opp['assetSymbol']}: buy on {opp['buyExchange']} at {opp['buyPrice']}, "
              f"sell on {opp['sellExchange']} at {opp['sellPrice']}, "
              f"net profit: {opp['netProfitPercent']}%")

JavaScript

const params = new URLSearchParams({
  minSpreadPercent: "1.5",
  sortBy: "netProfitPercent",
});
const response = await fetch(
  `https://arbradar.ir/api/v1/arbitrage/opportunities?${params}`,
  { headers: { Accept: "application/json" } },
);
const data = await response.json();

if (data.success) {
  console.log(`Found ${data.data.length} opportunities`);
  data.data.slice(0, 5).forEach((opp) => {
    console.log(`${opp.assetSymbol}: buy on ${opp.buyExchange}, sell on ${opp.sellExchange}, net: ${opp.netProfitPercent}%`);
  });
}

مثال ۳: دریافت نرخ مرجع تتر

این مثال نحوه‌ی دریافت نرخ مرجع تتر/تومان را نشان می‌دهد. این نرخ از میانگین چند صرافی معتبر محاسبه می‌شود.

curl

curl -X GET "https://arbradar.ir/api/v1/reference-rates/usdt" \
  -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://arbradar.ir/api/v1/reference-rates/usdt",
    headers={"Accept": "application/json"},
)
data = response.json()

if data["success"]:
    rate = data["data"]
    print(f"USDT/TMN reference rate: {rate['valueToman']} Toman")
    print(f"Sources: {rate['sourceCount']}")
    if rate.get("warning"):
        print(f"Warning: {rate['warning']}")

مثال ۴: ایجاد هشدار (نیازمند API Key)

این مثال نحوه‌ی ایجاد یک هشدار برای فرصت‌های آربیتراژ را نشان می‌دهد. این اندپوینت نیاز به API Key دارد.

curl

curl -X POST "https://arbradar.ir/api/v1/alerts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetSymbol": "BTC",
    "minSpreadPercent": 2.0,
    "notificationChannel": "telegram"
  }'

Python

import requests

response = requests.post(
    "https://arbradar.ir/api/v1/alerts",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "assetSymbol": "BTC",
        "minSpreadPercent": 2.0,
        "notificationChannel": "telegram",
    },
)
data = response.json()
print(f"Alert created with ID: {data['data']['id']}")

مثال ۵: خروجی CSV

برای تحلیل داده‌ها در Excel یا ابزارهای دیگر، می‌توانید داده‌ها را به‌صورت CSV دانلود کنید.

curl

# Download spreads as CSV
curl -X GET "https://arbradar.ir/api/v1/export/spreads" \
  -o spreads.csv

# Download arbitrage opportunities as CSV
curl -X GET "https://arbradar.ir/api/v1/export/arbitrage" \
  -o arbitrage.csv

Python (pandas)

import pandas as pd

# Read CSV directly into a DataFrame
df = pd.read_csv("https://arbradar.ir/api/v1/export/spreads")

# Show top 10 spreads by netProfitPercent
top = df.nlargest(10, "netProfitPercent")[
    ["assetSymbol", "buyExchange", "sellExchange", "netProfitPercent"]
]
print(top)

محدودیت نرخ (Rate Limit)

برای حفظ پایداری سرویس، محدودیت نرخ اعمال می‌شود. محدودیت‌های فعلی:

  • اندپوینت‌های عمومی: ۶۰ درخواست در دقیقه برای هر IP
  • اندپوینت‌های نیازمند API Key: ۳۰۰ درخواست در دقیقه برای هر کلید
  • اندپوینت‌های خروجی CSV: ۱۰ درخواست در دقیقه برای هر IP

هدرهای پاسخ شاملX-RateLimit-Limit،X-RateLimit-RemainingوX-RateLimit-Resetهستند که برای مدیریت درخواست‌ها مفیدند.

قالب پاسخ

تمام پاسخ‌ها به‌صورت JSON و با ساختار زیر هستند:

{
  "success": true,           // true/false
  "data": [],                // داده‌ی اصلی (array یا object)
  "meta": {                  // متادیتا (pagination و ...)
    "total": 348,
    "page": 1,
    "pageSize": 100
  },
  "timestamp": 1717990200000, // زمان پاسخ به میلی‌ثانیه
  "requestId": "req_xyz123"   // شناسه‌ی یکتا برای ردیابی
}

در صورت خطا:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter 'minSpreadPercent' must be a number"
  },
  "timestamp": 1717990200000,
  "requestId": "req_xyz123"
}

بهترین شیوه‌ها

توصیه می‌شود

  • از پارامترهای pagination استفاده کنید تا پاسخ‌ها سبک بمانند
  • برای مانیتورینگ بلادرنگ، هر ۵-۱۰ ثانیه poll کنید
  • API Key را در متغیر محیطی نگه دارید
  • از WebSocket برای داده‌ی بلادرنگ استفاده کنید (در صورت موجود بودن)
  • خطاهای 4xx و 5xx را به‌درستی مدیریت کنید
  • Retry با backoff برای خطاهای 5xx انجام دهید

توصیه نمی‌شود

  • Polling با فاصله‌ی کمتر از ۵ ثانیه
  • دریافت تمام داده‌ها در یک درخواست (بدون pagination)
  • قرار دادن API Key در کد سمت‌کلاینت
  • نادیده گرفتن خطاها بدون retry
  • ارسال درخواست موازی زیاد از یک IP
  • ذخیره‌ی موقت داده‌های حساس کاربر

آماده‌ی استفاده از API هستید؟

API Key خود را از داشبورد دریافت کنید و شروع به ساخت برنامه‌ی خود کنید.