שלך
מפתחים

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 שנותן את שם הכלי שלך אינו חובה, אבל כך נוכל לעדכן אותך על שינוי במקום שיהיה צורך לנחש מה השתבש.