مستندات API

راهنمای API ارزهام

همه چیز برای یکپارچه‌سازی نرخ ارز، طلا و سکه بازار ایران در اپلیکیشن شما. RESTful، JSON و قیمت‌ها به تومان.

دریافت کلید APIمدیریت کلیدها

معرفی

API ارزهام داده‌های نرخ ارز، طلا و سکه بازار ایران را از طریق REST API در اختیار توسعه‌دهندگان قرار می‌دهد.

تمام پاسخ‌ها JSON هستند و قیمت‌ها مستقیماً به تومان برگردانده می‌شوند. برای دسترسی به اندپوینت‌های نرخ، کافی است کلید API را در هدر درخواست ارسال کنید.

Base URL

https://api.arzham.app

فرمت

JSON

پروتکل

HTTPS

واحد قیمت

تومان

شروع سریع

در سه مرحله اولین درخواست خود را ارسال کنید.

  1. ۱

    ثبت‌نام و ساخت کلید

    در داشبورد ثبت‌نام کنید و از بخش کلیدهای API یک کلید بسازید.

  2. ۲

    ذخیره کلید

    کلید را در متغیر محیطی ARZHAM_API_KEY یا secret manager ذخیره کنید. هرگز در کد سمت کلاینت قرار ندهید.

  3. ۳

    ارسال درخواست

    کلید را در هدر X-App-Key ارسال کنید و پاسخ JSON را پردازش کنید.

اولین درخواست

curl -H "X-App-Key: YOUR_APP_KEY" \
  "https://api.arzham.app/api/rates/latest"

احراز هویت

اندپوینت‌های نرخ نیاز به کلید API دارند. اندپوینت سلامت عمومی است و کلید نمی‌خواهد.

روش پیشنهادی: هدر X-App-Key

X-App-Key: arz_live_xxxxxxxxxxxxxxxx

روش جایگزین: Bearer Token

Authorization: Bearer arz_live_xxxxxxxxxxxxxxxx

نکته امنیتی

کلید API را فقط در سرور یا backend نگه دارید. در اپلیکیشن موبایل یا JavaScript سمت مرورگر قرار ندهید.

اندپوینت‌ها

سه اندپوینت اصلی برای دریافت نرخ، تاریخچه و وضعیت سرویس.

GET/api/rates/latest

نرخ‌های لحظه‌ای

تمام دارایی‌های پشتیبانی‌شده را با قیمت فعلی، تغییر ۲۴ ساعته و جهت بازار برمی‌گرداند. پرکاربردترین اندپوینت برای نمایش نرخ در اپلیکیشن.

URL کامل

https://api.arzham.app/api/rates/latest

پارامترها

ناممحلنوعالزامیتوضیح
X-App-Keyheaderstringبلهکلید API ساخته‌شده از داشبورد

نمونه درخواست

curl -H "X-App-Key: YOUR_APP_KEY" \
  "https://api.arzham.app/api/rates/latest"

نمونه پاسخ

{
  "rates": [
    {
      "assetId": "usd",
      "price": 166800,
      "changePercent24h": 1.21,
      "direction": "up",
      "updatedAt": "2026-06-25T11:24:55.000Z"
    },
    {
      "assetId": "gold_18",
      "price": 16025670,
      "changePercent24h": 2.12,
      "direction": "up",
      "updatedAt": "2026-06-25T12:30:13.000Z"
    }
  ],
  "meta": {
    "currency": "toman",
    "assetCount": 25,
    "cacheAgeMs": 120000,
    "source": "live"
  }
}

فیلدهای پاسخ

ratesRate[]

آرایه نرخ تمام دارایی‌ها

meta.currencystring

همیشه toman

meta.assetCountnumber

تعداد دارایی‌های برگردانده‌شده

meta.cacheAgeMsnumber

قدمت کَش به میلی‌ثانیه

meta.sourcestring

live یا stale در صورت استفاده از کَش قدیمی

GET/api/rates/history/:assetId

تاریخچه قیمت

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

URL کامل

https://api.arzham.app/api/rates/history/:assetId

پارامترها

ناممحلنوعالزامیتوضیح
X-App-Keyheaderstringبلهکلید API
assetIdpathstringبلهشناسه دارایی، مثلاً usd یا gold_18
rangequerystringبلهیکی از 24h، 7d، 30d یا 90d

نمونه درخواست

curl -H "X-App-Key: YOUR_APP_KEY" \
  "https://api.arzham.app/api/rates/history/usd?range=7d"

نمونه پاسخ

