Référence API AxeOS : chaque endpoint d’ESP-Miner v2.14.2, vérifié depuis la source

Chaque Bitaxe sert une API HTTP complète et non authentifiée sur le port 80 — la même API que le tableau de bord AxeOS utilise lui-même. Cette page est la référence endpoint par endpoint de cette API, épinglée à ESP-Miner v2.14.2 (la version courante, publiée le 2026-07-08). Chaque chemin, méthode, champ de requête et forme de réponse ci-dessous a été re-dérivé de la source à ce tag — main/http_server/http_server.c et main/http_server/openapi.yaml — pas d’un autre article. La branche master bouge; cette page nomme son tag pour que vous puissiez lui demander des comptes.

Portée : ceci est une référence, pas un tutoriel. Pour les flux de travail — méthodologie d’overclocking, stratégie multi-pool, durcissement réseau, planification OTA — utilisez le guide AxeOS configuration avancée : API, overclocking, sécurité et mises à jour OTA; et pour chaque paramètre de l’interface web expliqué un par un, le guide complet AxeOS — cette page ne réenseignera ni l’un ni l’autre. Si vous cherchez l’API DCENT_OS, c’est un produit différent avec sa propre surface (REST, WebSocket, cgminer 4028, MCP) — voir la référence API DCENT_OS. Nouveau avec l’appareil lui-même? Commencez par le guide Bitaxe.

Aller à : conventions · index des endpoints · endpoints de lecture · actions · réglages PATCH · OTA · WebSockets · surveillance · la règle du réseau local

Conventions : URL de base, authentification, erreurs

