طلاسنج
در حال دریافت

API و وب‌سرویس رایگان قیمت طلا، سکه و دلار

وب‌سرویس JSON قیمت لحظه‌ای طلای ۱۸ عیار، مظنه آبشده، سکه امامی، دلار تهران و اونس جهانی برای اپ، سایت و کانال تلگرام؛ با استریم زنده، تاریخچه، پیش‌بینی و کارت تصویری. رایگان، با کلید از ربات تلگرام.

شروع سریع در ۳ قدم

  1. در تلگرام ربات @taalasanj_bot را باز کنید، دکمه «👨‍💻 API برنامه‌نویسان» و بعد «ساخت کلید» را بزنید. کلید فقط همان یک بار نشان داده می‌شود.
  2. از سرور خودتان درخواست بفرستید:
curl -H "Authorization: Bearer ts_live_YOUR_KEY" https://talasanj.info/api/v1/prices
  1. کنار قیمت‌ها لینک «قیمت‌ها از طلاسنج» به talasanj.info بگذارید (شرط استفاده رایگان).

داده‌ها هر حدود ۲۰ ثانیه از بازار طلای تهران به‌روز می‌شوند. همه قیمت‌ها عدد صحیح به تومان است (با ?unit=rial به ریال).

کلید API و امنیت

کلید را در هدر بفرستید: Authorization: Bearer ts_live_… (یا X-API-Key). فقط برای /stream و /card.png که در بعضی ابزارها هدر نمی‌پذیرند، ?key= هم قبول می‌شود.

مرجع API

آدرس پایه: https://talasanj.info/api/v1 · دانلود OpenAPI 3.1

آدرسچه می‌دهددسترسی
GET /pricesهمه قیمت‌ها در یک پاسخبدون کلید (۱۰ در دقیقه) یا با کلید
GET /prices/{symbol}یک قلمبدون کلید یا با کلید
GET /marketوضعیت بازار در ۴ بازه زمانیکلید
GET /forecastپیشنهاد امروز و بازه قیمت ۱، ۳ و ۵ روز بعدکلید
GET /historyتاریخچه دقیقه‌ای امروز یا روزانهکلید
GET /streamاستریم زنده (SSE) با هر تغییر قیمتکلید
GET /card.pngکارت تصویری قیمت ۱۰۸۰×۱۳۵۰کلید
GET /statusوضعیت سرویسآزاد

نمادها

symbolقلم
gram18طلای ۱۸ عیار، هر گرم
gram24 · gram21طلای ۲۴ و ۲۱ عیار، هر گرم
mazanehمظنه آبشده، هر مثقال
coin_full · coin_half · coin_quarterسکه امامی تمام، نیم و ربع (با درصد حباب)
usdدلار تهران
ounceاونس جهانی (به دلار)

قیمت‌ها: GET /prices

پارامترها: unit=toman|rial و format=fa (برای هر قیمت متن آماده فارسی مثل «۲۶٬۷۰۱ هزار تومان» و «۲۶ میلیون و ۷۰۱ هزار تومان» هم می‌آید؛ مناسب ربات و کانال).

نمونه پاسخ زنده (چند قلم)

{
  "updated_at": "2026-10-06T20:56:50.000Z",
  "market_open": true,
  "unit": "toman",
  "prices": {
    "gram18": {
      "name_fa": "طلای ۱۸ عیار، هر گرم",
      "price": 26640196,
      "change_pct": -0.28,
      "prev_close": 26715222,
      "day_low": null,
      "day_high": null
    },
    "mazaneh": {
      "name_fa": "مظنه آبشده، هر مثقال",
      "price": 115400000,
      "change_pct": -0.28
    },
    "coin_full": null,
    "usd": {
      "name_fa": "دلار تهران",
      "price": 268900,
      "change_pct": 0,
      "updated_at": "2026-10-06T17:26:51.000Z"
    },
    "ounce": {
      "name_fa": "اونس جهانی طلا",
      "price": 4164.15,
      "unit": "usd",
      "change_pct": -0.02,
      "market_open": true
    }
  },
  "attribution": {
    "text": "قیمت‌ها از طلاسنج",
    "url": "https://talasanj.info",
    "required": true
  }
}

