API و وبسرویس رایگان قیمت طلا، سکه و دلار
وبسرویس JSON قیمت لحظهای طلای ۱۸ عیار، مظنه آبشده، سکه امامی، دلار تهران و اونس جهانی برای اپ، سایت و کانال تلگرام؛ با استریم زنده، تاریخچه، پیشبینی و کارت تصویری. رایگان، با کلید از ربات تلگرام.
شروع سریع در ۳ قدم
- در تلگرام ربات @taalasanj_bot را باز کنید، دکمه «👨💻 API برنامهنویسان» و بعد «ساخت کلید» را بزنید. کلید فقط همان یک بار نشان داده میشود.
- از سرور خودتان درخواست بفرستید:
curl -H "Authorization: Bearer ts_live_YOUR_KEY" https://talasanj.info/api/v1/prices- کنار قیمتها لینک «قیمتها از طلاسنج» به talasanj.info بگذارید (شرط استفاده رایگان).
دادهها هر حدود ۲۰ ثانیه از بازار طلای تهران بهروز میشوند. همه قیمتها عدد صحیح به تومان است (با ?unit=rial به ریال).
کلید API و امنیت
کلید را در هدر بفرستید: Authorization: Bearer ts_live_… (یا X-API-Key). فقط برای /stream و /card.png که در بعضی ابزارها هدر نمیپذیرند، ?key= هم قبول میشود.
- کلید را فقط در سرور نگه دارید؛ هرگز در جاوااسکریپت سایت، اپ منتشرشده یا مخزن عمومی گیت نگذارید. برای نمایش قیمت در صفحه سایت از ویجت استفاده کنید که کلید نمیخواهد.
- هر حساب تلگرام تا ۳ کلید فعال دارد. اگر کلیدی لو رفت، همان لحظه از ربات حذفش کنید و کلید تازه بسازید.
- ما کلید را ذخیره نمیکنیم؛ فقط اثر رمزنگاریشده (SHA-256) آن را نگه میداریم. پس کلید گمشده قابل بازیابی نیست.
- همه درخواستها روی HTTPS. پاسخها
ETagدارند: باIf-None-Matchاگر قیمت عوض نشده باشد پاسخ304و بدون مصرف پهنای باند میگیرید.
مرجع 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-06T19:52:13.000Z",
"market_open": true,
"unit": "toman",
"prices": {
"gram18": {
"name_fa": "طلای ۱۸ عیار، هر گرم",
"price": 26665589,
"change_pct": -0.08,
"prev_close": 26686366,
"day_low": 26565169,
"day_high": 26844499
},
"mazaneh": {
"name_fa": "مظنه آبشده، هر مثقال",
"price": 115510000,
"change_pct": -0.08
},
"coin_full": null,
"usd": {
"name_fa": "دلار تهران",
"price": 268900,
"change_pct": -0.19,
"updated_at": "2026-10-06T17:26:51.000Z"
},
"ounce": {
"name_fa": "اونس جهانی طلا",
"price": 4167.19,
"unit": "usd",
"change_pct": 0.72,
"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-06T19:52:13.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.74,
"move_percentile": 93.9,
"volatility_percentile": 40.93,
"from": "2026-09-25",
"to": "2026-10-05",
"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-06T19:52:13.000Z",
"symbol": "gram18",
"unit": "toman",
"call": "buy",
"call_fa": "خرید",
"verdict_fa": "الان فرصت خوبی برای خرید است",
"horizons": {
"1d": {
"business_days": 1,
"p_up": 0.61,
"likely": [
26519932,
27099535
],
"range80": [
26147853,
27410803
],
"point": 26813430
},
"5d": {
"business_days": 5,
"p_up": 0.72,
"likely": [
26402015,
28076140
],
"range80": [
25874268,
29160593
],
"point": 27365419
}
},
"analogs": {
"days": 150,
"up_share": 0.79,
"median_5d_pct": 3.51
},
"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"}}
| HTTP | code | معنی و کار لازم |
|---|---|---|
| 400 | bad_param · key_in_query | پارامتر نامعتبر؛ یا کلید را بهجای آدرس در هدر بفرستید |
| 401 | no_key · bad_key | کلید لازم است یا نامعتبر/حذفشده است؛ از ربات کلید بگیرید |
| 403 | not_allowed | این امکان در پلن شما نیست |
| 404 | not_found | آدرس اشتباه است |
| 429 | rate_limited · daily_quota · too_many_streams | بیش از حد مجاز؛ به اندازه Retry-After صبر کنید |
| 503 | no_data · busy | موقتی؛ چند ثانیه بعد دوباره امتحان کنید |
قوانین استفاده و ذکر منبع
- ذکر منبع: در استفاده رایگان، کنار قیمتها و در همان صفحه یا پست، متن «قیمتها از طلاسنج» با لینک به https://talasanj.info دیده شود.
- بدون فروش مجدد: داده را بهعنوان فید قیمت خودتان نفروشید و API عمومی دیگری از آن نسازید.
- قیمتها تقریبیاند: از کانالهای عمومی بازار جمع و محاسبه میشوند و ممکن است چند ثانیه تا یک دقیقه تأخیر داشته باشند؛ برای اجرای معامله به آنها تکیه نکنید.
- بدون ضمانت: سرویس «همانطور که هست» ارائه میشود و ممکن است گاهی در دسترس نباشد.
- سوءاستفاده: کلیدهایی که از محدودیتها دور میزنند یا قوانین را رعایت نمیکنند ممکن است بدون اطلاع قبلی غیرفعال شوند.
- طلاسنج توصیه مالی نمیدهد.
پرسشهای رایج درباره 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/pricesFree plan: 60 requests/minute, 20,000/day; attribution «قیمتها از طلاسنج» with a link to https://talasanj.info is required. Machine-readable spec: OpenAPI 3.1.