وب‌سرویس نرخ ارز ایرانی‌ولت | API عمومی و رایگان نرخ لحظه‌ای

Q: برای استفاده باید کلید API بگیرم؟

نه. سرویس کاملاً باز است و هیچ کلید، توکن یا ثبتنامی لازم ندارد. شناسایی فقط بر اساس آیپی و صرفاً برای شمارش سهمیه انجام میشود.

Q: میتوانم فقط نرخ یک ارز را بگیرم؟

سرویس همیشه کل تابلو را برمیگرداند؛ حجمش چند کیلوبایت است و فیلتر کردن آن در سمت شما از یک درخواست جداگانه ارزانتر است. در نمونههای کد بالا دقیقاً همین کار انجام شده.

Q: نرخها هر چند وقت عوض میشوند؟

میز معاملات نرخها را در طول روز بهروز میکند و این سرویس حداکثر با ۱۰ دقیقه تأخیر آنها را منتشر میکند. زمان دقیق ثبت هر نرخ در updatedAt نوشته شده است.

Q: نسخهٔ v1 تا کی میماند؟

تا وقتی که باشد. اگر روزی ساختار پاسخ بهشکل ناسازگار عوض شود، زیر v2 منتشر میشود و v1 سر جای خودش میماند؛ افزودن فیلد جدید به همین نسخه، تغییر ناسازگار حساب نمیشود.

آدرس سرویس

یک آدرس، یک درخواست

این تنها آدرسی است که باید بشناسید. هیچ پارامتری نمی‌گیرد و هیچ هدر اجباری‌ای ندارد؛ کل تابلو را یک‌جا برمی‌گرداند و انتخاب ارز با شماست.

GET https://iraniwallet.com/api/v1/rates

باز کردن در مرورگر

آدرس قدیمی همچنان کار می‌کند

پیش از این نسخه، تابلو روی آدرس زیر منتشر می‌شد. دقیقاً همان پاسخ را می‌دهد و همان محدودیت‌ها را دارد، اما برای کد جدید آدرس نسخه‌دار بالا را استفاده کنید؛ تغییرهای ناسازگار آینده زیر ‎/api/v2‎ منتشر می‌شوند و ‎v1‎ سر جایش می‌ماند.

https://iraniwallet.com/api/rates.json

محیط تست

همین‌جا امتحانش کنید

دکمه را بزنید تا از همین صفحه یک درخواست واقعی به سرویس ارسال شود. آنچه می‌بینید دقیقاً همان چیزی است که برنامهٔ شما هم دریافت می‌کند — همان کد وضعیت، همان هدرها و همان بدنه.

GET https://iraniwallet.com/api/v1/rates

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

هنوز درخواستی نفرستاده‌اید. با زدن دکمه، پاسخ زنده همین‌جا نمایش داده می‌شود.

هر بار که این دکمه را بزنید، یکی از ۱۰ درخواست مجاز آن دقیقه مصرف می‌شود. اگر سهمیه تمام شود، پاسخ ۴۲۹ را همین‌جا خواهید دید — که خودش بخشی از تست است.

نمونهٔ خروجی

پاسخ واقعی همین لحظه

این نمونه دستی نوشته نشده؛ همان بدنه‌ای است که سرویس همین حالا برمی‌گرداند، فقط با فاصله‌گذاری خواناتر. پس هیچ‌وقت شکلی را نشان نمی‌دهد که سرویس دیگر پاسخ نمی‌دهد.

200 OK · application/json