مثال‌ها

const r = await fetch('https://talasanj.info/api/v1/prices', {
  headers: { Authorization: `Bearer ${process.env.TALASANJ_KEY}` },
});
const { prices } = await r.json();
console.log(prices.gram18.price);   // تومان
import os, requests

r = requests.get("https://talasanj.info/api/v1/prices",
                 headers={"Authorization": f"Bearer {os.environ['TALASANJ_KEY']}"}, timeout=10)
r.raise_for_status()
print(r.json()["prices"]["gram18"]["price"])
$ch = curl_init("https://talasanj.info/api/v1/prices");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("TALASANJ_KEY")]]);
$data = json_decode(curl_exec($ch), true);
echo $data["prices"]["gram18"]["price"];

وضعیت بازار: GET /market

چهار بازه «امروز»، «۲ ساعت اخیر»، «روزهای اخیر» و «هفته‌های اخیر» به وقت تهران. برای هر بازه: برچسب فارسی (مثل «داغ، صعودی»)، سطح (calm · normal · hot · veryhot)، نوع (trend · chop · turbulent)، جهت و درصد حرکت، و جایگاه حرکت و نوسان نسبت به دوره‌های مشابه گذشته.

{
  "updated_at": "2026-10-06T20:56:50.000Z",
  "timezone": "Asia/Tehran",
  "hottest": "weeks",
  "rows": {
    "today": null,
    "weeks": {
      "key": "weeks",
      "name_fa": "هفته‌های اخیر",
      "label_fa": "داغ، صعودی",
      "level": "hot",
      "kind": "trend",
      "direction": "up",
      "move_pct": 11.31,
      "move_percentile": 93.2,
      "volatility_percentile": 40.13,
      "from": "2026-09-26",
      "to": "2026-10-06",
      "window_days": 10
    }
  },
  "attribution": {
    "text": "قیمت‌ها از طلاسنج",
    "url": "https://talasanj.info",
    "required": true
  },
  "method": "https://talasanj.info/#market"
}

پیش‌بینی: GET /forecast

پیشنهاد امروز (buy · hold · avoid)، بازه محتمل‌تر (نیمی از موارد) و بازه ۸۰٪ قیمت هر گرم ۱۸ عیار برای ۱، ۳ و ۵ روز کاری بعد، و احتمال بالاتر بودن قیمت. قیمت دقیق قابل پیش‌بینی نیست؛ این‌ها احتمال‌اند، نه توصیه مالی.

{
  "updated_at": "2026-10-06T20:56:50.000Z",
  "symbol": "gram18",
  "unit": "toman",
  "call": "buy",
  "call_fa": "خرید",
  "verdict_fa": "الان فرصت خوبی برای خرید است",
  "horizons": {
    "1d": {
      "business_days": 1,
      "p_up": 0.61,
      "likely": [
        26454274,
        27076430
      ],
      "range80": [
        26104463,
        27383666
      ],
      "point": 26787892
    },
    "5d": {
      "business_days": 5,
      "p_up": 0.71,
      "likely": [
        26342038,
        28070849
      ],
      "range80": [
        25891984,
        29116656
      ],
      "point": 27313055
    }
  },
  "analogs": {
    "days": 150,
    "up_share": 0.77,
    "median_5d_pct": 3.4
  },
  "disclaimer_fa": "قیمت دقیق قابل پیش‌بینی نیست؛ این بازه‌ها احتمالی‌اند و توصیه مالی نیستند.",
  "attribution": {
    "text": "قیمت‌ها از طلاسنج",
    "url": "https://talasanj.info",
    "required": true
  }
}

تاریخچه: GET /history

symbol=gram18|mazaneh|usd و range=1d|30d|90d|1y (پلن حرفه‌ای: 3y). 1d قیمت دقیقه‌ای امروز از شروع معاملات است و بقیه قیمت پایانی روزانه. هر نقطه [زمان، قیمت] است.

curl -H "Authorization: Bearer $TALASANJ_KEY" "https://talasanj.info/api/v1/history?symbol=gram18&range=30d"

استریم زنده: GET /stream

