نمونه‌کد وب‌سرویس نرخ ارز (API نرخ ارز) نِت اَرز

نرخ دلار، یورو، درهم، لیر و ارزهای دیگر به تومان، برای سایت، اپ، ربات و صفحه‌گسترده.

Iranian Toman exchange rate API examples: USD, EUR, AED, TRY and more in PHP, JavaScript, React, Python, Go, C#/.NET, Laravel, WordPress, a Telegram bot, Google Sheets and Excel.

معرفی سرویس · مستندات · تابلوی نرخ ارز · ساخت کلید · English

این مخزن نمونه‌کدهای آماده برای API نرخ ارز نِت اَرز (وب سرویس نرخ ارز) را دارد. نرخ‌ها همان اعداد تابلوی نرخ ارز هستند: خرید، فروش و میانگین بازار هر ارز، به‌علاوهٔ مبدل ارز به تومان، تومان به ارز و ارز به ارز. طرح رایگان فقط عضویت می‌خواهد.

• نشانی پایه: https://netarz.ir/api/fx/v1
• کلید: Authorization: Bearer fx-ntz-v1-… (یا هدر X-API-Key)
• مستندات: netarz.ir/docs/fx · مرجع تعاملی: netarz.ir/docs/fx/reference

فهرست

• شروع در دو دقیقه
• راه‌اندازی در سه قدم
• فهرست نمونه‌ها
• React: از سرور خودتان یا از مرورگر
• ربات تلگرام
• مبدل تومان با یک درخواست
• داده‌ای که می‌گیرید
• رایگان و پرو
• مصرف را پایین نگه دارید
• خطاهای رایج
• بررسی خودکار کد و تغییرات
• مخزن‌های دیگر نِت اَرز
• مشارکت و پشتیبانی
• English

شروع در دو دقیقه

۱. کلید بسازید. در پنل API نرخ ارز یک «اپ» با دامنهٔ خودتان بسازید و کلید fx-ntz-v1-… را کپی کنید. برای آزمایش روی رایانهٔ خودتان، دامنهٔ localhost خودکار تأیید می‌شود.

۲. اولین درخواست را بفرستید. اگر از سرور می‌فرستید، IP خروجی همان سرور باید در «IPهای مجاز» اپ باشد:

export NETARZ_FX_KEY="fx-ntz-v1-..."
curl -4 "https://netarz.ir/api/fx/v1/rates?codes=USD,EUR,AED" \
  -H "Authorization: Bearer $NETARZ_FX_KEY"

۳. یکی از نمونه‌ها را اجرا کنید:

git clone https://github.com/netarz/fx-api-examples.git
cd fx-api-examples
./curl/rates.sh                      # cURL
php php/rates.php                    # PHP خالص، با کش فایل
node javascript/node/rates.mjs       # Node.js 18+، بدون وابستگی
python3 python/netarz_fx.py          # Python (pip install requests)
(cd go && go run .)                  # Go، فقط کتابخانهٔ استاندارد
dotnet run --project dotnet          # C# و .NET 8
node converter/toman-converter.mjs 250 USD   # مبدل تومان

فقط می‌خواهید نرخ را در سایتتان نشان بدهید و کد نمی‌نویسید؟ ویجت نرخ ارز با یک تگ <script> کار می‌کند، و برای وردپرس افزونهٔ آماده داریم.

راه‌اندازی در سه قدم

1. در نِت اَرز ثبت‌نام کنید و از پنل /fx یک «اپ» بسازید: یک نام و دامنه‌ای که از آن درخواست می‌فرستید. کلید fx-ntz-v1-… را فقط همان یک بار می‌بینید.
2. مالکیت دامنه را تأیید کنید: رکورد TXT روی _netarz.<دامنه>، یا فایل /.well-known/netarz-fx-verify.txt. فایل آماده را از صفحهٔ اپ دانلود کنید و بدون ویرایش آپلود کنید؛ تایپ دستی کد شایع‌ترین علت تأیید نشدن است. برای تست محلی، localhost خودکار تأیید می‌شود.
3. اگر از سرور درخواست می‌فرستید، IP خروجی سرور را در «IPهای مجاز» اپ بگذارید. درخواست مرورگر با دامنه سنجیده می‌شود و درخواست سرور با IP.

اگر سرور شما IP ثابت ندارد (هاست اشتراکی، Cloudflare Workers، Vercel، Google Sheets) یا با وجود ثبت IP خطای ip_not_allowed می‌گیرید، راهنمای قفل دامنه و IP را بخوانید؛ دام IPv6 هم همان‌جاست.

