₮
مستندات نرخ ارز API Documentation
بازگشت به سایت ←
راهنمای استفاده

مستندات جامع وب‌سرویس Exchange Rate API

این وب‌سرویس یک API معمارانه‌شده بر پایه REST است که داده‌های لحظه‌ای نرخ ارز، طلا و سکه را بازمی‌گرداند. کلیه درخواست‌ها از طریق پروتکل HTTPS و با خروجی فرمت JSON ارسال و دریافت می‌شوند.

📍 آدرس پایه (Base URL)

https://helloapi.ir/v1

🔐 احراز هویت (Authentication)

جهت دسترسی به سرویس‌ها، کلید اختصاصی خود را در هدر درخواست با کلید Authorization قرار دهید.

cURL Example 
curl -X GET "https://helloapi.ir/v1/latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

🛣️ لیست Endpointها

GET /v1/latest
دریافت لیست تمام نرخ‌های به روز شده شامل دلار، یورو، طلا و سکه.
GET /v1/currency/{symbol}
دریافت آخرین اطلاعات یک ارز خاص با نماد مشخص (مانند USD یا EUR).
GET /v1/history
تاریخچه نرخ یک ارز. پارامترها: symbol (ضروری)، from، to، source، per_page (پیش‌فرض ۵۰، سقف ۵۰۰).
GET /v1/convert
تبدیل ارز. پارامترها: from، to، amount.
GET /v1/sources
وضعیت منابع داده: تازه (fresh) یا قدیمی (stale) بر اساس fresh_hours.
GET /v1/plan
وضعیت پلن و مصرف. شامل plan، monthly_quota، daily_quota، rate_limit_per_minute، usage، websocket_enabled.

📦 ساختار پاسخ (JSON)

نمونه خروجی استاندارد وب سرویس:

{
  "success": true,
  "timestamp": "2026-09-27T10:30:00Z",
  "base": "IRT",
  "data": [
    {
      "symbol": "USD",
      "name": "دلار آمریکا",
      "price": 92500,
      "change": 0.32
    }
  ]
}

⏱️ محدودیت‌ها (Rate Limits)

هر درخواست با سه پنجره محدود می‌شود: دقیقه، روز، ماه. اگر در یک پنجره محدودیت exceeded باشد، ۴۲۹ برمی‌گردد.

دقیقه
طبق پلن
روز
طبق پلن
ماه
طبق پلن

هدر Retry-After در خطای ۴۲۹ زمان انتظار را نشان می‌دهد.

📄 صفحه‌بندی

فقط /v1/history صفحه‌بندی دارد. پیش‌فرض ۵۰، سقف ۵۰۰. پاسخ شامل meta با current_page، last_page، per_page، total.

🔢 دقت (Precision)

  • price: ۰ رقم اعشار
  • change: ۲ رقم
  • rate: ۱۰ رقم
  • amount: ۲ رقم

📡 WebSocket

در برخی پلن‌ها (طبق پاسخ /v1/plan) websocket_enabled فعال است. برای اتصال لحظه‌ای نرخ‌ها از WebSocket استفاده کنید.

❌ کدهای خطا