به‌جای درخواست‌های پشت‌سرهم، یک اتصال باز نگه دارید؛ هر بار که قیمتی عوض شود رویداد prices با همان ساختار /prices می‌رسد. هر ۲۵ ثانیه یک پیام نگه‌دارنده (: ping) هم می‌آید. پلن رایگان: ۲ اتصال هم‌زمان برای هر کلید.

import json, os, requests

url = "https://talasanj.info/api/v1/stream"
with requests.get(url, headers={"Authorization": f"Bearer {os.environ['TALASANJ_KEY']}"}, stream=True, timeout=60) as r:
    for line in r.iter_lines():
        if line.startswith(b"data:"):
            print(json.loads(line[5:])["prices"]["gram18"]["price"])
// Node.js 18+
const res = await fetch('https://talasanj.info/api/v1/stream', { headers: { Authorization: `Bearer ${process.env.TALASANJ_KEY}` } });
const dec = new TextDecoder(); let buf = '';
for await (const chunk of res.body) {
  buf += dec.decode(chunk, { stream: true });
  for (let i; (i = buf.indexOf('\n\n')) >= 0; buf = buf.slice(i + 2)) {
    const data = buf.slice(0, i).split('\n').find(l => l.startsWith('data:'));
    if (data) console.log(JSON.parse(data.slice(5)).prices.gram18.price);
  }
}

کارت تصویری برای کانال‌ها: GET /card.png

همان کارت قیمتی که کانال طلاسنج منتشر می‌کند (۱۰۸۰×۱۳۵۰، با نمودار امروز و وضعیت بازار). پلن رایگان: ۶۰ کارت در ساعت. این اسکریپت کوچک هر ۳۰ دقیقه کارت را با ربات خودتان در کانالتان می‌فرستد:

import os, time, requests

KEY, BOT, CHANNEL = os.environ["TALASANJ_KEY"], os.environ["BOT_TOKEN"], "@your_channel"
while True:
    png = requests.get("https://talasanj.info/api/v1/card.png", headers={"Authorization": f"Bearer {KEY}"}, timeout=60).content
    requests.post(f"https://api.telegram.org/bot{BOT}/sendPhoto",
                  data={"chat_id": CHANNEL, "caption": "قیمت‌ها از طلاسنج · talasanj.info"},
                  files={"photo": ("talasanj.png", png)}, timeout=60)
    time.sleep(30 * 60)

ویجت آماده برای سایت (بدون کلید، بدون کدنویسی)

فقط می‌خواهید قیمت طلا را در سایت یا وبلاگتان نشان دهید؟ لازم نیست با API کار کنید: این کد را هر جای صفحه بگذارید. قیمت‌ها هر ۳۰ ثانیه خودکار به‌روز می‌شوند.

<div class="talasanj-widget" data-items="gram18,mazaneh,coin_full,usd" data-theme="light" data-style="box" data-digits="fa">
  <a href="https://talasanj.info">قیمت طلا امروز از طلاسنج</a>
</div>
<script src="https://talasanj.info/widget.js" async></script>

سازنده ویجت با پیش‌نمایش زنده و راهنمای وردپرس، المنتور و بلاگفا

محدودیت‌ها و پلن‌ها

بدون کلیدرایگانحرفه‌ای (به‌زودی)
درخواست در دقیقه۱۰ (برای هر IP)۶۰۶۰۰
سهمیه روزانه—۲۰٬۰۰۰۵۰۰٬۰۰۰
اتصال زنده هم‌زمان—۲۱۰
کارت تصویری در ساعت—۶۰۶۰۰
تاریخچه—تا ۱ سالتا ۳ سال
ذکر منبعلازملازماختیاری

هر پاسخ هدرهای X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset دارد. سهمیه روزانه نیمه‌شب به وقت تهران پر می‌شود. چون قیمت حداکثر هر ۲۰ ثانیه عوض می‌شود، درخواست بیشتر از هر ۲۰ ثانیه فایده‌ای ندارد؛ برای به‌روزرسانی فوری از استریم استفاده کنید. برای سقف بالاتر از ربات پیام بدهید.

خطاها

همه خطاها یک شکل دارند: {"error": {"code", "message", "message_fa", "docs"}}