{
    "base": "IRT",
    "note": "نرخ‌ها به تومان برای هر یک واحد ارز است. buy نرخی است که ایرانی ولت بابت ارز می‌پردازد و sell نرخی است که بابت ارز می‌گیرد.",
    "updatedAt": "2026-09-15T05:50:02+03:30",
    "source": "https://iraniwallet.com/",
    "documentation": "https://iraniwallet.com/api",
    "rates": [
        {
            "code": "USDT",
            "name": "تتر — TRC20 / ERC20",
            "buy": "226478",
            "sell": "227732",
            "url": "https://iraniwallet.com/exchange/USDT"
        },
        {
            "code": "USD",
            "name": "دلار آمریکا",
            "buy": "226709",
            "sell": "228425",
            "url": "https://iraniwallet.com/exchange/USD"
        },
        {
            "code": "CAD",
            "name": "دلار کانادا",
            "buy": "163559",
            "sell": "163657",
            "url": "https://iraniwallet.com/exchange/CAD"
        },
        {
            "code": "AUD",
            "name": "دلار استرالیا",
            "buy": "162525",
            "sell": "162623",
            "url": "https://iraniwallet.com/exchange/AUD"
        },
        {
            "code": "EUR",
            "name": "یورو",
            "buy": "264132",
            "sell": "262995",
            "url": "https://iraniwallet.com/exchange/EUR"
        },
        {
            "code": "TRY",
            "name": "لیر ترکیه",
            "buy": "4616",
            "sell": "4739",
            "url": "https://iraniwallet.com/exchange/TRY"
        },
        {
            "code": "AED",
            "name": "درهم امارات",
            "buy": "62950",
            "sell": "62950",
            "url": "https://iraniwallet.com/exchange/AED"
        },
        {
            "code": "CNY",
            "name": "یوان چین",
            "buy": "34006",
            "sell": "33933",
            "url": "https://iraniwallet.com/exchange/CNY"
        },
        {
            "code": "AMD",
            "name": "درام ارمنستان",
            "buy": "636",
            "sell": "626",
            "url": "https://iraniwallet.com/exchange/AMD"
        }
    ]
}

ساختار پاسخ

هر فیلد پاسخ یعنی چه

کلیدها انگلیسی و ثابت‌اند؛ هرچه خوانده می‌شود فارسی است. فیلدی حذف نمی‌شود و معنایش عوض نمی‌شود — اگر روزی چیزی اضافه شود، به انتهای همین ساختار اضافه می‌شود.

فیلد	نوع	توضیح
`base`	string	ارز مبنا. همیشه IRT؛ یعنی همهٔ نرخ‌ها به تومان ایران هستند. هر یک تومان برابر ده ریال است.
`note`	string	یک جملهٔ فارسی که معنی buy و sell را توضیح می‌دهد. برای نمایش به کاربر نهایی مناسب است.
`updatedAt`	string \| null	لحظه‌ای که صرافی آخرین نرخ را ثبت کرده، به قالب ISO 8601 و با اختلاف ساعت تهران. اگر null باشد یعنی تابلوی لحظه‌ای در دسترس نبوده و نباید به عددها به‌عنوان نرخ روز استناد کنید.
`source`	string	آدرس صفحه‌ای که همین نرخ‌ها روی آن نمایش داده می‌شوند.
`documentation`	string	آدرس همین صفحه؛ برای وقتی که پاسخ بدون مستنداتش به دست کسی می‌رسد.
`rates`	array	فهرست ارزها، به همان ترتیبی که روی تابلوی سایت چیده شده‌اند.

هر عضو آرایهٔ rates

فیلد	نوع	توضیح
`code`	string	کد ارز با حروف بزرگ: USD، EUR، TRY، AED، CNY، USDT و مانند اینها. برای تطبیق در کد، همین فیلد را مبنا بگیرید نه ترتیب آرایه را.
`name`	string	نام فارسی ارز، همان‌طور که روی سایت نوشته می‌شود.
`buy`	string	نرخی که ایرانی‌ولت بابت خرید این ارز از شما می‌پردازد — به تومان، برای یک واحد.
`sell`	string	نرخی که ایرانی‌ولت بابت فروش این ارز به شما می‌گیرد — به تومان، برای یک واحد.
`url`	string	اختیاری. اگر برای این ارز صفحهٔ اختصاصی نوشته شده باشد، آدرسش اینجاست.

دربارهٔ عددها

buy و sell رشته‌اند، نه عدد. با ارقام لاتین و نقطهٔ اعشار نوشته می‌شوند تا در هیچ زبانی دقتشان از دست نرود؛ پیش از محاسبه آن‌ها را به عدد تبدیل کنید.
«خرید» و «فروش» از سمت صرافی خوانده می‌شوند: buy یعنی ما می‌خریم و شما می‌فروشید، sell یعنی ما می‌فروشیم و شما می‌خرید.
همیشه sell از buy بزرگ‌تر یا مساوی است؛ فاصلهٔ این دو، اسپرد میز معاملات است.

نمونهٔ کد

در زبان خودتان

