NAV
shell plaintext

مستندات API سهمتو

Sahmeto

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

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

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

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

احراز هویت و توکن

Authorization: Token yourTOKENhereHEX0000000000

برای استفاده از APIهای غیر عمومی نیاز به ارسال توکن وجود دارد. این توکن باید به عنوان HTTP Header درخواست به صورت زیر ارسال شود:

Authorization: Token yourTOKENhereHEX0000000000

به جز APIهای بخش‌هایی که عنوان «عمومی» در انتهای نام‌شان آورده شده باشد، برای استفاده از تمام APIها نیاز به ارسال توکن وجود دارد. توکن مشخص می‌کند که کدام کاربر در حال ارسال این درخواست است.

برای دریافت توکن می‌توانید با مراجعه به پنل کاربری خود در سهمتو، از بخش پروفایل وارد صفحه تنظیمات شده و توکن خود را دریافت نمایید. در صورتی که گزینه «مرا به خاطر بسپار» را در هنگام ورود به سهمتو انتخاب کرده باشید، این توکن تا ۳۰ روز یا زمان لاگ‌اوت شما از سهمتو معتبر خواهد ماند.

در صورت تمایل به دریافت دوره‌ای و خودکار توکن، می‌توانید از API ورود - دریافت توکن استفاده نمایید. ولی این کار ضروری نیست و روش پیشنهادی ما برای اغلب کاربران دریافت مستقیم توکن از پنل کاربری است. تنها در صورتی که با مخاطرات ذخیره گذرواژه خود در کد و روش‌های امن این کار آشنا هستید، در استفاده از API مهارت دارید، و از طرفی نیاز به دریافت کاملاً خودکار توکن دارید، از API دریافت توکن استفاده نمایید.

تنظیم User Agent

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

محدودیت‌ها

توجه داشته باشید، برای استفاده از APIها محدودیت هایی وجود دارد که در قسمت توضیحات هر کدام از APIها این موارد ذکر شده است.

تغییرات و موارد قدیمی

با توجه به ماهیت نوین و تغییرات مستمر مورد نیاز در حوزه رمزارزها، در API سهمتو نیز ممکن است در طول زمان تغییراتی ایجاد شود. پشتیبانی طولانی‌مدت از نسخه‌های قدیمی API معمولاً فرآیندی پیچیده و سخت است و باعث کاهش سرعت ایجاد تغییرات جدید در بستر سهمتو می‌شود. به همین دلیل API سهمتو همواره در عین حفظ ساختار کلی و اجزای اصلی ثابت، در حال بهبود مستمر و به‌روزرسانی است. کاربران گرامی می‌توانند با پیگیری تغییرات API که در صفحه سابقه تغییرات API سهمتو اطلاع‌رسانی می‌شود، همواره از تغییرات احتمالی ضروری در کد خود مطلع شوند تا بتوانند به صورت بدون وقفه از جدیدترین امکانات و روش‌های دسترسی به API سهمتو بهره‌مند شوند.

مواردی که قبلاً در API موجود بودند ولی در حال حاضر پشتیبانی نمی‌شوند، جهت ثبت سابقه در صفحه API قدیمی موجود هستند. ممکن است APIهای دیگری علاوه بر موارد مستند شده در مستندات پیش‌رو وجود داشته باشند، که این موارد جز API رسمی سهمتو نبوده و تضمینی در قبال ادامه‌دار بودن پشتیبانی از آن‌ها وجود ندارد. همین طور در استفاده از APIهای فعلی لازم به توضیح است که ممکن است علاوه بر فیلدهایی که در ورودی یا خروجی مستند شده است، فیلدهای دیگری نیز وجود داشته باشند. این فیلدها تا زمانی که در مستندات اضافه نشده باشند باید به عنوان امکانات آزمایشی و موقت در نظر گرفته شوند و نباید مورد استفاده عموم کاربران قرار گیرد. تنها کافی است که کدهای توسعه داده شده در صورت مشاهده فیلدی غیر از فیلدهای مورد انتظار خود، دچار خطا نشوند و صرفاً وجود آن فیلد را نادیده بگیرند.