فهرست نمونه‌ها

پوشه / فایل	کاربرد	راهنمای مربوط
curl/rates.sh	نرخ، یک ارز، مبدل، فهرست ارزها، وضعیت کلید و سهمیه	نرخ‌ها · مبدل
curl/pro-history.sh	تاریخچه، آرشیو روزانه (تاریخ شمسی هم پذیرفته می‌شود)، کندل، آمار و استریم؛ طرح پرو	تاریخچه
javascript/browser/	جدول نرخ در صفحهٔ سایت، مستقیم از مرورگر، با کش کوتاه	قفل دامنه
javascript/node/rates.mjs	Node.js بدون وابستگی، با کش	SDKها
python/netarz_fx.py	کلاینت پایتون با کش و پیام خطای روشن	SDKها
packages/python/	بستهٔ پایتون netarz-fx برای pip: بدون وابستگی، با کش و تست	SDKها
packages/js/	بستهٔ netarz-fx برای npm: Node.js، مرورگر، Deno و Bun، با تایپ‌های TypeScript	SDKها
php/rates.php	PHP خالص برای هاست اشتراکی، با کش فایل و آخرین مقدار سالم	نرخ‌ها
laravel/app/Services/NetArzFx.php	سرویس لاراول با Cache::remember و نسخهٔ پشتیبان	SDKها
wordpress/netarz-fx-snippet.php	کد کوتاه [netarz_usd] برای functions.php	افزونهٔ کامل وردپرس
google-sheets/Code.gs	تابع =NETARZ_RATE("USD") در Google Sheets	نرخ دلار در اکسل و گوگل شیت
excel-power-query/netarz-rates.pq	نرخ در Excel و Power BI با Power Query	نرخ دلار در اکسل و گوگل شیت
relay/fx-relay.php	رله روی یک سرور با IP ثابت، برای جاهایی که IP ثابت ندارند؛ JSON یا CSV	راهنمای قفل IP
go/	Go با net/http و بدون وابستگی، با کش و پیام خطای روشن	نرخ‌ها
dotnet/	C# و .NET 8 با HttpClient، بدون بستهٔ NuGet	نرخ‌ها
react/	هوک useNetArzRates و جدول نرخ برای React؛ از سرور خودتان یا مستقیم از مرورگر	قفل دامنه
telegram-bot/	ربات تلگرام با دستورهای /usd، /rates و /convert	نرخ‌ها
converter/toman-converter.mjs	تبدیل تومان به دلار، یورو و درهم و برعکس، با یک درخواست	مبدل

React: از سرور خودتان یا از مرورگر

هوک useNetArzRates نرخ‌ها را از یکی از این دو راه می‌گیرد:

• از سرور خودتان (پیشنهاد ما، اگر سرور دارید): endpoint را نشانی‌ای روی سایت خودتان بدهید که سمت سرور /rates را با کلید می‌خواند و همان JSON را برمی‌گرداند (نمونه‌های laravel/ و php/). کلید به مرورگر نمی‌رسد و یک کش سمت سرور برای همهٔ بازدیدکننده‌ها کافی است.
• مستقیم از مرورگر: apiKey را بدهید. کلید در کد صفحه دیده می‌شود، ولی چون به دامنهٔ شما قفل است از سایت دیگری کار نمی‌کند (قفل دامنه). دامنهٔ صفحه باید روی اپ باشد.

import RatesTable from "./RatesTable.jsx";

<RatesTable codes={["USD", "EUR", "AED"]} endpoint="/api/fx-rates" />

هوک نرخ‌ها را در حافظه و sessionStorage نگه می‌دارد و زودتر از یک دقیقه دوباره درخواست نمی‌فرستد. اگر درخواستی خطا بدهد، آخرین نرخ سالم روی صفحه می‌ماند.

ربات تلگرام

telegram-bot/bot.py به /usd، /eur، /rates و /convert 100 usd جواب می‌دهد. فقط کتابخانهٔ requests لازم دارد و با long polling کار می‌کند، پس دامنه و وبهوک نمی‌خواهد:

pip install -r telegram-bot/requirements.txt
export TELEGRAM_BOT_TOKEN="..."   # از @BotFather
export NETARZ_FX_KEY="fx-ntz-v1-..."
python3 telegram-bot/bot.py

ربات همهٔ نرخ‌ها را با یک درخواست می‌گیرد و دو دقیقه نگه می‌دارد؛ یعنی حتی در یک گروه شلوغ هر دو دقیقه حداکثر یک درخواست از سهمیهٔ شما کم می‌شود. IP سروری که ربات روی آن اجرا می‌شود باید در «IPهای مجاز» اپ باشد.

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

