شما
توسعه‌دهندگان

API استخر

همه استخرهای HeroMiners به یک مجموعه یکسان از اندپوینت‌های HTTP فقط‌خواندنی پاسخ می‌دهند. نه کلیدی لازم است، نه حساب کاربری و نه ثبت‌نام: یک URL را درخواست می‌کنید و JSON دریافت می‌کنید، همراه با Access-Control-Allow-Origin: * تا یک صفحه در مرورگر بتواند مستقیماً آن را فراخوانی کند. از آن برای ساخت ابزار پایش دستگاه استخراج، اعلان‌گر پرداخت، داشبورد شخصی خود یا انتقال داده‌های استخر به یک صفحه‌گسترده استفاده کنید.

آدرس خود را وارد کنید تا همه مثال‌های زیر برای اجرا روی این استخر آماده شوند. هر چه اینجا تایپ کنید فقط به خود استخر فرستاده می‌شود و تنها زمانی که «اجرا» را بزنید.

URL پایه
https://quantus.herominers.com

اندپوینت‌ها

GET /api/stats

هر آنچه استخر در این لحظه درباره خودش می‌داند: هش‌ریت استخر و شبکه، ماینرها و ورکرهای متصل، آخرین بلاک، کارمزدها، پورت‌ها و تنظیمات پرداخت.

پارامتر
address
یک آدرس پرداخت. آن ماینر را زیر miner اضافه می‌کند و اگر استخراج انفرادی هم انجام دهد، زیر solo_miner. اگر آن را حذف کنید، هیچ‌یک از این دو کلید فرستاده نمی‌شود.

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

درخواست 
curl "https://quantus.herominers.com/api/stats"
پاسخ

یک شیء با pool، network، config، charts، lastblock، payments و visitors، یعنی تعداد افرادی که همین حالا در سایت هستند، به شکل { windowMinutes, activeVisitors, activeLookups }. در هر چرخه آمار یک بار دوباره محاسبه می‌شود، پس درخواست‌های سریع‌تر از آن همان اعداد را برمی‌گردانند.

GET /api/live_stats

همان داده‌های /api/stats، اما درخواست تا پایان چرخه آمار بعدی باز می‌ماند و سپس پاسخ داده می‌شود. یک درخواست برای هر به‌روزرسانی، به جای درخواست‌های پیاپی با تایمر.

پارامتر
address
یک ماینر را در پاسخ بگنجانید، مانند /api/stats.

یک اتصال باز کنید و پس از دریافت پاسخ دوباره آن را باز کنید. چند اتصال هم‌زمان از یک IP با خطای 503 رد می‌شوند، پس درخواست‌های موازی نفرستید.

درخواست 
curl "https://quantus.herominers.com/api/live_stats"
پاسخ

همان ساختار /api/stats، با این تفاوت که miner و solo_miner همیشه فرستاده می‌شوند و اگر آدرسی داده نشده باشد خالی هستند. درخواست حداکثر به اندازه یک چرخه آمار باز می‌ماند.

GET /api/stats_address

یک ماینر: هش‌ریت فعلی و میانگین، شیرهای معتبر و منقضی، موجودی، مبلغ پرداخت‌شده و همین ارقام برای هر ورکر.

پارامتر
addressالزامی
آدرس پرداختی که می‌خواهید بررسی کنید.
درخواست 
curl "https://quantus.herominers.com/api/stats_address"

برای اجرای این درخواست، address را در بالا وارد کنید. فرمان آن را نشان می‌دهد چون استخر بدون آن با خطا پاسخ می‌دهد.

پاسخ

یک شیء با stats (مجموع‌های ماینر)، payments، charts، unlocked و workers، آرایه‌ای با یک ورودی برای هر ورکر که با name آن نام‌گذاری شده است. آدرسی که هرگز اینجا استخراج نکرده باشد به جای یک ماینر خالی، خطا دریافت می‌کند.

GET /api/get_blocks

بلاک‌هایی که استخر پیدا کرده و دیگر در انتظار نیستند: پرداخت‌شده یا یتیم. status مشخص می‌کند کدام.

پارامتر
heightالزامی
بلاک‌های پایین‌تر از این ارتفاع را برمی‌گرداند. برای جدیدترین صفحه عددی بسیار بالاتر از نوک زنجیره بفرستید، سپس برای رفتن به صفحه‌های قبلی کمترین ارتفاعی را که دریافت کرده‌اید.

آدرس یابنده پیش از خروج از استخر پوشانده می‌شود، پس نمی‌توان از این اندپوینت برای جمع‌آوری آدرس‌ها استفاده کرد. time بر حسب ثانیه Unix است، reward در کوچک‌ترین واحد ارز است، و یک بلاک انفرادی اگر پرداخت شده باشد score برابر s0 و اگر یتیم شده باشد s1 دارد.

درخواست 
curl "https://quantus.herominers.com/api/get_blocks?height=9999999999"
پاسخ

یک آرایه تخت که به تناوب مقدار و ارتفاع را دارد: [block, height, block, height, ...]. هر بلاک با دونقطه جدا شده است:

0hash1time2difficulty3shares4score5nonce6status7reward8finder9region10rewardScheme
GET /api/get_payments

پرداخت‌هایی که استخر ارسال کرده است، برای کل استخر یا برای یک آدرس.