{
  "assetId": "usd",
  "range": "7d",
  "points": [
    { "timestamp": "2026-06-18T12:00:00.000Z", "price": 164200 },
    { "timestamp": "2026-06-19T12:00:00.000Z", "price": 165100 },
    { "timestamp": "2026-06-25T11:24:55.000Z", "price": 166800 }
  ],
  "meta": {
    "currency": "toman",
    "pointCount": 168
  }
}

فیلدهای پاسخ

assetIdstring

شناسه دارایی درخواستی

rangestring

بازه درخواست‌شده

pointsHistoryPoint[]

نقاط قیمت در بازه

points[].timestampstring

زمان ISO 8601

points[].pricenumber

قیمت به تومان

meta.currencystring

همیشه toman

GET/api/health

سلامت سرویس

وضعیت API و اتصال به منبع داده را بررسی می‌کند. نیازی به کلید API ندارد و برای مانیتورینگ uptime مناسب است.

URL کامل

https://api.arzham.app/api/health

نمونه درخواست

curl "https://api.arzham.app/api/health"

نمونه پاسخ

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 86400,
  "source": "connected"
}

فیلدهای پاسخ

statusstring

ok در حالت سالم

versionstring

نسخه API

uptimenumber

مدت فعالیت سرور به ثانیه

sourcestring

وضعیت اتصال به منبع داده

فیلدهای پاسخ

ساختار مشترک هر آیتم در آرایه rates.

فیلدنوعتوضیح
assetIdstringشناسه یکتا دارایی. در URL تاریخچه استفاده می‌شود.
pricenumberقیمت به تومان. نیازی به تبدیل ریال نیست.
changePercent24hnumberدرصد تغییر قیمت نسبت به ۲۴ ساعت قبل.
direction"up" | "down" | "flat"جهت تغییر. اگر تغییر کمتر از ۰.۰۵٪ باشد، flat است.
updatedAtstringزمان آخرین به‌روزرسانی قیمت (ISO 8601).

دارایی‌های پشتیبانی‌شده

25 دارایی شامل ارزهای رایج، طلا، سکه و آبشده.

assetIdنام فارسی
usdدلار آمریکا
usd_buyدلار خرید
usd_farda_sellدلار فردا
usd_haratدلار هرات
eurیورو
gbpپوند
aedدرهم امارات
tryلیر ترکیه
sarریال عربستان
iqdدینار عراق
kwdدینار کویت
cadدلار کانادا
audدلار استرالیا
cnyیوان چین
chfفرانک سوئیس
rubروبل روسیه
jpyین ژاپن
coin_emamiسکه امامی
coin_baharسکه بهار آزادی
coin_nimنیم سکه
coin_robربع سکه
coin_geramiسکه گرمی
gold_18طلای ۱۸ عیار
abshodehآبشده
gold_xauانس طلا (XAU)

محدودیت درخواست

سقف درخواست بر اساس پلن شما اعمال می‌شود. در صورت عبور از سقف، خطای 429 دریافت می‌کنید.

پلندر دقیقهدر ساعتدر روزدر ماهتاریخچهبه‌روزرسانی
رایگان———50نداردهر ۲ ساعت
استارتر205003000—۷ روزلحظه‌ای
حرفه‌ای60200015000—۳۰ روزلحظه‌ای
کسب‌وکار30010000100000—۹۰ روزلحظه‌ای

هدر Retry-After در پاسخ 429 زمان انتظار تا درخواست بعدی را نشان می‌دهد.

خطاها

تمام خطاها با ساختار یکسان و کد HTTP مناسب برگردانده می‌شوند.

401unauthorizedکلید نامعتبر

هدر X-App-Key ارسال نشده یا کلید revoke شده است.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
403forbiddenدسترسی محدود

پلن شما به این بازه تاریخچه یا قابلیت دسترسی ندارد.

{
  "error": {
    "code": "forbidden",
    "message": "History range 30d requires Pro plan or higher"
  }
}
404not_foundدارایی یافت نشد

assetId در مسیر تاریخچه معتبر نیست.

{
  "error": {
    "code": "not_found",
    "message": "Unknown asset: xyz"
  }
}
429rate_limitedمحدودیت درخواست

سقف دقیقه‌ای، ساعتی یا روزانه پلن شما پر شده است.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "retryAfter": 42
  }
}
503source_unavailableمنبع در دسترس نیست

منبع داده قطع است و کَش معتبری برای پاسخ وجود ندارد.

{
  "error": {
    "code": "source_unavailable",
    "message": "Data source unavailable and no stale cache"
  }
}

سوالات متداول