دریافت قیمت دلار با پایتون؛ آموزش قدم‌به‌قدم قیمت دلار و تتر با requests

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

این آموزش بخشی از راهنمای کامل API قیمت ارز و طلا است؛ اگر هنوز کلید ندارید، اول بخش «ساخت کلید API» آن راهنما را بخوانید.

آماده‌سازی محیط

به پایتون ۳٫۹ یا جدیدتر و کتابخانهٔ requests نیاز دارید. بهتر است پروژه را در یک محیط مجازی بسازید:

python3 -m venv venv
source venv/bin/activate        # در ویندوز: venv\Scripts\activate
pip install requests
export EZRATE_KEY="ezr_live_…"   # در ویندوز: set EZRATE_KEY=ezr_live_…

اولین اسکریپت: قیمت دلار و تتر

import os
import requests

API = "https://api.ezrate.me/v1"
KEY = os.environ["EZRATE_KEY"]

r = requests.get(
    f"{API}/rates",
    params={"symbols": "usd,usdt", "lang": "fa"},
    headers={"X-API-Key": KEY},
    timeout=10,
)
r.raise_for_status()

for item in r.json()["data"]:
    print(f"{item['name']}: خرید {item['buy']:,} | فروش {item['sell']:,} تومان "
          f"({item['change_pct']:+.2f}٪، {item['sources']} منبع)")

خروجی دو خط است: نام دارایی، نرخ خرید و فروش با جداکنندهٔ هزارگان، درصد تغییر ۲۴ ساعت و تعداد منابع. فیلد sources را جدی بگیرید؛ اگر عددش کم است یا low_sources مقدار true دارد، یعنی در آن ساعت بازار خلوت بوده است.

قیمت به ریال یا بر حسب تتر

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

def rates(symbols, quote="IRT"):
    r = requests.get(f"{API}/rates", params={"symbols": symbols, "quote": quote},
                     headers={"X-API-Key": KEY}, timeout=10)
    r.raise_for_status()
    return {x["symbol"]: x for x in r.json()["data"]}

print(rates("usd", quote="IRR")["usd"]["sell"])       # دلار به ریال
print(rates("btc,eth", quote="USDT")["btc"]["sell"])  # بیت‌کوین بر حسب تتر

مدیریت خطا به شکل حرفه‌ای

اسکریپتی که هر چند دقیقه اجرا می‌شود، دیر یا زود با قطعی اینترنت یا تمام شدن سهمیه روبه‌رو می‌شود. نسخهٔ قابل اتکا این‌طور است:

import time

def fetch_rates(symbols, retries=3):
    for attempt in range(retries):
        try:
            r = requests.get(f"{API}/rates", params={"symbols": symbols},
                             headers={"X-API-Key": KEY}, timeout=10)
        except requests.RequestException:
            time.sleep(2 ** attempt)          # 1s، 2s، 4s
            continue
        if r.status_code == 401:
            raise SystemExit("کلید نامعتبر است؛ پنل کاربری را بررسی کنید.")
        if r.status_code == 429:
            reset = r.json().get("meta", {}).get("reset_at")
            raise RuntimeError(f"سهمیه تمام شده؛ بازشدن: {reset}")
        if r.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        r.raise_for_status()
        return r.json()["data"]
    raise RuntimeError("API در دسترس نیست؛ آخرین نرخ ذخیره‌شده را استفاده کنید.")

منطق هر کد خطا در مدیریت خطا و Rate Limit در APIهای مالی توضیح داده شده است.

ذخیرهٔ روزانه در فایل CSV

برای داشتن آرشیو شخصی، کافی است اسکریپت را روزی یک‌بار اجرا کنید و نتیجه را به فایل اضافه کنید:

import csv, datetime

data = fetch_rates("usd,usdt,g18,emami")
today = datetime.date.today().isoformat()
with open("rates.csv", "a", newline="", encoding="utf-8") as f:
    w = csv.writer(f)
    for x in data:
        w.writerow([today, x["symbol"], x["buy"], x["sell"], x["sources"]])

اگر دادهٔ گذشته را هم می‌خواهید، لازم نیست ماه‌ها صبر کنید: مسیر history کندل‌های روزانه را یک‌جا می‌دهد. آموزش آن در دیتای تاریخی قیمت دلار و طلا آمده است.

هشدار ساده وقتی دلار از عدد دلخواه عبور کرد