پارامتر
timeالزامی
پرداخت‌های پیش از این مُهر زمانی Unix بر حسب ثانیه را برمی‌گرداند. برای جدیدترین صفحه زمان فعلی را بفرستید، سپس برای رفتن به صفحه‌های قبلی قدیمی‌ترین مُهر زمانی که دریافت کرده‌اید.
address
محدود به یک آدرس پرداخت. برای همه پرداخت‌هایی که استخر انجام داده است آن را حذف کنید.
limit
تعداد مواردی که برگردانده می‌شود. به اندازه صفحه خود استخر محدود می‌شود، پس عدد بزرگ‌تر همان مقدار را برمی‌گرداند.
format
مقدار parsed را بفرستید تا به جای آرایه خام، اشیای { tx, amount, time } دریافت کنید.
conversions
همراه با address، مقدار 1 را بفرستید تا سابقه تبدیل هر پرداختی در این صفحه که به ارز دیگری تبدیل شده است را هم دریافت کنید. در این حالت پاسخ به { payments, conversions } تبدیل می‌شود. همراه با format=parsed نادیده گرفته می‌شود.
درخواست 
curl "https://quantus.herominers.com/api/get_payments?time=1792922073"
پاسخ

بدون format، یک آرایه تخت که به تناوب مقدار و مُهر زمانی را دارد و هر مقدار به شکل txid:amount است. مبلغ‌ها رشته‌هایی در کوچک‌ترین واحد ارز هستند و باید رشته بمانند: تبدیل آن‌ها به عدد در زنجیره‌ای با 18 رقم اعشار باعث از دست رفتن دقت می‌شود.

GET /api/get_miners_stats

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

درخواست 
curl "https://quantus.herominers.com/api/get_miners_stats"
پاسخ

یک شیء با miners، agents، regions، regionHistory و statsDisplay. آدرس‌ها پوشانده شده‌اند. وقتی یک بخش فعال نباشد آرایه آن خالی برمی‌گردد و statsDisplay این را اعلام می‌کند.

GET /api/get_blocks_search_config

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

درخواست 
curl "https://quantus.herominers.com/api/get_blocks_search_config"
پاسخ

{ enabled, minQueryLength, maxQueryLength, frontendCooldownMs }. طول‌ها بر حسب نویسه هستند و frontendCooldownMs مدت زمان انتظار بین دو جست‌وجو است.

GET /api/get_miner_payout_level

آستانه پرداختی که در حال حاضر برای یک آدرس تنظیم شده است، بر حسب ارز کامل.

پارامتر
addressالزامی
آدرس پرداخت.

اندپوینت متناظر /api/set_miner_payout_level آن را ثبت می‌کند و برای همه باز نیست: درخواست باید از IP استخراج خود آن آدرس بیاید. این بررسی و محدودیت نرخی که پیش از آن اعمال می‌شود در زبانه تنظیمات داشبورد توضیح داده شده‌اند، نه اینجا.

درخواست 
curl "https://quantus.herominers.com/api/get_miner_payout_level"

برای اجرای این درخواست، address را در بالا وارد کنید. فرمان آن را نشان می‌دهد چون استخر بدون آن با خطا پاسخ می‌دهد.

پاسخ

{ status: "done", level }. آدرسی که هرگز آن را تنظیم نکرده باشد حداقل استخر را دریافت می‌کند.

GET /api/miner_ban_status

اعلان مسدودیتی که صفحه ماینر برای یک آدرس نشان می‌دهد و هر پیامی که اپراتور برای آن گذاشته است.

پارامتر
addressالزامی
آدرس پرداخت.
درخواست 
curl "https://quantus.herominers.com/api/miner_ban_status"

برای اجرای این درخواست، address را در بالا وارد کنید. فرمان آن را نشان می‌دهد چون استخر بدون آن با خطا پاسخ می‌دهد.

پاسخ

{ banned, minerMessage }، و در صورت مسدود بودن، blockMining، blockPayments و reason هم. این همان اعلانی است که صفحه ماینر برای این آدرس نشان می‌دهد: مسدود از استخراج، از دریافت پرداخت، یا هیچ‌کدام. minerMessage پیام اپراتور به این آدرس است، به شکل { message, type, createdAt, expiresAt }، یا null وقتی پیامی وجود نداشته باشد.

استفاده درست

  • با زمان‌بندی خود استخر درخواست بفرستید. اعداد در هر چرخه آمار یک بار دوباره محاسبه می‌شوند و config.updateInterval در پاسخ /api/stats طول آن را بر حسب ثانیه نشان می‌دهد. درخواست‌های بیشتر از آن همان پاسخ را برمی‌گردانند و پهنای باند هر دو طرف را هدر می‌دهند.
  • /api/live_stats را به یک تایمر سریع ترجیح دهید. به محض اینکه چیز جدیدی باشد پاسخ می‌دهد، که هم برای شما سریع‌تر است و هم برای استخر سبک‌تر از درخواست‌های پیاپی.
  • مبلغ‌ها را به شکل رشته نگه دارید. پاداش‌ها و موجودی‌ها در کوچک‌ترین واحد ارز برگردانده می‌شوند. در زنجیره‌ای با 18 رقم اعشار، این اعداد صحیح از حدی که یک عدد JavaScript می‌تواند دقیق نگه دارد فراتر می‌روند، پس تبدیل آن‌ها به عدد بی‌صدا یک پرداخت را گرد می‌کند.
  • انتظار داشته باشید آدرس‌ها پوشانده شده باشند. فهرست‌های عمومی بخش میانی هر آدرس را پنهان می‌کنند. آدرس کامل شما را فقط خودتان لازم دارید، و فقط جایی که خودتان آن را وارد می‌کنید.
  • محدودیت نرخ را انتظار بدانید، نه شکست. جایی که محدودیتی اعمال شود، پاسخ شامل retryMs است. به همان اندازه صبر کنید و دوباره تلاش کنید، به جای اینکه پشت سر هم درخواست بفرستید.
  • خود را معرفی کنید. یک User-Agent که نام ابزار شما را بگوید الزامی نیست، اما به ما امکان می‌دهد درباره یک تغییر به شما خبر دهیم، به جای اینکه حدس بزنید چه چیزی خراب شده است.