چهار نمونهٔ آماده که می‌توانید مستقیم بردارید. هر چهار تا یک کار می‌کنند: تابلو را می‌گیرند و یک ارز را از آن بیرون می‌کشند.

cURL

# کل تابلو
curl -s 'https://iraniwallet.com/api/v1/rates'

# همراه با هدرها، تا سهمیهٔ باقی‌مانده را ببینید
curl -si 'https://iraniwallet.com/api/v1/rates' | head -n 20

JavaScript

const response = await fetch('https://iraniwallet.com/api/v1/rates');

if (429 === response.status) {
  const wait = Number(response.headers.get('Retry-After') || 60);
  throw new Error(`سهمیه تمام شد؛ ${wait} ثانیه دیگر دوباره تلاش کنید.`);
}

const board = await response.json();
const usd = board.rates.find((rate) => 'USD' === rate.code);

console.log(`دلار: خرید ${usd.buy} / فروش ${usd.sell} تومان`);
console.log(`آخرین به‌روزرسانی: ${board.updatedAt}`);

PHP

$context = stream_context_create([
    'http' => ['timeout' => 5, 'header' => "Accept: application/json\r\n"],
]);

$board = json_decode(file_get_contents('https://iraniwallet.com/api/v1/rates', false, $context), true);

foreach ($board['rates'] as $rate) {
    printf("%-5s خرید %12s   فروش %12s\n", $rate['code'], $rate['buy'], $rate['sell']);
}

Python

import requests

response = requests.get('https://iraniwallet.com/api/v1/rates', timeout=5)
response.raise_for_status()

board = response.json()
usd = next(rate for rate in board['rates'] if rate['code'] == 'USD')

print(f"دلار: خرید {usd['buy']} / فروش {usd['sell']} تومان")
print('سهمیهٔ باقی‌مانده:', response.headers.get('X-RateLimit-Remaining'))

محدودیت‌ها

چه چیزهایی را باید در نظر بگیرید

سرویس رایگان است، اما بی‌قید نیست. سه محدودیت زیر همهٔ چیزی است که باید بدانید.

۱۰ درخواست در هر دقیقه، برای هر آی‌پی

شمارش روی دقیقهٔ ساعت انجام می‌شود، نه از لحظهٔ اولین درخواست شما. با شروع دقیقهٔ بعد سهمیه از نو ۱۰ می‌شود. درخواست یازدهم با کد ۴۲۹ رد می‌شود و در هدر Retry-After نوشته شده که چند ثانیه دیگر می‌توانید دوباره تلاش کنید.

داده هر ۱۰ دقیقه ساخته می‌شود

پاسخ از یک فایل آماده خوانده می‌شود که حداکثر هر ۱۰ دقیقه یک‌بار بازسازی می‌شود. یعنی درخواست پشت‌سرهم، دادهٔ تازه‌تری به شما نمی‌دهد؛ همان بدنه را می‌گیرید. برای همین بیش از هر چند دقیقه یک بار صدا زدن سرویس فایده‌ای ندارد.

تاریخ نرخ را جدی بگیرید

هر پاسخ فیلد updatedAt را دارد: لحظه‌ای که میز معاملات آن نرخ را ثبت کرده. اگر این فیلد null بود یا مربوط به ساعت‌ها قبل بود، نرخ را به‌عنوان قیمت لحظه‌ای به کاربرتان نشان ندهید.

هدرهایی که با هر پاسخ می‌آیند

`X-RateLimit-Limit`	سقف درخواست در هر دقیقه — همیشه ۱۰.
`X-RateLimit-Remaining`	چند درخواست از سهمیهٔ این دقیقه باقی مانده است.
`X-RateLimit-Reset`	چند ثانیه تا شروع دقیقهٔ بعد و صفر شدن شمارش باقی است.
`Retry-After`	فقط روی پاسخ ۴۲۹؛ چند ثانیه باید صبر کنید.
`Age`	چند ثانیه از ساخته شدن این نسخه از تابلو گذشته است.
`Cache-Control`	تا کی می‌توانید همین پاسخ را بدون درخواست دوباره استفاده کنید.

کدهای وضعیت

پاسخ‌هایی که ممکن است بگیرید