TARGET = 0   # عدد دلخواه خود را به تومان بنویسید

usd = {x["symbol"]: x for x in fetch_rates("usd")}["usd"]
if usd["sell"] >= TARGET:
    print(f"دلار به {usd['sell']:,} تومان رسید.")
    # اینجا می‌توانید ایمیل یا پیام تلگرام بفرستید

این اسکریپت را با cron (لینوکس) یا Task Scheduler (ویندوز) هر ده دقیقه اجرا کنید. اگر فقط هشدار شخصی می‌خواهید و برنامه‌نویسی برایتان هدف نیست، هشدار قیمت EZRate همین کار را بدون کد با ایمیل، تلگرام یا اعلان مرورگر انجام می‌دهد.

چند توصیهٔ عملی

• فاصلهٔ اجرای اسکریپت را از meta.freshness_sec کمتر نکنید؛ درخواست بیشتر عدد تازه‌تری نمی‌دهد و فقط سهمیه مصرف می‌کند.
• برای چند نماد یک درخواست بفرستید (symbols=usd,eur,aed) نه چند درخواست جدا.
• در داده‌های ذخیره‌شده واحد را ثبت کنید (quote) تا بعدها تومان و ریال قاطی نشوند.
• نسخهٔ انگلیسی همین آموزش با مثال جنگو در USD to IRR API in Python & Django آمده است.

مقایسهٔ دلار و تتر در یک اسکریپت

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

d = {x["symbol"]: x for x in fetch_rates("usd,usdt")}
gap = (d["usdt"]["sell"] - d["usd"]["sell"]) / d["usd"]["sell"] * 100
print(f"اختلاف تتر با دلار آزاد: {gap:+.2f}٪")

اگر این عدد را هر ساعت در فایل ذخیره کنید، بعد از چند هفته نمودار جالبی از رفتار بازار دارید. برای آرشیو طولانی‌تر، کندل‌های روزانهٔ هر دو را از history بگیرید و با هم مقایسه کنید.

تحلیل سریع با pandas

اگر با داده‌ها کار تحلیلی می‌کنید، pandas کار را خیلی کوتاه می‌کند. نمونهٔ زیر کندل‌های روزانهٔ دلار را می‌گیرد، میانگین متحرک ۷ روزه حساب می‌کند و بیشترین تغییر روزانه را پیدا می‌کند:

import pandas as pd

r = requests.get(f"{API}/history/usd", params={"interval": "1d", "from": "2026-07-01"},
                 headers={"X-API-Key": KEY}, timeout=15)
df = pd.DataFrame(r.json()["data"])
df["t"] = pd.to_datetime(df["t"])
df = df.set_index("t")
df["ma7"] = df["c"].rolling(7).mean()
df["chg"] = df["c"].pct_change() * 100
print(df[["c", "ma7", "chg"]].tail(10))
print("بیشترین رشد روزانه:", df["chg"].idxmax().date(), round(df["chg"].max(), 2), "٪")

ستون‌های o، h، l و c به ترتیب قیمت باز، بیشترین، کمترین و بسته شدن هر روز هستند. عمق تاریخچه به پلن شما بستگی دارد.

زمان‌بندی اجرا با cron

در لینوکس، با crontab -e یک خط اضافه کنید تا اسکریپت هر ۱۰ دقیقه اجرا شود. متغیر محیطی کلید را هم در همان خط یا در فایل جدا تعریف کنید، چون cron متغیرهای محیطی ترمینال شما را نمی‌بیند:

*/10 * * * * EZRATE_KEY=ezr_live_… /home/me/venv/bin/python /home/me/rates.py >> /home/me/rates.log 2>&1

در ویندوز همین کار با Task Scheduler انجام می‌شود: یک Task جدید بسازید، در بخش Action مسیر python.exe و آدرس اسکریپت را بدهید و در Trigger تکرار هر ۱۰ دقیقه را تنظیم کنید.

نمایش اعداد فارسی و جداکنندهٔ هزارگان

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

FA = str.maketrans("0123456789,", "۰۱۲۳۴۵۶۷۸۹٬")
def fa_num(n: int) -> str:
    return f"{n:,}".translate(FA)

print(fa_num(1234567))   # ۱٬۲۳۴٬۵۶۷

نرخ‌های لحظه‌ای مرتبط با این مطلب: قیمت دلار، قیمت تتر، قیمت طلای ۱۸ عیار.