API عمومی داده‌های بازار

قیمت‌ها، بازارها و فهرست دارایی‌های اس پلاس فاند را بدون ثبت‌نام و بدون کلید دریافت کنید؛ فقط خواندنی، نسخه‌دار و رایگان.

شروع سریع درباره API معاملاتی

نمای کلی

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

همه مسیرها فقط با متد GET کار می‌کنند، به احراز هویت نیاز ندارند و برای همه درخواست‌کنندگان پاسخ یکسانی برمی‌گردانند.

نشانی پایه: https://api.splusfund.com/api/public/v1
نسخه: v1
احراز هویت: ندارد — کلید یا توکن لازم نیست
متدها: GET
قالب: JSON با کدگذاری UTF-8

آنچه این API ارائه نمی‌کند

هیچ اطلاعاتی درباره کاربران، حساب‌ها، موجودی یا سبد دارایی
سفارش‌ها، معاملات کاربران، واریز و برداشت
احراز هویت، ثبت سفارش یا هر عملیات نوشتنی دیگر
دارایی‌هایی که در فهرست عمومی نمایش داده نمی‌شوند

شروع سریع

آخرین قیمت چند دارایی را با یک درخواست بگیرید:

curl -s "https://api.splusfund.com/api/public/v1/prices?symbols=BTC,ETH,USDT"

مرورگر نیز می‌تواند مستقیماً این نشانی‌ها را فراخوانی کند؛ درخواست GET ساده بدون هدر سفارشی به پیش‌درخواست CORS نیازی ندارد.

قراردادهای پاسخ

پاسخ موفق همیشه شامل status، api_version و data است.
قیمت‌ها رشته‌ی عددی دقیق هستند (مثلاً «98765432101234.56789012») تا در تبدیل به عدد اعشاری دقت از دست نرود. آن‌ها را با کتابخانه‌ی اعداد دقیق پردازش کنید.
همه زمان‌ها میلی‌ثانیه‌ی یونیکس (UTC) هستند.
فیلدی که مقدار ندارد با null ارسال می‌شود و هرگز حذف نمی‌شود.
قیمت ریالی، قیمت مؤثر نمایش‌داده‌شده در اس پلاس فاند است؛ قیمت دلاری بر اساس نرخ تتر محاسبه می‌شود و در صورت نبود نرخ null است.
پاسخ‌ها برای مدت کوتاهی کش می‌شوند؛ مدت کش هر مسیر در سرآیند Cache-Control آمده است و تکرار درخواست زودتر از آن داده‌ی تازه‌تری نمی‌دهد.
پارامتر ناشناخته، تکراری یا خالی پذیرفته نمی‌شود و خطای ۴۰۰ برمی‌گرداند.

محدودیت نرخ درخواست

برای حفظ پایداری سرویس، درخواست‌ها در دو سطح محدود می‌شوند:

برای هر نشانی IP: حداکثر ۳۰ درخواست پشت‌سرهم، سپس ۱۰ درخواست در هر ۱۰ ثانیه.
برای کل سرویس: حداکثر ۳۰۰ درخواست پشت‌سرهم، سپس ۱۰۰ درخواست در هر ۱ ثانیه.

در صورت عبور از محدودیت، پاسخ ۴۲۹ با کد خطای ۴۰۲۹ و سرآیند Retry-After (بر حسب ثانیه) برمی‌گردد. پیش از تلاش دوباره همان مدت صبر کنید.

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

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

{
  "status": "Failure",
  "errorCode": 4029,
  "message": "Too many requests from this client. Retry after 10 second(s).",
  "traceId": "0HNOILC44Q4IJ:00000001",
  "timestamp": 1789422992
}

خطاها

همه خطاها ساختار یکسانی دارند:

کد HTTP	errorCode	معنی
400	4006	پارامتر نامعتبر، ناشناخته، تکراری یا خارج از محدوده
404	4004	دارایی یا مسیر یافت نشد
405	—	فقط متد GET پشتیبانی می‌شود (بدون بدنه)
429	4029	عبور از محدودیت نرخ درخواست
503	4018	سامانه در حال بروزرسانی است؛ چند دقیقه بعد دوباره تلاش کنید
503	4503	داده‌ی بازار موقتاً در دسترس نیست

نمونه پاسخ خطا

{
  "status": "Failure",
  "errorCode": 4006,
  "message": "'page' must be an integer between 1 and 1000.",
  "traceId": "0HNOILD89MRS3:00000001",
  "timestamp": 1789423116
}

مسیرها

زمان سرور

GET/api/public/v1/time

ساعت سرور را برمی‌گرداند؛ برای هماهنگ کردن زمان سامانه‌ی شما.

مدت کش: بدون کش

پارامترها

این مسیر پارامتری ندارد.

نمونه درخواست

curl -s "https://api.splusfund.com/api/public/v1/time"