HTTPcodeمعنی و کار لازم
400bad_param · key_in_queryپارامتر نامعتبر؛ یا کلید را به‌جای آدرس در هدر بفرستید
401no_key · bad_keyکلید لازم است یا نامعتبر/حذف‌شده است؛ از ربات کلید بگیرید
403not_allowedاین امکان در پلن شما نیست
404not_foundآدرس اشتباه است
429rate_limited · daily_quota · too_many_streamsبیش از حد مجاز؛ به اندازه Retry-After صبر کنید
503no_data · busyموقتی؛ چند ثانیه بعد دوباره امتحان کنید

قوانین استفاده و ذکر منبع

پرسش‌های رایج درباره API قیمت طلا

آیا API قیمت طلای طلاسنج رایگان است؟

بله. پلن رایگان ۶۰ درخواست در دقیقه و ۲۰٬۰۰۰ درخواست در روز دارد و فقط شرطش این است که کنار قیمت‌ها لینک «قیمت‌ها از طلاسنج» به talasanj.info دیده شود.

چطور کلید API بگیرم؟

در تلگرام ربات @taalasanj_bot را باز کنید، دکمه «API برنامه‌نویسان» و بعد «ساخت کلید» را بزنید. کلید در چند ثانیه ساخته می‌شود و ثبت‌نام جداگانه لازم نیست.

قیمت‌ها هر چند وقت به‌روز می‌شوند و از کجا می‌آیند؟

حدود هر ۲۰ ثانیه. قیمت‌ها از کانال‌های عمومی بازار طلای تهران و قیمت جهانی اونس جمع و با روش طلاسنج محاسبه می‌شوند؛ با استریم زنده هر تغییر همان لحظه می‌رسد.

چه قیمت‌هایی در API هست؟

طلای ۱۸، ۲۱ و ۲۴ عیار (هر گرم)، مظنه آبشده (هر مثقال)، سکه امامی تمام، نیم و ربع با درصد حباب، دلار تهران و اونس جهانی؛ به‌اضافه وضعیت بازار، پیش‌بینی و تاریخچه.

چطور قیمت طلا را در سایت خودم نشان دهم؟

ساده‌ترین راه ویجت قیمت طلا است: یک تکه کد را کپی و در سایت جای‌گذاری کنید؛ کلید و برنامه‌نویسی لازم ندارد.

با PHP و وردپرس هم کار می‌کند؟

بله. نمونه کد PHP در همین صفحه هست و برای وردپرس، ویجت را در یک بلوک «HTML سفارشی» قرار دهید.

برای کانال تلگرام چه امکانی هست؟

آدرس card.png همان کارت تصویری قیمت را می‌دهد که با یک اسکریپت کوچک (نمونه در همین صفحه) می‌توانید با ربات خودتان در کانالتان منتشر کنید.

تغییرات و نسخه‌ها

تا وقتی نسخه v1 است فقط فیلد اضافه می‌شود و چیزی حذف یا عوض نمی‌شود؛ تغییر ناسازگار با نسخه v2 و اطلاع قبلی می‌آید. نسخه فعلی در هدر X-Api-Version هست.

پشتیبانی

سؤال، گزارش مشکل یا درخواست سقف بالاتر: در ربات @taalasanj_bot پیام بدهید. وضعیت سرویس: /api/v1/status

Iran gold price API (English)

Talasanj offers a free JSON API with real-time Iranian gold prices: 18k gold per gram, mazaneh (Tehran melted-gold benchmark per mithqal), Emami gold coins with their premium, the Tehran free-market US dollar rate and the world gold ounce, in toman (or rial). Prices refresh about every 20 seconds; there is a Server-Sent Events stream, intraday and daily history, a market-state endpoint, a 1/3/5-day forecast and a ready price-card PNG.

Get a free key in Telegram (@taalasanj_bot), then:

curl -H "Authorization: Bearer ts_live_YOUR_KEY" https://talasanj.info/api/v1/prices

Free plan: 60 requests/minute, 20,000/day; attribution «قیمت‌ها از طلاسنج» with a link to https://talasanj.info is required. Machine-readable spec: OpenAPI 3.1.