پرش به محتوای اصلی
یک شروع رایگان برای شما

۳ روز رایگان،
پنل تحلیلگر را تجربه کنید

ثبت‌نام کنید و با تأیید شماره موبایل، دسترسی آزمایشی سه‌روزه‌تان را فعال کنید.

✓ بدون نیاز به پرداخت✓ فعال‌سازی پس از تأیید موبایل
شروع رایگان ۳ روزه

ویژه کاربران جدید · یک دوره برای هر حساب

API داده بازار khapi؛ دریافت قیمت تتر، طلا و دلار در پروژه شما

راهنمای استفاده از API داده بازار khapi برای دریافت و پردازش قیمت تتر، دلار و طلا؛ همراه با نمونه‌های عملی curl، Python و Next.js برای ساخت داشبورد، هشدار قیمت و ابزارهای تحلیلی.

تیم khapi · ۹ مرداد ۱۴۰۵ · ۵ دقیقه مطالعه
API داده بازار khapi؛ دریافت قیمت تتر، طلا و دلار در پروژه شما

دادهٔ بازار khapi چیست؟

khapi endpoint دادهٔ بازار را برای دریافت نرخ‌های لحظه‌ای مانند ارز، طلا و شاخص‌ها فراهم می‌کند. برخلاف API خبر، این endpoint بدون احراز هویت در دسترس است.

تنها endpoint معتبر:

curl -X GET "https://khapi.ir/api/market-prices"

ساختار پاسخ

پاسخ شامل وضعیت کلی و دیکشنری `prices` است:

{
  "available": true,
  "stale": true,
  "news_count_24h": 5970,
  "stale_after_seconds": 120,
  "max_age_seconds": 21600,
  "service": {
    "active": "active",
    "failed": "active"
  },
  "prices": {
    "usd_free": {
      "label": "دلار آزاد",
      "value": 98200.0,
      "unit": "تومان",
      "updated_at": "2026-07-31T22:47:19",
      "age_seconds": 51,
      "stale": false,
      "too_old": false,
      "provider": "TGJU USD/IRR",
      "change_24h_percent": 0.2,
      "change_24h_value": 200.0
    }
  }
}

فیلدهای هر قیمت عبارت‌اند از: `label`، `value` (مقدار عددی)، `unit`، `updated_at`، `age_seconds`، `stale`، `too_old`، `provider` و `change_24h_percent`.

نکتهٔ مهم دربارهٔ فیلد `stale`

فیلد `stale` در سطح کلی پاسخ ممکن است `true` باشد حتی اگر برخی قیمت‌ها تازه باشند. دلیل آن می‌تواند قدیمی‌بودن بخشی از داده‌ها، مانند شاخص‌های بورس در ساعات غیرمعاملاتی، باشد. بنابراین مصرف‌کننده نباید کل پاسخ را تازه فرض کند و باید وضعیت `stale` را برای هر نماد جداگانه بررسی کند.

دریافت قیمت با Python

نمونهٔ کامل برای خواندن `usd_free` و اعتبارسنجی تازگی:

import requests

response = requests.get("https://khapi.ir/api/market-prices", timeout=20)
response.raise_for_status()
data = response.json()

if not data.get("available"):
    raise RuntimeError("دادهٔ بازار در دسترس نیست")

usd = data["prices"].get("usd_free")
if usd is None:
    raise KeyError("نماد usd_free یافت نشد")

# بررسی تازگی پیش از مصرف
if usd.get("stale") or usd.get("too_old"):
    print("هشدار: قیمت usd_free ممکن است قدیمی باشد")
else:
    print(f"{usd['label']}: {usd['value']:,} {usd['unit']}")
    print(f"به‌روزرسانی: {usd['updated_at']} (سن: {usd['age_seconds']} ثانیه)")
    print(f"تغییر ۲۴ ساعته: {usd['change_24h_percent']}%")

همیشه پیش از نمایش یا ذخیرهٔ هر نماد، فیلدهای `stale` و `too_old` آن نماد را بررسی کنید.

کاربردها

  • نمایش قیمت لحظه‌ای در داشبورد یا اپلیکیشن
  • ساخت هشدار عبور قیمت از آستانه (در سرویس خودتان)
  • ذخیرهٔ تاریخچه برای تحلیل روند
  • ترکیب با دادهٔ خبر برای تحلیل زمینه

خطاهای رایج

  • فرض اینکه کل پاسخ تازه است به‌خاطر `stale: false` کلی (اشتباه است)
  • مقایسهٔ قیمت‌های ناهم‌واحد (ریال، تومان، دلار)
  • نادیده‌گرفتن `age_seconds` هنگام تصمیم‌گیری

لینک‌های داخلی

جمع‌بندی

Endpoint `/api/market-prices` تنها منبع معتبر دادهٔ بازار در khapi است. همیشه تازگی را در سطح هر نماد بررسی کنید و قیمت‌های `stale` یا `too_old` را پیش از مصرف رد یا علامت‌گذاری کنید.

اشتراک‌گذاری:

این مطلب چطور به کار شما بیاید؟

مفاهیم این مقاله را مستقیم در پنل khapi امتحان کنید:

آماده شروع هستید؟

۳ روز استفادهٔ رایگان از پنل تحلیلگر، مطابق محدودیت‌های دورهٔ آزمایشی و بدون نیاز به کارت بانکی.