راهنمای حل مشکلات

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

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

در صورتی که بخشی از مستندات API مبهم است، یا پیشنهادی درباره APIهای موجود دارید، یا پس از بررسی کامل اطمینان دارید که مشکلی در API سهمتو وجود دارد، می‌توانید در مخزن گیت‌هاب مستندات سهمتو API مورد (issue) جدیدی را ایجاد نمایید و با ما در ارتباط باشید. دقت کنید که این کانال عمومی است و نباید در آن هیچ گونه اطلاعات حساس یا توکن یا سایر اطلاعات حساب خود را مطرح کنید.

راهنمای شروع به کار با API

اگر برای اولین بار از API سهمتو یا سایر بازارهای رمزارز استفاده می‌کنید، برای شروع کار پیشنهاد می‌شود گام‌های زیر را طی کنید:

همین طور می‌توانید بنا به نیاز خود این موارد را نیز در ادامه در نظر بگیرید:

تریدر

لیست تریدرها

curl 'https://api.sahmeto.com/api/v1/telegram/publishers/list'

http GET 'https://api.sahmeto.com/api/v1/telegram/publishers/list'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

[
  {
    "telegram_id": -9223372036854776000,
    "primary_username": "string",
    "account_type": "telegram",
    "name": "string",
    "photo": "string",
    "is_top": "string"
  }
]

پارامترهای ورودی

پارامتر نوع پیش‌فرض توضیحات نمونه
» telegram_id integer¦null false none none
» primary_username string false read-only none
» account_type string false none none
» name string false none none
» photo string false read-only none
» is_top string false read-only none

جزییات تریدر

curl '/api/v1/telegram/publishers/{telegram_id}'

http GET https://api.sahmeto.com/v2/trades/BCHIRT

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "id": 0,
  "telegram_id": -9223372036854776000,
  "username": "string",
  "name": "string",
  "primary_username": "string",
  "account_type": "telegram",
  "description": "string",
  "members_count": -2147483648,
  "active": true,
  "publisher_rank": -2147483648,
  "post_avg_view": -9223372036854776000,
  "post_daily_avg_count": -9223372036854776000,
  "channel_daily_avg_view": -9223372036854776000,
  "photo": "string",
  "messages": "string",
  "is_verified": true,
  "publisher_type": "analytical",
  "verified_description": "string",
  "book_marked_by_user": "string",
  "social_impact": "string",
  "min_capital_loss": "string",
  "tags": [
    0
  ]
}

برای دریافت لیست معاملات از این نوع درخواست استفاده نمایید:

پارامتر نوع پیش‌فرض توضیحات نمونه
telegram_id path integer true none

پیام های تریدر

curl '/api/v1/telegram/publishers/{telegram_id}/messages'

http GET  '/api/v1/telegram/publishers/{telegram_id}/messages'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "count": 0,
  "next": "http://example.com",
  "previous": "http://example.com",
  "results": [
    {
      "id": 0,
      "text": "string",
      "date": "2019-08-24T14:15:22Z",
      "account_type": "telegram",
      "photo": "string",
      "html_message": "string",
      "signals": "string",
      "bookmarked_by_user": "string"
    }
  ]
}

برای دریافت آخرین آمار بازار سهمتو از این نوع درخواست استفاده نمایید:

پارامتر نوع پیش‌فرض توضیحات نمونه
» count integer true none none
» next string(uri)¦null false none none
» previous string(uri)¦null false none none
» results [MessageSignal] tr
»» id integer false read-only none
»» text string true none none
»» date string(date-time) true none none
»» account_type string false none none
»» photo string false read-only none
»» html_message string false read-only none
»» signals string false read-only none
»» bookmarked_by_user string false read-only none

بازدهی و نمودار تریدر

دریافت اطلاعات مشخصات پرفرمنس و بازدهی یک تریدر

هر تریدر بر اساس تعداد پیام ها ودرصد درستی سال ها و فعالیتی که دارد دارای نمودار بازدهی خاص خود میباشد.

curl 'http://localhost:8000/api/v1/telegram/publishers/{telegram_id}/performance_risk_chart'