برای یک تبدیل، GET /convert ساده‌ترین راه است. ولی صفحه‌ای که ده‌ها قیمت را تبدیل می‌کند (فهرست قیمت، سبد خرید، ماشین‌حساب) بهتر است یک بار /rates را بگیرد و حساب را خودش انجام بدهد. converter/toman-converter.mjs همین کار را می‌کند، با همان قاعدهٔ mid، buy و sell که /convert دارد، و قیمت را بر unit تقسیم می‌کند:

node converter/toman-converter.mjs 250 USD            # ۲۵۰ دلار به تومان
node converter/toman-converter.mjs 10000000 IRT EUR   # ۱۰ میلیون تومان به یورو

داده‌ای که می‌گیرید

• buy، sell و mid به تومان و برای unit واحد از آن ارز است. بیشتر ارزها unit: 1 دارند؛ برای ارزی مثل دینار عراق قیمت برای ۱۰۰ واحد است. قیمت یک واحد = مقدار ÷ unit.
• buy و sell از دید صرافی است (buy یعنی صرافی می‌خرد). نرخ‌ها اطلاع‌رسانی‌اند؛ برای تصمیم مالی منبع خودتان را هم داشته باشید.
• meta.as_of زمان واقعی نرخ است و meta.delayed_minutes تأخیر طرح شما.
• هدرهای X-FX-Plan، X-Quota-Limit، X-Quota-Remaining و X-Quota-Reset وضعیت سهمیه را می‌گویند.

رایگان و پرو

طرح رایگان فقط عضویت می‌خواهد: نرخ همهٔ ارزها با تأخیر، مبدل، فهرست ارزها و ویجت. طرح پرو را برای هر اپ جدا می‌خرید و نرخ زنده، تاریخچه و آرشیو روزانه، کندل، آمار، هشدار قیمت با وبهوک و استریم زنده دارد. در زمان نوشتن این راهنما طرح رایگان ۱۵ دقیقه تأخیر، ۶۰ درخواست در دقیقه و ۳٬۰۰۰ درخواست در روز دارد و طرح پرو ۵ دلار در ماه برای هر اپ است. این اعداد ممکن است تغییر کنند؛ مرجع، صفحهٔ طرح‌ها است.

مصرف را پایین نگه دارید

• کش کنید. نرخ هر چند دقیقه یک بار تازه می‌شود (meta.refresh_interval_minutes). کش ۱ تا ۵ دقیقه‌ای سمت شما کافی است و همهٔ نمونه‌های این مخزن آن را دارند.
• چند ارز را در یک درخواست بگیرید: /rates?codes=USD,EUR,AED به‌جای سه درخواست جدا.
• اگر پاسخ ۴۲۹ گرفتید، به اندازهٔ Retry-After صبر کنید و بعد دوباره بفرستید.

خطاهای رایج

کد	یعنی
401 missing_api_key / invalid_api_key	کلید نرسیده یا اشتباه است
403 domain_not_verified	تأیید مالکیت دامنه انجام نشده
403 origin_not_allowed	صفحه روی دامنه‌ای است که روی اپ نیست
403 origin_required / ip_not_allowed	درخواست از سروری آمده که IP آن مجاز نیست (پاسخ فیلد ip دارد)
402 pro_required	این امکان فقط در طرح پرو است
429 rate_limit_exceeded / daily_quota_exceeded	سقف دقیقه‌ای یا سهمیهٔ روزانه پر شده

فهرست کامل: netarz.ir/docs/fx/errors

بررسی خودکار کد و تغییرات

با هر Push و Pull Request، گردش‌کار CI نحو و ساخت همهٔ نمونه‌ها را بررسی می‌کند: Python، JavaScript و JSX، PHP، Go، .NET و اسکریپت‌های cURL. این بررسی هیچ درخواستی به API نمی‌فرستد و کلید نمی‌خواهد. فهرست تغییرات هر نسخه در CHANGELOG.md است.

مخزن‌های دیگر نِت اَرز