نمونه پاسخ

{
  "status": "Success",
  "api_version": "v1",
  "data": {
    "server_time": 1789423579453,
    "api_version": "v1"
  }
}

فیلدهای data

فیلد	نوع	توضیح
server_time	integer	زمان فعلی سرور، میلی‌ثانیه‌ی یونیکس
api_version	string	نسخه‌ی API

بازارها

GET/api/public/v1/markets

فهرست بازارهای عمومی به ترتیب نمایش.

مدت کش: ۶۰ ثانیه

پارامترها

این مسیر پارامتری ندارد.

نمونه درخواست

curl -s "https://api.splusfund.com/api/public/v1/markets"

نمونه پاسخ

{
  "status": "Success",
  "api_version": "v1",
  "data": [
    {
      "key": "crypto",
      "name_fa": "رمزارز",
      "name_en": "Crypto",
      "position": 1,
      "asset_count": 3
    },
    {
      "key": "metal",
      "name_fa": "طلا و فلزات",
      "name_en": "Metals",
      "position": 2,
      "asset_count": 1
    },
    {
      "key": "currency",
      "name_fa": "ارز",
      "name_en": null,
      "position": 3,
      "asset_count": 1
    }
  ]
}

فیلدهای data

فیلد	نوع	توضیح
key	string	شناسه‌ی ثابت بازار؛ همان مقداری که پارامتر market می‌پذیرد
name_fa	string	نام فارسی بازار
name_en	string\|null	نام انگلیسی بازار
position	integer	جایگاه نمایش، از ۱
asset_count	integer	تعداد دارایی‌های فهرست‌شده در این بازار

دارایی‌ها

GET/api/public/v1/currencies

فهرست دارایی‌های قابل مشاهده، صفحه‌بندی‌شده و قابل فیلتر بر اساس بازار.

مدت کش: ۶۰ ثانیه

پارامترها

نام	الزامی	قواعد
market	خیر	کلید بازار از مسیر markets؛ حداکثر ۴۰ نویسه از A-Z، a-z، 0-9، _ و -
page	خیر	عدد صحیح از ۱ تا ۱۰۰۰؛ پیش‌فرض ۱
page_size	خیر	عدد صحیح از ۱ تا ۱۰۰؛ پیش‌فرض ۵۰

نمونه درخواست

curl -s "https://api.splusfund.com/api/public/v1/currencies?page=1&page_size=3"

نمونه پاسخ

{
  "status": "Success",
  "api_version": "v1",
  "data": {
    "items": [
      {
        "symbol": "BTC",
        "standard_symbol": null,
        "name_fa": "بیت‌کوین",
        "name_en": "Bitcoin",
        "market": "crypto",
        "amount_precision": 8,
        "price_precision": 0
      },
      {
        "symbol": "ETH",
        "standard_symbol": null,
        "name_fa": "اتریوم",
        "name_en": "Ethereum",
        "market": "crypto",
        "amount_precision": 6,
        "price_precision": 0
      },
      {
        "symbol": "USDT",
        "standard_symbol": null,
        "name_fa": "تتر",
        "name_en": "Tether",
        "market": "crypto",
        "amount_precision": 2,
        "price_precision": 0
      }
    ],
    "page": 1,
    "page_size": 3,
    "total": 5
  }
}

فیلدهای data

فیلد	نوع	توضیح
items	array	دارایی‌های این صفحه
page	integer	شماره‌ی صفحه
page_size	integer	اندازه‌ی صفحه
total	integer	تعداد کل دارایی‌های منطبق در همه صفحه‌ها

فیلدهای هر عضو items

فیلد	نوع	توضیح
symbol	string	نماد دارایی در اس پلاس فاند
standard_symbol	string\|null	نماد استاندارد، در صورت تفاوت با نماد
name_fa	string	نام فارسی
name_en	string\|null	نام انگلیسی
market	string	کلید بازاری که دارایی به آن تعلق دارد
amount_precision	integer	تعداد رقم اعشار برای نمایش مقدار این دارایی
price_precision	integer	تعداد رقم اعشار برای نمایش قیمتی که بر حسب این دارایی بیان شود

قیمت‌ها

GET/api/public/v1/prices

آخرین قیمت دارایی‌های فهرست‌شده؛ بدون پارامتر، همه دارایی‌ها. نمادهای ناشناخته نادیده گرفته می‌شوند.

مدت کش: ۱۰ ثانیه

پارامترها

نام	الزامی	قواعد
symbols	خیر	فهرست نمادها با ویرگول؛ ۱ تا ۱۰۰ نماد، هر نماد حداکثر ۲۰ حرف یا رقم لاتین
market	خیر	کلید بازار از مسیر markets؛ حداکثر ۴۰ نویسه از A-Z، a-z، 0-9، _ و -

نمونه درخواست