http GET 'http://localhost:8000/api/v1/telegram/publishers/{telegram_id}/performance_risk_chart'

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

{
  "performance": "string",
  "risk": "string"
}
پارامتر نوع پیش‌فرض توضیحات نمونه
telegram_id path integer true none

سیگنال ها

سیگنال های بورسی

پیام های بورسی ای که حاوی سیگنال خرید یا فروش هستند.

پیام ها پس از تایید هوش مصنوعی به صورت سیگنال معامله ای در میاید در زیر لیستی از سیگنال های خرید و فروش را مشاهده میکنید.

curl 'https://api.sahmeto.com/api/v1/core/most-recommended-tickers/signals?v=&t='

http GET 'https://api.sahmeto.com/api/v1/core/most-recommended-tickers/signals?v=&t='

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

[
  {
    "id": -36434643,
    "value": "N",
    "type": "N",
    "message": "{"id":2674257,"text":"❇️ نمادهای تاثیرگذار در شاخص کل و شاخص هم‌وزن\n\n📍 نمادهای #شپنا #فارس #شبندر #حکشتی #کچاد #شفن و #کگل نمادهای تاثیرگذار در شاخص کل\n\n📍 نمادهای #آریا #زاگرس #فغدیر #صبا  #خدیزل #اتکای و #وملل  بیشترین تاثیر در شاخص هم وزن\n\n@boursika_official","date":"2022-10-17T15:31:42+03:30","account_type":"telegram","photo":null,"html_message":"❇️ نمادهای تاثیرگذار در شاخص کل و شاخص هم‌وزن\n\n📍 نمادهای #شپنا #فارس #شبندر #حکشتی #کچاد #شفن و #کگل نمادهای تاثیرگذار در شاخص کل\n\n📍 نمادهای #آریا #زاگرس #فغدیر #صبا  #خدیزل #اتکای و #وملل  بیشترین تاثیر در شاخص هم وزن\n\n@boursika_official","publisher":{"id":530,"content_type":23,"name":"تحلیل سهام بورسیکا","primary_username":"g_1421873113","account_type":"telegram","telegram_id":1421873113,"username":"boursika_official","rank":143,"photo":{"image":"/media/telegram_media/channel_profile_photos/1421873113_big.jpg","thumbnail_85":"/media/telegram_media/channel_profile_photos/1421873113.thumb_85","thumbnail_270":"/media/telegram_media/channel_profile_photos/1421873113.thumb_270"}",
    "score": "1.2",
    "is_verified": "True"
  }
]
پارامتر نوع پیش‌فرض توضیحات نمونه

سیگنال های کریپتویی

پیام های کریپتویی که حاوی سیگنال خرید یا فروش هستند.

پیام های کریپتویی همانند پیام های بورسی پس از تایید هوش مصنوعی به صورت سیگنال معامله ای در میاید در زیر لیستی از سیگنال های خرید و فروش را مشاهده میکنید.

curl 'https://api.sahmeto.com/api/v1/crypto/recommended/signals?v=&t='

http GET 'https://api.sahmeto.com/api/v1/crypto/recommended/signals?v=&t='

در صورت فراخوانی درست، پاسخ به این صورت خواهد بود:

[
  {
    "id": -36434643,
    "value": "N",
    "type": "N",
    "message": ""message":{"id":2674007,"text":"THETA update \n Risk warning, disclaimer: the above is a personal market judgment based on published information and historical chart data on Tradingview, all analysis is only subjective. Hope investors consider, I am not responsible for your investment decision. \n\r\nBe careful of Scammers impersonating me (Trader_OMS), my community/channel/platforms to scam you. \r\nI will NEVER message you first on my offical platforms to SELL you anything. \n\r\nThank you. \r\nGood luck","date":"2022-10-17T13:19:32+03:30","account_type":"tradingview","photo":{"image":"https://s3.tradingview.com/r/R4ZuhuIQ_mid.png","thumbnail":"https://s3.tradingview.com/r/R4ZuhuIQ_mid.png"}",
    "score": "1.2",
    "is_verified": "True"
  }
]
پارامتر نوع پیش‌فرض توضیحات نمونه