کد	معنی	چه کنید
200	موفق	بدنه، تابلوی نرخ‌هاست. کد شما فقط باید به همین حالت خوش‌بین باشد.
429	سهمیه تمام شد	به اندازهٔ عدد Retry-After صبر کنید و دوباره تلاش کنید. تلاش پیاپی و بی‌فاصله فقط پاسخ ۴۲۹ بیشتری می‌گیرد.
404	آدرس اشتباه	آدرس را با آنچه بالای همین صفحه نوشته شده مقایسه کنید؛ معمولاً یک اسلش یا نسخه جا افتاده است.
405	روش اشتباه	این سرویس فقط GET می‌پذیرد. POST و بقیه رد می‌شوند.
5xx	خطای سمت ما	چند ثانیه بعد دوباره تلاش کنید. آخرین پاسخ موفقی را که گرفته‌اید نگه دارید تا در این فاصله صفحه‌تان خالی نماند.

نمونهٔ پاسخ ۴۲۹

429 Too Many Requests · application/json

{
  "error": "rate_limit_exceeded",
  "message": "در هر دقیقه حداکثر ۱۰ درخواست از هر آی‌پی پذیرفته می‌شود. ۳۷ ثانیه دیگر دوباره تلاش کنید.",
  "limit": 10,
  "window": 60,
  "retryAfter": 37,
  "documentation": "https://iraniwallet.com/api"
}

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

شرط‌های ما ساده است

نرخ را با تاریخش نقل کنید

هر جا نرخ ما را نشان می‌دهید، updatedAt را هم کنارش بیاورید. نرخی که تاریخ ندارد، نرخ نیست.
به ما ارجاع بدهید

یک لینک به iraniwallet.com کنار عددها کافی است. این تنها چیزی است که بابت این سرویس از شما می‌خواهیم.
پاسخ را نزد خودتان کش کنید

داده هر ۱۰ دقیقه عوض می‌شود؛ اگر چند کاربر دارید، یک بار بگیرید و بین همه پخش کنید، نه اینکه هر کاربر یک درخواست بزند.
سقف را دور نزنید

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

نرخ نهایی هر معامله در پنل کاربری و در لحظهٔ ثبت سفارش تعیین می‌شود. نرخ این سرویس برای نمایش و اطلاع است و ایرانی‌ولت مسئول تصمیم‌هایی که بر مبنای آن گرفته می‌شود نیست.

پرسش‌های متداول

چیزهایی که معمولاً پرسیده می‌شود

برای استفاده باید کلید API بگیرم؟

نه. سرویس کاملاً باز است و هیچ کلید، توکن یا ثبت‌نامی لازم ندارد. شناسایی فقط بر اساس آی‌پی و صرفاً برای شمارش سهمیه انجام می‌شود.

می‌توانم فقط نرخ یک ارز را بگیرم؟

سرویس همیشه کل تابلو را برمی‌گرداند؛ حجمش چند کیلوبایت است و فیلتر کردن آن در سمت شما از یک درخواست جداگانه ارزان‌تر است. در نمونه‌های کد بالا دقیقاً همین کار انجام شده.

سقف را می‌شود بیشتر کرد؟

اگر کاربرد شما واقعاً به بیشتر از این نیاز دارد، از صفحهٔ تماس با ما بنویسید و بگویید چه می‌سازید. برای موارد منطقی راه باز است.

نرخ‌ها هر چند وقت عوض می‌شوند؟

میز معاملات نرخ‌ها را در طول روز به‌روز می‌کند و این سرویس حداکثر با ۱۰ دقیقه تأخیر آن‌ها را منتشر می‌کند. زمان دقیق ثبت هر نرخ در updatedAt نوشته شده است.

آیا از مرورگر هم می‌شود صدایش زد؟

بله. پاسخ هدر Access-Control-Allow-Origin با مقدار * دارد، پس fetch از هر دامنه‌ای کار می‌کند. هدرهای سهمیه هم برای جاوااسکریپت قابل خواندن‌اند.

نسخهٔ v1 تا کی می‌ماند؟

تا وقتی که باشد. اگر روزی ساختار پاسخ به‌شکل ناسازگار عوض شود، زیر v2 منتشر می‌شود و v1 سر جای خودش می‌ماند؛ افزودن فیلد جدید به همین نسخه، تغییر ناسازگار حساب نمی‌شود.