API توسعه‌دهندگان

📘 شروع سریع

همه درخواست‌ها GET هستند و پاسخ application/json; charset=utf-8 برمی‌گردانند. آدرس پایه:

# همه قیمت‌ها
curl https://ibahoosham.ir/arzprice/w-api/prices/

# فقط دسته طلا
curl https://ibahoosham.ir/arzprice/w-api/category/gold

# تاریخچه ۷ روزه دلار
curl "https://ibahoosham.ir/arzprice/w-api/history/?symbol=USD&range=7d"

🧪 کنسول API — Playground جدید v4.11

اندپوینت را انتخاب (یا مسیر دلخواه‌تان را بنویسید) و «اجرا» بزنید — پاسخ واقعی همین لحظه از سرور ارزپرایس برمی‌گردد:

💡 مسیرها نسبت به w-api/ هستند (مثلاً prices/ یا history/?symbol=USD&range=7d). این کنسول مستقیم از مرورگر شما به API وصل می‌شود — همان محدودیت نرخ ۱۲۰ درخواست/دقیقه اعمال می‌شود.

🧩 ویجت امبد برای سایت شما جدید v4.12

قیمت‌های زنده ارزپرایس را با دو خط کد در هر سایت یا وبلاگی نمایش دهید — iframe امن، ریسپانسیو و با به‌روزرسانی خودکار هر ۶۰ ثانیه. پیش‌نمایش واقعی همین‌جا (با همان لودر widget.js):

<script src="https://ibahoosham.ir/arzprice/widget.js" async></script>
<div data-arzprice-widget
     data-symbols="دلار آمریکا,یورو,بیت‌کوین"
     data-theme="dark"
     data-rows="6"
     data-height="420"></div>

پیش‌نمایش مستقیم آدرس هم ممکن است: /arzprice/embed/?symbols=USD,EUR&theme=dark&rows=6 — فید RSS اخبار: /rss 📡

📚 اندپوینت‌های عمومی

🎯 ساختار پاسخ w-api/prices/

{
  "ok": true,
  "count": 106,
  "items": [
    {
      "symbol": "USD",
      "name": "دلار آمریکا",
      "category": "currency",
      "price": 2643050,
      "unit": "rial",       // rial | usd
      "changePercent": -0.3,
      "high": 2646100, "low": 2643050, "open": 2643050,
      "timestamp": "2026-10-11T20:23:41",
      "emoji": "🇺🇸",
      "slug": "USD",
      "url": "https://ibahoosham.ir/arzprice/p/currency/USD"
    }
  ]
}

🔐 اندپوینت‌های نیازمند ورود

این‌ها با session کوکی مرورگر کاربر کار می‌کنند و برای استفاده مستقیم مناسب نیستند:

🪝 وب‌هوک‌ها (Webhooks) v4.9 · ۳ رویداد در v4.10

به‌جای polling، رویدادهای بازار را به‌صورت POST با JSON دریافت کنید: جابه‌جایی قیمت، نوسان مهم و آلارم کاربران. مدیریت وب‌هوک‌ها از صفحه /webhooks 🪝 (نیازمند ورود) — تا ۵ وب‌هوک برای هر حساب.

انواع رویداد (هدر X-ArzPrice-Event)

{
  "event": "price_change",
  "source": "arzprice",
  "symbol": "BTC/IRT",
  "name": "بیت کوین",
  "category": "crypto",
  "price": 219020000030,
  "price_fmt": "۲۱۹٬۰۲۰٬۰۰۰٬۰۳۰ ریال",
  "unit": "rial",
  "change_pct": -0.16,
  "direction": "down",
  "high": 21999779998, "low": 21901695369, "open": 21936648987,
  "instrument_url": "https://ibahoosham.ir/arzprice/p/crypto/btcirt",
  "sent_at": "2026-10-12T09:00:00Z"
}

تأیید امضا سمت شما — روش جدید زمان‌دار (توصیه‌شده؛ جلوگیری از replay attack):

// $body = file_get_contents('php://input');
$m = [];
if (!preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_X_ARZPRICE_SIGNATURE'] ?? '', $m)) {
    http_response_code(401); exit;
}
// ۱) امضا معتبر؟  ۲) فاصله زمانی کمتر از ۵ دقیقه؟ (جلوگیری از replay)
$expected = hash_hmac('sha256', $m[1] . '.' . $body, $secret);
if (!hash_equals($expected, $m[2]) || abs(time() - (int)$m[1]) > 300) {
    http_response_code(401); exit; // امضا نامعتبر یا منقضی
}

روش قدیمی (بدون timestamp) هم همچنان روی هدر X-ArzPrice-Signature-Body ارسال می‌شود تا گیرنده‌های قبلی بدون تغییر کار کنند:

$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_ARZPRICE_SIGNATURE_BODY'] ?? '')) {
    http_response_code(401); exit; // امضا نامعتبر
}

نمونه رویداد alert_triggered:

{
  "event": "alert_triggered",
  "source": "arzprice",
  "hook_id": 1,
  "symbol": "BTC/IRT",
  "alert_id": 42,
  "condition": "above",
  "target_price": 7000000000,
  "target_price_fmt": "۷٬۰۰۰٬۰۰۰٬۰۰۰ ریال",
  "triggered_price": 7042000000,
  "triggered_price_fmt": "۷٬۰۴۲٬۰۰۰٬۰۰۰ ریال",
  "change_pct": 1.8,
  "instrument_url": "https://ibahoosham.ir/arzprice/p/crypto/btcirt",
  "sent_at": "2026-10-12T09:00:00Z"
}

⚖️ قواعد استفاده

• استفاده رایگان برای مصارف غیرتجاری با ذکر منبع «ارزپرایس» — برای تجاری با ما تماس بگیرید.
• محدودیت نرخ (جدید v4.5): GET حداکثر ۱۲۰ درخواست در دقیقه و درخواست‌های نوشتن حداکثر ۳۰ در دقیقه از هر IP — در صورت عبور، پاسخ 429 با هدر Retry-After می‌گیرید. پاسخ‌های قیمت از سمت ما ~۶۰ ثانیه کش می‌شوند، سمت خودتان هم کش کنید.
• داده‌ها «چنان‌که هست» ارائه می‌شوند؛ برای تصمیم‌های مالی به منابع رسمی هم مراجعه کنید.
• نسخه فعلی API: v4.39.0 — تغییرات ناسازگار با نسخه جدید اعلام می‌شوند.