مخزن	چیست
netarz-fx-wordpress	افزونهٔ وردپرس همین API: شورت‌کد [netarz_rate currency="usd"]، ابزارک، کش و ترجمهٔ فارسی
ai-api-examples	نمونه‌کد وب‌سرویس هوش مصنوعی: GPT، Claude، Gemini و DeepSeek با یک کلید سازگار با OpenAI
gisoo	گیسو، برند هوش مصنوعی نِت اَرز: اپ فارسی برای گفت‌وگو با بیش از ۴۰۰ مدل، ساخت تصویر، ویدیو، موسیقی و صدا، کارشناس‌های هوش مصنوعی و گفت‌وگوی صوتی، و وب‌سرویس سازگار با OpenAI و Anthropic (Claude Code) (gisoo.pro)
netarz	معرفی همهٔ وب‌سرویس‌ها و مخزن‌های نِت اَرز

همهٔ پروژه‌های متن‌باز ما یک‌جا: netarz.ir/open-source · همهٔ مستندات فنی: netarz.ir/docs

مشارکت و پشتیبانی

• اشکال در کد همین مخزن: یک Issue باز کنید.
• نمونهٔ تازه یا اصلاح: Pull Request بفرستید. پیش از آن راهنمای مشارکت را ببینید.
• اپ، کلید، تأیید دامنه و طرح پرو: از پنل نِت اَرز تیکت بزنید یا به info@netarz.ir ایمیل بفرستید. شناسهٔ اپ و متن کامل پاسخ خطا را هم بفرستید.
• مشکل امنیتی: در Issue عمومی ننویسید؛ طبق سیاست امنیتی به dev@netarz.ir بفرستید.

مجوز: MIT · آیین رفتار

---

English

NetArz FX API examples. Code for showing exchange rates in Iranian Toman (USD, EUR, AED, TRY and more) on websites, apps, bots and spreadsheets, using the NetArz FX API. The rates are the same as on the NetArz rate board; every currency is priced from the live USD market rate through its dollar parity (fixed for pegged currencies, updated daily for the rest).

Quick start

# Create an app and key at https://netarz.ir/fx (localhost is verified automatically), then:
export NETARZ_FX_KEY="fx-ntz-v1-..."
curl -4 "https://netarz.ir/api/fx/v1/rates?codes=USD,EUR,AED" -H "Authorization: Bearer $NETARZ_FX_KEY"

More examples (1.1.0)

(cd go && go run . USD EUR AED)                 # Go, standard library only
dotnet run --project dotnet -- USD EUR AED      # C# / .NET 8, HttpClient
node converter/toman-converter.mjs 250 USD      # Toman converter from one /rates call
python3 telegram-bot/bot.py                     # Telegram bot: /usd, /rates, /convert 100 usd

• react/: useNetArzRates hook and RatesTable component. Point endpoint at your own backend (the key stays on the server), or pass a domain-locked apiKey for direct browser calls, which the docs support because a browser cannot forge Origin.
• converter/: converts many amounts locally from one /rates response, with the same mid/buy/sell rule as GET /convert and prices divided by unit.
• CI (.github/workflows/ci.yml) runs syntax and build checks only; it never calls the API. Release notes: CHANGELOG.md.

Facts

• Base URL https://netarz.ir/api/fx/v1; auth Authorization: Bearer fx-ntz-v1-… or X-API-Key (never ?key=).
• Endpoints: /rates, /rates/{code}, /convert, /currencies, /me, /status; Pro: /history/{code}, /archive/{code} (accepts Gregorian or Jalali dates), /ohlc/{code}, /stats/{code}, /snapshot/{code}, /stream (SSE), /alerts (signed webhooks).
• Domain lock: browser calls are checked by Origin/Referer against the app's verified domains; server calls (no Origin) by the caller's IP against the app's allowed IPs. See guides/domain-and-ip-allow-list.md for servers without a fixed IP and the IPv6 trap.
• buy/sell/mid are Toman per unit units of the currency; meta.as_of is the rate's real time.
• Free plan (membership only): delayed rates, converter, currency list, widget. Pro (per app, monthly): live rates, history and daily archive, OHLC, stats, alerts, SSE stream. Current limits: netarz.ir/docs/fx/plans
• Cache 1 to 5 minutes on your side; rates refresh every few minutes.

Links

• Service overview: netarz.ir/fx-api · Live rate board: netarz.ir/rates
• Docs: netarz.ir/docs/fx · Interactive reference: netarz.ir/docs/fx/reference
• All NetArz open-source projects: netarz.ir/open-source
• Related repos: netarz-fx-wordpress (WordPress plugin) · ai-api-examples (OpenAI-compatible AI API) · gisoo (Gisoo, our Persian AI app and OpenAI/Anthropic-compatible API, gisoo.pro)

Contributions are welcome: see CONTRIBUTING.md. Report security issues privately to dev@netarz.ir (SECURITY.md). Rates are informational. Licensed under MIT.