ملاحظات عمومی

راهنمای اشکال‌یابی

پاسخ‌های موفق

نمونه پاسخ موفق:

{
  "status": "ok",
  "otherFields": "..."
}

در تمامی API ها در صورتی که عملیات مد نظر به درستی انجام شده باشد، پاسخ به صورت یک شی در قالب JSON بازگردانده می‌شود و با وضعیت HTTP 200 است. این پاسخ در حالت موفق یک کلید status با مقدار ok دارد. بنا به API مورد استفاده ممکن است یک یا چند کلید دیگر نیز در این پاسخ بازگردانده شود.

پاسخ‌های ناموفق

نمونه پاسخ ناموفق:

{
  "status": "failed",
  "code": "ErrorCode",
  "message": "Human-readable error message"
}

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

در صورتی که پارامترهای ورودی قابل تفسیر باشند، ولی عملیات مد نظر قابل انجام نباشد، پاسخ با وضعیت HTTP 200 بازگردانده می‌شود، و توضیحات تکمیلی به صورت یک شی در قالب JSON خواهد بود که مقدار کلید status آن برابر failed است. کلید code در این شرایط، خطای دقیق رخ داده شده را مشخص می‌کند که در بخش «حالت‌های خطا» در توضیحات هر API فهرستی از کدهای خطای ممکن و توضیحات آن ارائه شده است. معمولاً در یک کلید message توضیح بیشتری در مورد آن خطا نیز ارائه می‌شود که جهت رفع عیب یا نمایش مستقیم به کاربر نهایی می‌تواند مفید باشد.

برخی وضعیت‌های پرکاربرد

کد HTTP عنوان توضیحات ‌
200 OK درخواست دریافت و پاسخ داده شده، وضعیت اصلی درخواست در فیلد status پاسخ مشخص می‌شود.
400 Bad Request پارامترهای درخواست نادرست یا ناکافی است به طوری که امکان بررسی بیشتر و پاسخ بهتر به آن وجود ندارد.
401 Unauthorized کاربر احراز هویت نشده است
403 Forbidden انجام این عملیات مجاز نمی‌باشد
404 Not Found آدرس یا شی مد نظر وجود ندارد 🐱
500 Internal Server Error مشکلی به صورت موقت در سرور سهمتو رخ داده است 🐱

صفحه‌بندی

پارامترهای زیر در API های دریافت لیست دارای صفحه‌بندی قابل استفاده است:

پارامتر نوع پیش‌فرض توضیحات نمونه
page int اختیاری شماره صفحه 2
pageSize int اختیاری اندازه صفحه 10

مقادیر پولی (monetary)

در موارد متعددی پارامترهای ورودی درخواست‌ها از نوع مقدار پولی یا monetary مشخص شده است. برای داشتن بالاترین دقت، پیشنهاد می‌شود که این مقادیر را به صورت رشته‌ای ارسال نمایید، چرا که استفاده از انواع داده‌ای مانند float در کاربردهای دقیق مالی توصیه نمی‌شود.

اعتبارسنجی دو عاملی

در صورتی که اعتبارسنجی دو عاملی (2 Factor Authentication) را برای حساب خود فعال کرده باشید، باید در هنگام استفاده از برخی APIها، به خصوص در هنگام دریافت توکن از API لاگین، علاوه بر سایر پارامترها، رمز یک‌بار مصرف خود را نیز در هدرهای درخواست به این صورت ارسال نمایید: X-TOTP: 123456.

محدودیت‌های فراخوانی API

برخی از APIهای سهمتو دارای محدودیت تعداد فراخوانی در هر بازه‌ی زمانی هستند. با این حال اگر شما به صورت معمولی و مشابه استفاده‌ی متداول کاربران از API استفاده کنید، با این محدودیت‌ها مواجه نخواهید شد. محدودیت‌ها به ازای هر API مستقلا محاسبه و اعمال می‌شوند. محدودیت‌ها معمولا بر اساس آدرس IP درخواست دهنده و در موارد هم بر اساس کاربر (توکن) درخواست دهنده می‌باشند. در حالتی که به حد مجاز تعداد فراخوانی یک API رسیده باشید، پاسخ آن API به شما یک پیام خطا با کد 403 و دارای توضیحات مشخص در خصوص آن محدودیت خواهد بود.

