Każdy pool HeroMiners odpowiada na ten sam zestaw endpointów HTTP tylko do odczytu. Nie jest potrzebny klucz, konto ani rejestracja: wystarczy zapytać o URL, a odpowiedzią jest JSON z nagłówkiem Access-Control-Allow-Origin: *, dzięki czemu strona w przeglądarce może wywołać go bezpośrednio. Można w ten sposób zbudować monitor koparek, powiadomienia o wypłatach, własny panel albo pobrać dane poola do arkusza kalkulacyjnego.
Każda moneta ma własny pool z własnymi liczbami i własnym formatem adresu, dlatego należy najpierw wybrać monetę, a potem wpisać adres tej monety. Nic, co zostanie tu wpisane, nie trafia nigdzie poza samym poolem, i to tylko po naciśnięciu Uruchom.
Bazowy URL
https://alephium.herominers.com
Endpointy
GET/api/stats
Wszystko, co pool wie o sobie w tej chwili: hashrate poola i sieci, połączeni górnicy i workery, ostatni blok, opłaty, porty i ustawienia wypłat.
Parametry
address
Adres wypłat. Dodaje tego górnika w miner, a także w solo_miner, jeśli kopie również solo. Bez niego żaden z tych kluczy nie jest wysyłany.
Od tego endpointu warto zacząć. Strona poola, strona górników i każdy wykres na tej stronie są zbudowane na jego podstawie.
Żądanie
curl "https://alephium.herominers.com/api/stats"
Odpowiedź
Obiekt z polami pool, network, config, charts, lastblock, payments i visitors (ile osób jest teraz na stronie) w postaci { windowMinutes, activeVisitors, activeLookups }. Przeliczany raz na cykl statystyk, więc częstsze odpytywanie zwraca te same liczby.
GET/api/live_stats
Te same dane co /api/stats, ale żądanie jest trzymane otwarte do końca następnego cyklu statystyk i dopiero wtedy dostaje odpowiedź. Jedno żądanie na aktualizację zamiast odpytywania według zegara.
Parametry
address
Dołącza górnika do odpowiedzi, tak jak w /api/stats.
Należy otworzyć jedno połączenie i otwierać je ponownie po każdej odpowiedzi. Kilka jednoczesnych połączeń z tego samego IP jest odrzucanych z kodem 503, więc nie należy ich mnożyć.
Ta sama struktura co /api/stats, z tą różnicą, że miner i solo_miner są wysyłane zawsze i są puste, gdy nie podano adresu. Żądanie pozostaje otwarte najwyżej przez jeden cykl statystyk.
GET/api/stats_address
Jeden górnik: bieżący i średni hashrate, poprawne i przestarzałe share'y, saldo, wypłacona kwota oraz te same dane dla każdego workera.
Aby je uruchomić, należy wpisać address powyżej. Polecenie to pokazuje, ponieważ bez tego pool odpowiada błędem.
Odpowiedź
Obiekt z polami stats (sumy górnika), payments, charts, unlocked i workers, czyli tablicą z jednym wpisem na workera, nazwanym według jego name. Dla adresu, który nigdy tu nie kopał, zwracany jest błąd, a nie pusty górnik.
GET/api/get_blocks
Bloki znalezione przez pool, które nie czekają już na potwierdzenie: wypłacone albo osierocone. Który to przypadek, mówi status.
Parametry
heightwymagane
Zwraca bloki poniżej tej wysokości. Dla najnowszej strony należy podać liczbę znacznie powyżej czubka łańcucha, a potem najniższą otrzymaną wysokość, aby przewijać wstecz.
Adres znalazcy jest maskowany, zanim opuści pool, więc tego endpointu nie da się użyć do zbierania adresów. time to sekundy Unix, reward jest w najmniejszej jednostce monety, a blok solo ma score równe s0, gdy został wypłacony, lub s1, gdy został osierocony.
Wypłaty wysłane przez pool, dla całego poola albo dla jednego adresu.
Parametry
timewymagane
Zwraca wypłaty sprzed tego znacznika czasu Unix w sekundach. Dla najnowszej strony należy podać bieżący czas, a potem najstarszy otrzymany znacznik, aby przewijać wstecz.
address
Ogranicza wynik do jednego adresu wypłat. Bez niego zwracane są wszystkie wypłaty poola.
limit
Ile wpisów zwrócić. Ograniczone do rozmiaru strony samego poola, więc większa liczba po prostu zwraca ten rozmiar.
format
Podanie parsed zwraca obiekty { tx, amount, time } zamiast surowej tablicy.
conversions
Razem z address podanie 1 zwraca też zapis konwersji każdej wypłaty na stronie, która została przeliczona na inną monetę. Odpowiedź ma wtedy postać { payments, conversions }. Ignorowane przy format=parsed.
Bez format jest to płaska tablica, w której na przemian występują wartość i znacznik czasu, a każda wartość ma postać txid:amount. Kwoty są ciągami znaków w najmniejszej jednostce monety i muszą nimi pozostać: zamiana na liczbę traci precyzję na łańcuchu z 18 miejscami po przecinku.
GET/api/get_miners_stats
Dziesięciu największych górników poola oraz podział według programów do kopania i regionów, na którym opiera się strona górników.
Obiekt z polami miners, agents, regions, regionHistory i statsDisplay. Adresy są maskowane. Gdy panel nie jest włączony, jego tablica wraca pusta, a statsDisplay o tym informuje.
GET/api/get_blocks_search
Wyszukiwanie bloków poola po wysokości, hashu bloku lub adresie znalazcy, jednocześnie wśród bloków oczekujących i wypłaconych.
Parametry
qwymagane
Wysokość, hash bloku lub adres.
offset
Pomija tyle wyników. Odpowiedź zawiera hasMore, dzięki czemu wiadomo, czy pytać dalej.
Wyszukiwanie ma limit zapytań na IP, a jego przekroczenie zwraca rateLimited z dokładnym czasem oczekiwania w retryMs zamiast samego błędu. Najpierw warto wywołać /api/get_blocks_search_config, aby poznać dopuszczalną długość zapytania i sprawdzić, czy wyszukiwanie jest w ogóle włączone.
Aby je uruchomić, należy wpisać q powyżej. Polecenie to pokazuje, ponieważ bez tego pool odpowiada błędem.
Odpowiedź
Obiekt z polami pending i matured, w obu wartość występuje na przemian z wysokością jak w /api/get_blocks, a do tego totalMatched, offset, limit i hasMore. Blok z matured ma format /api/get_blocks; blok z pending wciąż czeka na dojrzenie i używa dłuższego formatu bloków oczekujących, więc jego pola są w innej kolejności.
GET/api/get_blocks_search_config
Czy wyszukiwanie bloków jest włączone i w jakich granicach musi się mieścić zapytanie, aby pole wyszukiwania dało się przygotować przed pierwszym wyszukiwaniem.
{ enabled, minQueryLength, maxQueryLength, frontendCooldownMs }. Długości są podane w znakach, a frontendCooldownMs to czas oczekiwania między dwoma wyszukiwaniami.
GET/api/get_miner_payout_level
Próg wypłaty ustawiony obecnie dla adresu, w całych monetach.
Parametry
addresswymagane
Adres wypłat.
Odpowiadający mu /api/set_miner_payout_level go zapisuje i nie jest dostępny dla każdego: żądanie musi przyjść z IP, z którego kopie ten adres. Ta kontrola i limit zapytań przed nią są opisane na karcie ustawień panelu, a nie tutaj.
Aby je uruchomić, należy wpisać address powyżej. Polecenie to pokazuje, ponieważ bez tego pool odpowiada błędem.
Odpowiedź
{ banned, minerMessage }, a przy blokadzie także blockMining, blockPayments i reason. To komunikat, który strona górnika pokazuje dla tego adresu: zablokowane kopanie, wypłaty albo nic. minerMessage to wiadomość operatora dla tego adresu w postaci { message, type, createdAt, expiresAt } lub null, gdy jej nie ma.
Dobre praktyki
Odpytywanie w rytmie poola. Liczby są przeliczane raz na cykl statystyk, a config.updateInterval w odpowiedzi /api/stats podaje jego długość w sekundach. Częstsze pytanie zwraca tę samą odpowiedź i zużywa transfer po obu stronach.
/api/live_stats zamiast szybkiego zegara. Odpowiada w chwili, gdy pojawi się coś nowego, co jest zarówno szybsze dla klienta, jak i lżejsze dla poola niż odpytywanie.
Kwoty jako ciągi znaków. Nagrody i salda wracają w najmniejszej jednostce monety. Na łańcuchu z 18 miejscami po przecinku takie liczby całkowite przekraczają to, co liczba w JavaScript może przechować dokładnie, więc zamiana na liczbę po cichu zaokrągla wypłatę.
Adresy są maskowane. Publiczne listy ukrywają środek każdego adresu. Pełny adres jest potrzebny tylko jego właścicielowi i tylko tam, gdzie sam go poda.
Limit zapytań to czekanie, a nie awaria. Tam, gdzie obowiązuje limit, odpowiedź zawiera retryMs. Należy odczekać tyle czasu i ponowić żądanie, zamiast zasypywać pool zapytaniami.
Warto się przedstawić. Nagłówek User-Agent z nazwą narzędzia nie jest wymagany, ale dzięki niemu możemy poinformować o zmianie, zamiast zgadywać, co się zepsuło.