• URL de base : http://<device-ip> — HTTP simple sur le port 80. Les exemples ci-dessous utilisent 192.168.1.45; si mDNS fonctionne sur votre réseau, le nom d’hôte de l’appareil (défaut affiché dans les réglages AxeOS) se résout en http://<hostname>.local.
• Authentification : aucune. Pas de mot de passe, pas de jeton, pas de clé API. La seule barrière est une vérification de plage réseau (section suivante).
• Types de contenu : JSON en entrée et en sortie pour la famille /api/system, sauf /api/system/logs (texte brut) et les deux endpoints de téléversement OTA (application/octet-stream).
• CORS : le serveur répond aux pré-vérifications OPTIONS /api/* et met Access-Control-Allow-Origin: *, donc les tableaux de bord du réseau local servis depuis un autre hôte peuvent appeler l’API depuis le navigateur.
• Réponses d’erreur : 401 — la requête a échoué à la vérification de plage réseau (ci-dessous); 400 — corps de réglages invalide ou fichier firmware invalide; 500 — erreur interne. Documenté par endpoint dans l’openapi.yaml du dépôt.

La règle du réseau local (Vérifié dans la source) : les endpoints /api/system ne répondent que lorsque à la fois l’IP demandeuse et l’en-tête Origin du navigateur (quand présent) tombent dans les plages privées RFC-1918 — 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (is_network_allowed et ip_in_private_range dans http_server.c). Tout le reste reçoit 401 Unauthorized — y compris des appels bien intentionnés qui arrivent avec une adresse source non privée, comme certaines configurations de VPN ou de réseau superposé. Quand l’appareil est en mode AP (configuration initiale), la vérification est suspendue. Ce comportement de vérification d’origine est le descendant du correctif CSRF livré par ESP-Miner dans la v2.5.0 (janvier 2025, correctif de @benjamin-wilson, notes de version) — un fait de changelog utile quand vous lisez de vieux articles sur l’API.

Index des endpoints — tout ce qui est enregistré à v2.14.2

Les routes /api/* non appariées tombent sur un gestionnaire fourre-tout, et tout autre GET sert l’application monopage AxeOS.

Ajouté après v2.14.2 (branche master, pas au tag) : PUT /api/system/pools/* et DELETE /api/system/pools/* (une paire CRUD de liste de pools) et POST /api/system/boot existent dans la master courante mais ne sont pas enregistrés à v2.14.2 — sur cette version, les changements de pool passent par PATCH /api/system. Inversement, des endpoints qui apparaissent dans de la documentation plus ancienne — POST /api/system/factoryreset, GET /api/system/statistics/dashboard — ne sont pas enregistrés à v2.14.2 non plus. Si un script dépend de l’un d’eux, testez contre votre version installée avant de faire confiance à un article, celui-ci inclus.

Endpoints de lecture

GET /api/system/info — le cheval de trait. Retourne un gros objet JSON; le schéma dans openapi.yaml liste plus de 80 champs. Ceux qui intéressent la plupart des scripts :

curl -s http://192.168.1.45/api/system/info | jq .
# or just the fields you chart:
curl -s http://192.168.1.45/api/system/info | jq '{hashRate, temp, vrTemp, power, sharesAccepted}'

GET /api/system/asic — l’enveloppe de réglage. Retourne la puce détectée et les listes d’options exactes qu’AxeOS offre lui-même, pour que les scripts n’aient jamais à coder en dur les valeurs valides :

curl -s http://192.168.1.45/api/system/asic | jq .

Forme de la réponse (exemples de champs tirés de la spécification) : ASICModel (parmi BM1366, BM1368, BM1370, BM1397), deviceModel (p. ex. "Ultra"), asicCount, defaultFrequency / frequencyOptions (MHz), defaultVoltage / voltageOptions (mV), et swarmColor. Tout ce que vous prévoyez écrire par PATCH dans frequency ou coreVoltage devrait venir de ces listes.

GET /api/system/statistics — l’historique sur l’appareil. Retourne currentTimestamp, un tableau labels et un tableau statistics de rangées de points de données correspondant à ces étiquettes. Le paramètre de requête columns sélectionne les séries (séparées par des virgules); la liste d’exemple de la spécification elle-même : hashrate, hashrate_1m, hashrate_10m, hashrate_1h, asicTemp, vrTemp, asicVoltage, voltage, power, current, fanSpeed, fanRpm, fan2Rpm, wifiRssi, freeHeap, responseTime. La cadence d’échantillonnage est le réglage statsFrequency (secondes; 0 désactive), et statsLimit dans l’objet info rapporte la profondeur du tampon.

curl -s 'http://192.168.1.45/api/system/statistics?columns=hashrate,asicTemp,power' | jq .

GET /api/system/scoreboard — les 20 meilleures parts par difficulté, chacune avec rank, since (secondes écoulées), difficulty, et les composantes brutes de la part (job_id, extranonce2, ntime, nonce, version_bits). L’endpoint médaille d’honneur.

GET /api/system/wifi/scan — les réseaux à proximité en objets {ssid, rssi, authmode}, authmode étant le code de mode d’authentification ESP-IDF (0 = ouvert, jusqu’aux variantes WPA3). GET /api/system/logs — le tampon de journaux courant en téléchargement texte brut :

curl -s http://192.168.1.45/api/system/logs -o bitaxe-logs.txt

Endpoints d’action

Les quatre sont des POST sans paramètre répondant {"message": "..."} :

curl -s -X POST http://192.168.1.45/api/system/restart   # reboot; replies "System will restart shortly."
curl -s -X POST http://192.168.1.45/api/system/identify  # the unit says hi (find it on a crowded shelf)
curl -s -X POST http://192.168.1.45/api/system/pause     # stop hashing without powering off
curl -s -X POST http://192.168.1.45/api/system/resume    # start hashing again

L’endpoint de redémarrage est celui qui gagne sa vie : c’est le déclencheur derrière le chien de garde à redémarrage automatique du Bitaxe qui récupère automatiquement les unités figées. POST /api/system/blockFound/dismiss efface la bannière de bloc trouvé tout en préservant le compte blockFound — le seul endpoint que vous espérez avoir besoin d’appeler.

Écrire les réglages : PATCH /api/system

Un seul endpoint écrit chaque réglage persistant. Envoyez un objet JSON contenant seulement les clés que vous voulez changer; elles sont validées contre le schéma Settings (les valeurs invalides retournent 400) et persistées en NVS. Deux choses à savoir avant de le scripter : le schéma met additionalProperties: true, donc une clé inconnue (mal orthographiée) n’est pas rejetée — orthographiez les clés exactement; et les champs de classe mot-de-passe (stratumPassword, fallbackStratumPassword, wifiPass) sont en écriture seule — ils n’apparaissent jamais dans GET /api/system/info.

Changer le pool primaire (valeurs calquées sur les propres exemples de la spécification) :

curl -s -X PATCH http://192.168.1.45/api/system \
  -H 'Content-Type: application/json' \
  -d '{"stratumURL":"stratum+tcp://pool.example.com","stratumPort":3333,"stratumUser":"worker1","stratumPassword":"x"}'

Activer Stratum V2 sur le pool primaire, en gardant un secours V1 (la v2.14.0 a ajouté le SV2 natif avec les quatre combinaisons de protocoles primaire/secours) :

curl -s -X PATCH http://192.168.1.45/api/system \
  -H 'Content-Type: application/json' \
  -d '{"stratumProtocol":"SV2","stratumV2AuthorityPubkey":"<POOL_PUBLIC_KEY>","fallbackStratumProtocol":"SV1"}'

Deux notes honnêtes sur les champs SV2. Premièrement, le schéma énumère les deux types de canaux standard et extended — et à v2.14.2 les deux sont implémentés : extended est le défaut, et sur les puces BM1397 le firmware force le canal étendu (la puce n’a pas le version rolling matériel), donc stratumV2ChannelType: "standard" n’est honoré que sur les puces non-BM1397 (vérifié au tag : main/tasks/stratum_v2_task.c). Il n’y a pas de client Job Declarator à ce tag dans un cas comme dans l’autre — SV2 sur un Bitaxe signifie un minage chiffré et à cadrage binaire, pas la construction de vos propres gabarits de bloc; même sur les canaux étendus, c’est le pool qui fournit le gabarit. Deuxièmement, la pubkey d’autorité est celle de votre pool — copiez-la caractère par caractère depuis la propre documentation du pool, jamais depuis une page tierce. La configuration de pool pas à pas, les endpoints et la vérification vivent dans le guide compagnon : activer Stratum V2 sur un Bitaxe. Pour la méthodologie de réglage — quoi changer, dans quel ordre, et comment le valider — utilisez le guide de configuration avancée; un redémarrage (POST /api/system/restart) après des changements de réglages est la façon fiable de s’assurer que chaque sous-système les prend en compte, et c’est ce que font les flux de travail du guide compagnon.

Endpoints OTA : firmware et interface web

Les mises à jour AxeOS sont deux fichiers par version, et l’API reflète cela : POST /api/system/OTA prend l’image firmware (esp-miner.bin), POST /api/system/OTAWWW prend l’image de l’interface web (www.bin). Les deux acceptent le binaire brut en application/octet-stream et répondent en texte brut; l’endpoint firmware valide le téléversement, change la partition de démarrage, répond "Firmware update complete, rebooting now!" et redémarre. Un mauvais fichier retourne 400.

# from the directory holding the release assets for YOUR board:
curl -s -X POST http://192.168.1.45/api/system/OTAWWW \
  -H 'Content-Type: application/octet-stream' --data-binary @www.bin
curl -s -X POST http://192.168.1.45/api/system/OTA \
  -H 'Content-Type: application/octet-stream' --data-binary @esp-miner.bin

Note de flux de travail : prenez les deux fichiers de la même version pour que le firmware et l’interface restent synchronisés, et mettez à jour l’interface d’abord, le firmware ensuite — le téléversement du firmware redémarre l’appareil, celui de l’interface non, donc cet ordre se termine proprement en une passe. L’appareil fonctionne en partitions A/B; runningPartition dans l’objet info vous dit quel emplacement a démarré. Les téléchargements et les noms de fichiers par carte sont sur la page des versions d’ESP-Miner.

Endpoints de thème

GET /api/theme retourne {"colorScheme": ..., "accentColors": {...}}; POST /api/theme accepte la même forme et la persiste. C’est ainsi que l’interface AxeOS stocke son apparence; les scripts en ont rarement besoin, mais cela fait partie de la surface enregistrée et a sa place dans une référence complète.

Flux WebSocket

Deux endpoints WebSocket partagent un gestionnaire mais diffusent des choses différentes (Vérifié dans la source — les enregistrements portent des types de flux différents) :

• /api/ws — le flux de journaux. Des trames texte contenant la sortie des journaux de l’appareil, drainées du tampon circulaire embarqué seulement tant qu’au moins un client est connecté. C’est le flux derrière le visualiseur de journaux d’AxeOS.
• /api/ws/live — le flux de télémétrie. Des trames JSON de la forme {"event": "update", "data": {...}} où data est un diff contre le dernier état envoyé, limité à une mise à jour par 500 ms. Le premier message après la connexion porte l’état complet; ensuite vous ne recevez que les champs qui ont changé. Pour les tableaux de bord, cela bat l’interrogation : pas de surcharge de requête, et pas d’octets gaspillés sur des champs inchangés.

# websocat (or any WS client):
websocat ws://192.168.1.45/api/ws/live   # telemetry diffs
websocat ws://192.168.1.45/api/ws        # live logs

Recette de surveillance : /api/system/info → Prometheus → Grafana

Le patron qui fonctionne : interroger /api/system/info à intervalle, traduire les champs qui vous intéressent en métriques Prometheus, tracer dans Grafana. Ce qui suit est un croquis délibérément petit — la version collecteur textfile de node_exporter, aucun démon exporteur à maintenir. Sauvegardez sous axeos-textfile.sh et lancez-le par cron (ou une minuterie systemd) toutes les 30–60 secondes sur une machine qui exécute déjà node_exporter avec --collector.textfile.directory configuré :

#!/usr/bin/env bash
# axeos-textfile.sh - one Bitaxe -> node_exporter textfile collector. A sketch, not a product.
IP=192.168.1.45
OUT=/var/lib/node_exporter/textfile_collector/bitaxe.prom
J=$(curl -sf --max-time 5 "http://${IP}/api/system/info") || exit 1
{
  echo "bitaxe_hashrate_ghs $(jq .hashRate <<<"$J")"
  echo "bitaxe_temp_celsius $(jq .temp <<<"$J")"
  echo "bitaxe_vr_temp_celsius $(jq .vrTemp <<<"$J")"
  echo "bitaxe_power_watts $(jq .power <<<"$J")"
  echo "bitaxe_shares_accepted $(jq .sharesAccepted <<<"$J")"
  echo "bitaxe_shares_rejected $(jq .sharesRejected <<<"$J")"
  echo "bitaxe_uptime_seconds $(jq .uptimeSeconds <<<"$J")"
} > "${OUT}.tmp" && mv "${OUT}.tmp" "$OUT"

Notes honnêtes en bas du croquis : les compteurs de parts se remettent à zéro à chaque redémarrage, alors traitez-les dans Grafana avec des fonctions tolérantes aux resets (increase() / resets()) plutôt que des deltas bruts; pour plusieurs Bitaxe, ajoutez une étiquette par appareil (bitaxe_hashrate_ghs{unit="45"} ...) et bouclez sur les IP; et si vous préférez le flux à l’interrogation, /api/ws/live ci-dessus est le meilleur transport pour un exporteur maison. L’historique embarqué via /api/system/statistics est l’alternative zéro-infrastructure quand tout ce que vous voulez est un graphique du passé récent. Le scriptage à l’échelle de la flotte sur cette même API — réglage par lots, séries de comparaison — est couvert dans le guide des scripts d’auto-réglage Bitaxe, et les quatre lignes de surveillance à plus haute valeur que vous puissiez déployer restent le chien de garde à redémarrage automatique.

Gardez-la sur le réseau local

Pratique d’exploitation standard pour une API d’appareil non authentifiée, énoncée une fois et calmement : n’exposez jamais un Bitaxe à Internet. Pas de redirection de port vers lui, pas de DMZ. La vérification de plage privée du firmware refuse les appelants non RFC-1918, et c’est un plancher, pas une architecture de sécurité — traitez le placement réseau comme le vrai contrôle. Sur un réseau domestique, un VLAN IoT isolé (ou au minimum l’isolation de clients de votre routeur pour les appareils non fiables) garde le mineur joignable depuis votre machine de surveillance et rien d’autre; si vous avez besoin de visibilité à distance, rejoignez le réseau local par votre propre VPN et appelez l’API de l’intérieur — en vous rappelant que la règle du réseau local signifie que l’API voit l’adresse source de votre client VPN, qui doit tomber dans une plage privée pour passer. Le parcours complet de durcissement (réservations DHCP, plan de VLAN, patrons d’accès à distance) est dans le guide de configuration avancée.

FAQ

L’API AxeOS exige-t-elle un mot de passe ou une clé API?

Non. Il n’y a aucune authentification d’aucune sorte — par conception, pour un appareil de réseau local. La seule barrière est la vérification de plage réseau du firmware : les requêtes (et les Origins du navigateur) doivent venir d’adresses privées RFC-1918. C’est exactement pourquoi l’API ne doit jamais être joignable depuis Internet.

Pourquoi l’API du Bitaxe retourne-t-elle 401 Unauthorized?

Votre requête a échoué à la vérification de plage privée dans is_network_allowed : soit l’IP source, soit l’en-tête Origin du navigateur se résout hors de 10.0.0.0/8, 172.16.0.0/12 ou 192.168.0.0/16. Causes typiques : appeler à travers un VPN ou un réseau superposé qui présente une adresse source non privée, un NAT qui réécrit la source, ou une origine de navigateur passant par un proxy. Appelez depuis une machine sur le même réseau local privé.

Quel endpoint AxeOS un tableau de bord devrait-il interroger?

GET /api/system/info — il porte le hashrate (avec moyennes 1 m/10 m/1 h), les températures, la puissance, les parts, l’état du pool et la santé de l’appareil dans un seul objet. Pour du push au lieu du poll, connectez-vous au WebSocket /api/ws/live, qui envoie des diffs JSON au plus toutes les 500 ms et ne coûte rien entre les changements.

Puis-je configurer Stratum V2 par l’API AxeOS?

Oui, sur ESP-Miner v2.14.0 ou plus récent : PATCH /api/system avec stratumProtocol: "SV2" et optionnellement la stratumV2AuthorityPubkey de votre pool (base58, jusqu’à 52 caractères); le pool de secours a des champs miroirs et toute combinaison V1/V2 fonctionne. Les deux types de canaux sont implémentés à v2.14.2 — stratumV2ChannelType a extended pour défaut, et les puces BM1397 sont forcées en extended — et il n’y a pas de client Job Declarator : SV2 sur un Bitaxe chiffre et recadre votre connexion de minage; il ne construit pas de gabarits de bloc. Configuration complète : activer Stratum V2 sur un Bitaxe.

Puis-je ajouter ou supprimer des pools par l’API AxeOS?

Pas à v2.14.2. La paire PUT /api/system/pools/* et DELETE /api/system/pools/* apparaît sur la branche master après le tag v2.14.2 et n’est pas enregistrée dans le build v2.14.2 — sur cette version, changez les pools avec PATCH /api/system. Si votre appareil exécute une version plus récente, vérifiez sa propre source ou ses notes de version avant de scripter contre eux.

Crédits

Cette API est l’œuvre des mainteneurs et contributeurs d’ESP-Miner — Skot, WantClue, mutatrum et la communauté bitaxeorg au sens large (GPL-3.0). Les champs Stratum V2 existent grâce à la PR #1553 de @warioishere; la protection d’origine réseau remonte au correctif CSRF v2.5.0 de @benjamin-wilson. Le wiki d’Open Source Miners United maintenait une liste communautaire des endpoints avant que cette page existe — crédit à qui de droit, et elle reste une bonne consultation rapide. Vérification endpoint par endpoint contre le tag v2.14.2 par D-Central.

Dernière vérification du dossier : 2026-08-13. Chaque endpoint, champ et contrainte de cette page a été re-dérivé de la source d’ESP-Miner au tag v2.14.2 (main/http_server/http_server.c, openapi.yaml, theme_api.c, websocket_api.c, websocket_log.c, main/tasks/stratum_v2_task.c) à cette date.