curl -s "https://api.splusfund.com/api/public/v1/prices?symbols=BTC,ETH,USDT"

نمونه پاسخ

{
  "status": "Success",
  "api_version": "v1",
  "data": [
    {
      "symbol": "BTC",
      "price_irr": "98765432101234.56789012",
      "price_usd": "93852700.88657458",
      "updated_at": 1789422817784
    },
    {
      "symbol": "ETH",
      "price_irr": "3456789012.5",
      "price_usd": "3284.84347525",
      "updated_at": 1789422817784
    },
    {
      "symbol": "USDT",
      "price_irr": "1052345.12345678",
      "price_usd": "1",
      "updated_at": 1789422817784
    }
  ]
}

فیلدهای data

فیلد	نوع	توضیح
symbol	string	نماد دارایی
price_irr	string	آخرین قیمت به ریال، رشته‌ی عددی دقیق
price_usd	string\|null	قیمت دلاری (بر اساس نرخ تتر)، رشته‌ی عددی دقیق
updated_at	integer\|null	زمان آخرین بروزرسانی قیمت، میلی‌ثانیه‌ی یونیکس

خلاصه‌ی ۲۴ ساعته

GET/api/public/v1/tickers

قیمت و درصد تغییر واقعی ۲۴ ساعت گذشته برای چند نماد، به ترتیب الفبایی نماد.

مدت کش: ۱۵ ثانیه

پارامترها

نام	الزامی	قواعد
symbols	بله	الزامی؛ فهرست نمادها با ویرگول؛ ۱ تا ۱۰ نماد، هر نماد حداکثر ۲۰ حرف یا رقم لاتین

نمونه درخواست

curl -s "https://api.splusfund.com/api/public/v1/tickers?symbols=BTC,ETH,GOLD18"

نمونه پاسخ

{
  "status": "Success",
  "api_version": "v1",
  "data": [
    {
      "symbol": "BTC",
      "price_irr": "98765432101234.56789012",
      "price_usd": "93852700.88657458",
      "change_24h_percent": "-0.80",
      "updated_at": 1789422817784
    },
    {
      "symbol": "ETH",
      "price_irr": "3456789012.5",
      "price_usd": "3284.84347525",
      "change_24h_percent": "-0.80",
      "updated_at": 1789422817784
    },
    {
      "symbol": "GOLD18",
      "price_irr": "186070000",
      "price_usd": "176.81461704",
      "change_24h_percent": "-0.80",
      "updated_at": 1789422812784
    }
  ]
}

فیلدهای data

فیلد	نوع	توضیح
symbol	string	نماد دارایی
price_irr	string	آخرین قیمت به ریال
price_usd	string\|null	قیمت دلاری
change_24h_percent	string\|null	درصد تغییر ۲۴ ساعته با دو رقم اعشار؛ اگر سابقه‌ی کافی نباشد null
updated_at	integer\|null	زمان آخرین بروزرسانی قیمت، میلی‌ثانیه‌ی یونیکس

سابقه‌ی قیمت

GET/api/public/v1/history

سری زمانی قیمت یک دارایی برای بازه‌ی انتخابی؛ در هر بازه‌ی زمانی آخرین قیمت ثبت‌شده.

مدت کش: ۶۰ ثانیه

پارامترها

نام	الزامی	قواعد
symbol	بله	یک نماد؛ حداکثر ۲۰ حرف یا رقم لاتین
period	خیر	یکی از 24h, 7d, 30d, 90d, 1y؛ پیش‌فرض 24h

نمونه درخواست

curl -s "https://api.splusfund.com/api/public/v1/history?symbol=BTC&period=24h"

نمونه پاسخ

{
  "status": "Success",
  "api_version": "v1",
  "data": {
    "symbol": "BTC",
    "period": "24h",
    "interval": "15m",
    "points": [
      {
        "t": 1789337320784,
        "price_irr": "99560108376900.125",
        "price_usd": null
      },
      {
        "t": 1789338220784,
        "price_irr": "99476652191278.96875",
        "price_usd": null
      },
      {
        "t": 1789339120784,
        "price_irr": "99377916924386.15625",
        "price_usd": null
      }
    ]
  }
}

فیلدهای data

فیلد	نوع	توضیح
symbol	string	نماد دارایی
period	string	بازه‌ی درخواستی
interval	string	فاصله‌ی نقاط سری
points	array	نقاط سری به ترتیب صعودی زمان

فیلدهای هر عضو points

فیلد	نوع	توضیح
t	integer	زمان نقطه، میلی‌ثانیه‌ی یونیکس
price_irr	string	قیمت به ریال
price_usd	string\|null	قیمت دلاری، در صورت ثبت

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

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

داده‌ها صرفاً جنبه‌ی اطلاع‌رسانی دارند و قیمت نهایی هر معامله در اپلیکیشن اس پلاس فاند تعیین می‌شود.