در صورتی که به صورت موردی یا در حین تست کد خود به محدودیتی برخورد کردید، می‌توانید با منتظر ماندن (بین یک ساعت تا یک روز) آن محدودیت را برطرف کنید و دوباره امکان استفاده از API مد نظرتان را داشته باشید. اگر به صورت مداوم به محدودیتی برای یک API برخورد می‌کنید و فکر می‌کنید که بهتر است تعداد فراخوانی مجاز آن API افزایش یابد، حتما با ایجاد یک مورد در گیت‌هاب (لینک ایجاد مورد) مسئله را با ما مطرح نمایید.

حالت متداول و Pro

در برخی از درخواست‌ها جهت حفاظت بهتر از کاربران، برخی محدودیت‌ها اعمال می‌شود. در چنین مواردی در بخش ملاحظات این محدودیت‌ها توضیح داده شده و در انتهای آن عبارت «غیرفعال در حالت Pro» ذکر شده است. با ارائه پارامتر pro به مقدار yes به عنوان ورودی، این محدودیت برای آن درخواست غیرفعال می‌شود. با این حال دقت کنید که محدودیت‌های حالت متداول برای جلوگیری از حالت‌های خاص و اشتباهات رایج تعبیه شده است و تنها در صورت نیاز و آگاهی از تبعات احتمالی آن، اقدام به فعال‌سازی حالت Pro نمایید.

سوالات متداول

سوالی در مورد لاگین و دریافت توکن دارم

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

آیا سهمتو محیط آزمایشی (Test) دارد؟

بله، شما میتوانید برای استفاده از کلیه امکانات بازار سهمتو و همچنین api ها از محیط آزمایشی سهمتو به آدرس‌های ذیل استفاده نمائید:

آدرس سهمتو آزمایشی : https://dev.sahmeto.com

آدرس api آزمایشی :https://dev.sahmeto.com

آیا برای استفاده از apiها محدودیتی وجود دارد؟

بله، برای مثال شما حتماً باید از IPهای ایران درخواست خود را ارسال نمائید، و یا محدودیت‌های مخصوص به هر api که در توضیحات هر کدام از endpointها آورده شده است.

فرمت استفاده شده برای تاریخ چیست؟

ساعت یونیکس Unix Time یکی از مقیاس اندازه‌گیری زمان آنی است. این عدد که تعداد ثانیه‌ها از ساعت ۰۰:۰۰:۰۰ ساعت هماهنگ جهانی اول ژانویه ۱۹۷۰ است، شامل ثانیه‌های کبیسه نمی‌شود. برای زمان‌های قبل از اول ژانویه از اعداد منفی استفاده می‌شود.

به عنوان مثال [۰۱/۰۱/۱۹۷۰ ۰۰:۰۰:۰۰] برابر با صفر (۰) و [۰۱/۰۱/۱۹۷۰ ۰۰:۰۱:۰۰] برابر با شصت(۶۰) است.

فرمول اصلی آن به این صورت می‌باشد:

تعداد (روزهای گذشته از اول ژانویه ۱۹۷۰) × ۸۶۴۰۰(تعداد ثانیه‌های هر روز)

به منظور مطالعه بیشتر به آدرس زیر مراجعه نمائید https://en.wikipedia.org/wiki/Unix_time

آیا برای apiها کدهای نمونه تهیه شده است؟

بله، collection کلیه api ها برای استفاده در برنامه postman تهیه و از اینجا میتوانید به آن دسترسی داشته باشید. در این collection شما میتوانید نمونه فراخوانی هر کدام از این apiها را به زبان‌های مختلف برنامه نویسی نظیر پی اچ پی، پایتون، سی شارپ و … در این مجموعه مشاهده کرده و آن را در سیستم خود اجرا نمائید.

shell plaintext