شروع سریع
تمام اندپوینتها از مسیر /api/v1/ قابل دسترسی هستند. پایهی URL:
اندپوینتهای عمومی (قیمت، اسپرد، فرصتها) بدون احراز هویت قابل دسترسی هستند. اندپوینتهای مربوط به هشدار و تنظیمات شخصی نیاز به API Key دارند.
احراز هویت
برای اندپوینتهای نیازمند احراز هویت، API Key خود را در هدرX-API-Keyارسال کنید. API Key را میتوانید از داشبورد کاربری خود دریافت کنید.
هدر مورد نیاز
هشدار امنیتی: هرگز API Key خود را در کد سمتکلاینت (مرورگر) قرار ندهید. همیشه از سرور استفاده کنید و کلید را در متغیر محیطی نگه دارید.
فهرست اندپوینتها
/api/v1/health/api/v1/assets/api/v1/exchanges/api/v1/spreads/api/v1/spreads/top/api/v1/arbitrage/opportunities/api/v1/prices/live/api/v1/prices/{symbol}/api/v1/reference-rates/usdt/api/v1/reference-rates/history/api/v1/orderbook/{slug}/api/v1/history/{symbol}/api/v1/fees/api/v1/stats/api/v1/top-volume/api/v1/leveraged/api/v1/export/spreads/api/v1/export/prices/api/v1/export/arbitrage/api/v1/alerts/api/v1/alerts/api/v1/alerts/{id}مثال ۱: دریافت قیمتهای زنده
این مثال نحوهی دریافت قیمتهای زندهی همهی رمزارزها در تمام صرافیها را نشان میدهد.
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.csvPython (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 خود را از داشبورد دریافت کنید و شروع به ساخت برنامهی خود کنید.